a method to construct a conditional filter function for the list method

        :param metadata_filters: list with query criteria dictionaries
        :return: filter_function object

            NOTE:   query criteria architecture

                    each item in the metadata filters list must be a dictionary
                    which is composed of one or more key names which represent the
                    dotpath to a metadata element of the record to be queried with a
                    key value that is a dictionary of conditional operators used to
                    test the value in the corresponding metadata field of the record.

                    eg. path_filters = [ { '.file_name': { 'must_contain': [ '^lab' ] } } ]

                    this example filter looks in the file tree that is walked for a
                    file which starts with the characters 'lab'. as a result, it will
                    match both the following:
                        log/unittests/test/20160912/lab.json
                        laboratory20160912.json

            NOTE:   the filter method uses a query filters list structure to represent
                    the disjunctive normal form of a logical expression. a record is
                    added to the results list if any query criteria dictionary in the
                    list evaluates to true. within each query criteria dictionary, all
                    declared conditional operators must evaluate to true.

                    in this way, the metadata_filters represents a boolean OR operator and
                    each criteria dictionary inside the list represents a boolean AND
                    operator between all keys in the dictionary.

            NOTE:   each query_criteria uses the architecture of query declaration in
                    the jsonModel.query method

            query_criteria = {
                '.file_name': {},
                '.file_path': {},
                '.file_size': {},
                '.create_date': {},
                '.update_date': {},
                '.access_date': {}
            }

            conditional operators for '.file_name' and '.file_path' fields:
                "byte_data": false,
                "discrete_values": [ "" ],
                "excluded_values": [ "" ],
                "greater_than": "",
                "less_than": "",
                "max_length": 0,
                "max_value": "",
                "min_length": 0,
                "min_value": "",
                "must_contain": [ "" ],
                "must_not_contain": [ "" ],
                "contains_either": [ "" ]

            conditional operators for '.file_size', '.create_date', '.update_date', '.access_date':
                "discrete_values": [ 0.0 ],
                "excluded_values": [ 0.0 ],
                "greater_than": 0.0,
                "integer_data": false,
                "less_than": 0.0,
                "max_value": 0.0,
                "min_value": 0.0

def conditional_filter(self, metadata_filters):

        ''' a method to construct a conditional filter function for the list method

        :param metadata_filters: list with query criteria dictionaries
        :return: filter_function object

            NOTE:   query criteria architecture

                    each item in the metadata filters list must be a dictionary
                    which is composed of one or more key names which represent the
                    dotpath to a metadata element of the record to be queried with a
                    key value that is a dictionary of conditional operators used to
                    test the value in the corresponding metadata field of the record.

                    eg. path_filters = [ { '.file_name': { 'must_contain': [ '^lab' ] } } ]

                    this example filter looks in the file tree that is walked for a
                    file which starts with the characters 'lab'. as a result, it will
                    match both the following:
                        log/unittests/test/20160912/lab.json
                        laboratory20160912.json

            NOTE:   the filter method uses a query filters list structure to represent
                    the disjunctive normal form of a logical expression. a record is
                    added to the results list if any query criteria dictionary in the
                    list evaluates to true. within each query criteria dictionary, all
                    declared conditional operators must evaluate to true.

                    in this way, the metadata_filters represents a boolean OR operator and
                    each criteria dictionary inside the list represents a boolean AND
                    operator between all keys in the dictionary.

            NOTE:   each query_criteria uses the architecture of query declaration in
                    the jsonModel.query method

            query_criteria = {
                '.file_name': {},
                '.file_path': {},
                '.file_size': {},
                '.create_date': {},
                '.update_date': {},
                '.access_date': {}
            }

            conditional operators for '.file_name' and '.file_path' fields:
                "byte_data": false,
                "discrete_values": [ "" ],
                "excluded_values": [ "" ],
                "greater_than": "",
                "less_than": "",
                "max_length": 0,
                "max_value": "",
                "min_length": 0,
                "min_value": "",
                "must_contain": [ "" ],
                "must_not_contain": [ "" ],
                "contains_either": [ "" ]

            conditional operators for '.file_size', '.create_date', '.update_date', '.access_date':
                "discrete_values": [ 0.0 ],
                "excluded_values": [ 0.0 ],
                "greater_than": 0.0,
                "integer_data": false,
                "less_than": 0.0,
                "max_value": 0.0,
                "min_value": 0.0
        '''

    # validate input
        self.fields.validate(metadata_filters, '.metadata_filters')

    # construct function called by list function
        def query_function(**kwargs):
            file_metadata = {}
            for key, value in kwargs.items():
                if key in self.file_model.schema.keys():
                    file_metadata[key] = value
            for query_criteria in metadata_filters:
                if self.file_model.query(query_criteria, file_metadata):
                    return True
            return False

        return query_function