Filters

Filters typically have corresponding elasticsearch filters. ESFluent helps intelligently compose them and provides a common interface, via to_query() whose responsibility is to generate the corresponding elasticsearch filter dictionary.

A Filter can Geometry clean up data and also generate novel queries.

Basic Filters

class es_fluent.filters.Age(name, gte=None, lte=None, lt=None, gt=None)

Bases: es_fluent.filters.Dict

Similar to a range filter. Operates on times. When querified, we convert the age in seconds into a datetime relative to the current datetime.datetime.now().

add_filter(filter_or_string, *args, **kwargs)

Appends a filter.

and_filter(filter_or_string, *args, **kwargs)

Adds a list of And clauses, automatically generating And filter if it does not exist.

find_filter(filter_cls)

Find or create a filter instance of the provided filter_cls. If it is found, use remaining arguments to augment the filter otherwise create a new instance of the desired type and add it to the current QueryBuilder accordingly.

is_empty()

Returns:True if this filter has nested clauses False.

name = 'age'

or_filter(filter_or_string, *args, **kwargs)

Adds a list of Or clauses, automatically generating the an Or filter if it does not exist.

to_query()

class es_fluent.filters.And

Bases: es_fluent.filters.Generic

A multi-clause filter that ands’s all sub-filters added to it.

Elastic docs.

add_filter(filter_or_string, *args, **kwargs)

Appends a filter.

and_filter(filter_or_string, *args, **kwargs)

Adds a list of And clauses, automatically generating And filter if it does not exist.

find_filter(filter_cls)

Find or create a filter instance of the provided filter_cls. If it is found, use remaining arguments to augment the filter otherwise create a new instance of the desired type and add it to the current QueryBuilder accordingly.

is_empty()

Returns:True if this filter has nested clauses False.

name = 'and'

or_filter(filter_or_string, *args, **kwargs)

Adds a list of Or clauses, automatically generating the an Or filter if it does not exist.

to_query()

class es_fluent.filters.Custom(query)

Bases: es_fluent.filters.Terminal

Allows for an entirely custom dictionary to be used and passed verbatim when to_query is invoked.

add_filter(filter_instance)

As a Terminal filter, adding nested filters is not allowed.

find_filter(filter_cls)

As a Terminal filter, adding nested filters is not allowed and therefore, finding sub-filters is not supported.

name = 'custom'

to_query()

class es_fluent.filters.Dict

Bases: es_fluent.filters.Generic

Contains a generic dictionary of filters e.g. in a top level ES Query we may have:

{ "filtered": {"filter": {"and": {...}, "or": {...}, "exists": {...} }

The Dict filter may represent the dictionary inside of “filtered.filter”.

add_filter(filter_or_string, *args, **kwargs)

Appends a filter.

and_filter(filter_or_string, *args, **kwargs)

Adds a list of And clauses, automatically generating And filter if it does not exist.

find_filter(filter_cls)

Find or create a filter instance of the provided filter_cls. If it is found, use remaining arguments to augment the filter otherwise create a new instance of the desired type and add it to the current QueryBuilder accordingly.

is_empty()

Returns:True if this filter has nested clauses False.

name = None

or_filter(filter_or_string, *args, **kwargs)

Adds a list of Or clauses, automatically generating the an Or filter if it does not exist.

to_query()

Iterates over all filters and converts them to an Elastic HTTP API suitable query.

Note: each Filter is free to set it’s own filter dictionary. ESFluent does not attempt to guard against filters that may clobber one another. If you wish to ensure that filters are isolated, nest them inside of a boolean filter such as And or Or.

class es_fluent.filters.Exists(value)

Bases: es_fluent.filters.Terminal

Checks whether a field exists in the source document.

Elastic docs.

add_filter(filter_instance)

As a Terminal filter, adding nested filters is not allowed.

find_filter(filter_cls)

As a Terminal filter, adding nested filters is not allowed and therefore, finding sub-filters is not supported.

name = 'exists'

to_query()

class es_fluent.filters.Filter

Bases: object

The base filter.

name = None

The shorthand name of the filter.

to_query()

Serializes this Filter and any descendants into a json-serializable dictionary suitable for use with the elasticsearch api.

class es_fluent.filters.FilterRegistry

Bases: type

Metaclass used to automatically register new filter classes in our filter registry. Enables shorthand filter notation.

>>> from es_fluent.builder import QueryBuilder
>>> query_builder = QueryBuilder()
>>> query_builder.add_filter('missing', 'boop').to_query()['filter']
{'missing': {'field': 'field_name'}}

mro() → list

return a type’s method resolution order

class es_fluent.filters.Generic

Bases: es_fluent.filters.Filter

Contains a generic list of filters. Serialized as a dictionary.

add_filter(filter_or_string, *args, **kwargs)

Appends a filter.

and_filter(filter_or_string, *args, **kwargs)

Adds a list of And clauses, automatically generating And filter if it does not exist.

find_filter(filter_cls)

Find or create a filter instance of the provided filter_cls. If it is found, use remaining arguments to augment the filter otherwise create a new instance of the desired type and add it to the current QueryBuilder accordingly.

is_empty()

Returns:True if this filter has nested clauses False.

name = None

or_filter(filter_or_string, *args, **kwargs)

Adds a list of Or clauses, automatically generating the an Or filter if it does not exist.

to_query()

Serializes this Filter and any descendants into a json-serializable dictionary suitable for use with the elasticsearch api.

class es_fluent.filters.Missing(name)

Bases: es_fluent.filters.Terminal

Filters documents that to do not contain a given field.

Elastic docs.

add_filter(filter_instance)

As a Terminal filter, adding nested filters is not allowed.

find_filter(filter_cls)

As a Terminal filter, adding nested filters is not allowed and therefore, finding sub-filters is not supported.

name = 'missing'

to_query()

class es_fluent.filters.Not

Bases: es_fluent.filters.Dict

A filter that inverts it’s clauses.

Elastic docs.

add_filter(filter_or_string, *args, **kwargs)

Appends a filter.

and_filter(filter_or_string, *args, **kwargs)

Adds a list of And clauses, automatically generating And filter if it does not exist.

find_filter(filter_cls)

Find or create a filter instance of the provided filter_cls. If it is found, use remaining arguments to augment the filter otherwise create a new instance of the desired type and add it to the current QueryBuilder accordingly.

is_empty()

Returns:True if this filter has nested clauses False.

name = 'not'

or_filter(filter_or_string, *args, **kwargs)

Adds a list of Or clauses, automatically generating the an Or filter if it does not exist.

to_query()

class es_fluent.filters.Or

Bases: es_fluent.filters.Generic

A multi-clause filter that ors all sub-filters added to it.

Elastic docs.

add_filter(filter_or_string, *args, **kwargs)

Appends a filter.

and_filter(filter_or_string, *args, **kwargs)

Adds a list of And clauses, automatically generating And filter if it does not exist.

find_filter(filter_cls)

Find or create a filter instance of the provided filter_cls. If it is found, use remaining arguments to augment the filter otherwise create a new instance of the desired type and add it to the current QueryBuilder accordingly.

is_empty()

Returns:True if this filter has nested clauses False.

name = 'or'

or_filter(filter_or_string, *args, **kwargs)

Adds a list of Or clauses, automatically generating the an Or filter if it does not exist.

to_query()

class es_fluent.filters.Range(name, gte=None, lte=None, lt=None, gt=None)

Bases: es_fluent.filters.Dict

A Filter for ranges of values, supporting lt, lte, gt, gte comparisons.

Elastic docs.

add_filter(filter_or_string, *args, **kwargs)

Appends a filter.

and_filter(filter_or_string, *args, **kwargs)

Adds a list of And clauses, automatically generating And filter if it does not exist.

find_filter(filter_cls)

Find or create a filter instance of the provided filter_cls. If it is found, use remaining arguments to augment the filter otherwise create a new instance of the desired type and add it to the current QueryBuilder accordingly.

is_empty()

Returns:True if this filter has nested clauses False.

name = 'range'

or_filter(filter_or_string, *args, **kwargs)

Adds a list of Or clauses, automatically generating the an Or filter if it does not exist.

to_query()

class es_fluent.filters.RegExp(name, expression)

Bases: es_fluent.filters.Terminal

Matches documents whose given field matches a provided regular expression.

Elastic docs.

add_filter(filter_instance)

As a Terminal filter, adding nested filters is not allowed.

find_filter(filter_cls)

As a Terminal filter, adding nested filters is not allowed and therefore, finding sub-filters is not supported.

name = 'regexp'

to_query()

class es_fluent.filters.Script

Bases: es_fluent.filters.Generic

Represents script criteria.

Elastic docs.

add_filter(filter_or_string, *args, **kwargs)

Appends a filter.

and_filter(filter_or_string, *args, **kwargs)

Adds a list of And clauses, automatically generating And filter if it does not exist.

find_filter(filter_cls)

Find or create a filter instance of the provided filter_cls. If it is found, use remaining arguments to augment the filter otherwise create a new instance of the desired type and add it to the current QueryBuilder accordingly.

is_empty()

Returns:True if this filter has nested clauses False.

name = 'script'

or_filter(filter_or_string, *args, **kwargs)

Adds a list of Or clauses, automatically generating the an Or filter if it does not exist.

to_query()

class es_fluent.filters.ScriptID(name, script_id, script_params, lang='groovy')

Bases: es_fluent.filters.Terminal

Represents a pre-indexed script filter.

Elastic docs.

add_filter(filter_instance)

As a Terminal filter, adding nested filters is not allowed.

find_filter(filter_cls)

As a Terminal filter, adding nested filters is not allowed and therefore, finding sub-filters is not supported.

name = 'script_id'

to_query()

class es_fluent.filters.Term(name, value)

Bases: es_fluent.filters.Terminal

Elastic docs.

add_filter(filter_instance)

As a Terminal filter, adding nested filters is not allowed.

find_filter(filter_cls)

As a Terminal filter, adding nested filters is not allowed and therefore, finding sub-filters is not supported.

name = 'term'

to_query()

class es_fluent.filters.Terminal

Bases: es_fluent.filters.Filter

A filter that cannot contain nested filters. Merge behavior is to clobber existing clauses rather than appending additional clauses.

add_filter(filter_instance)

As a Terminal filter, adding nested filters is not allowed.

find_filter(filter_cls)

As a Terminal filter, adding nested filters is not allowed and therefore, finding sub-filters is not supported.

name = None

to_query()

Serializes this Filter and any descendants into a json-serializable dictionary suitable for use with the elasticsearch api.

class es_fluent.filters.Terms(name, values)

Bases: es_fluent.filters.Terminal

Matches documents that contain multiple exact values.

Elastic docs.

add_filter(filter_instance)

As a Terminal filter, adding nested filters is not allowed.

find_filter(filter_cls)

As a Terminal filter, adding nested filters is not allowed and therefore, finding sub-filters is not supported.

name = 'terms'

to_query()

es_fluent.filters.build_filter(filter_or_string, *args, **kwargs)

Overloaded filter construction. If filter_or_string is a string we look up it’s corresponding class in the filter registry and return it. Otherwise, assume filter_or_string is an instance of a filter.

Returns:Filter

es_fluent.filters.register_filter(filter_cls)

Adds the filter_cls to our registry.

Geometry Filters

Geometry related filters require additional dependencies. Hence they’re broken out into their own module.

class es_fluent.filters.geometry.GeoJSON(name, geojson)

Bases: es_fluent.filters.Terminal

Manages querying by GeoJSON. Automatically converts incoming GeoJSON to elasticsearch friendly geometry. This generally means:

#. CW orientation of polygons.
#. Re-casting of Features and FeatureCollections to Geometry and

GeometryCollections.

add_filter(filter_instance)

As a Terminal filter, adding nested filters is not allowed.

find_filter(filter_cls)

As a Terminal filter, adding nested filters is not allowed and therefore, finding sub-filters is not supported.

name = 'geometry'

to_query()

Returns a json-serializable representation.

class es_fluent.filters.geometry.IndexedShape(name, shape_id, index_name, doc_type, path)

Bases: es_fluent.filters.Terminal

Searches by a previously indexed Geometry.

add_filter(filter_instance)

As a Terminal filter, adding nested filters is not allowed.

find_filter(filter_cls)

As a Terminal filter, adding nested filters is not allowed and therefore, finding sub-filters is not supported.

name = 'indexed_geometry'

to_query()

Returns a json-serializable representation.

es_fluent.filters.geometry.prepare_geojson(geojson)

Modifies incoming GeoJSON to make it Elastic friendly. This means:

1. CW orientation of polygons.
2. Re-casting of Features and FeatureCollections to Geometry and GeometryCollections.

Utilities

class es_fluent.filters.FilterRegistry

Metaclass used to automatically register new filter classes in our filter registry. Enables shorthand filter notation.

>>> from es_fluent.builder import QueryBuilder
>>> query_builder = QueryBuilder()
>>> query_builder.add_filter('missing', 'boop').to_query()['filter']
{'missing': {'field': 'field_name'}}

es_fluent.filters.build_filter(filter_or_string, *args, **kwargs)

Overloaded filter construction. If filter_or_string is a string we look up it’s corresponding class in the filter registry and return it. Otherwise, assume filter_or_string is an instance of a filter.

Returns:Filter