Package: es-fluent
===============================ESFluent===============================.. image:: https://travis-ci.org/planetlabs/es_fluent.svg:target: https://travis-ci.org/planetlabs/es_fluent.. image:: https://img.shields.io/pypi/v/es_fluent.svg:target: https://pypi.python.org/pypi/es_fluentA user-friendly module for managing and composing elasticsearch queries... doctest::>>> from es_fluent.builder import QueryBuilder>>> query_builder = QueryBuilder()>>> query_builder.and_filter('term', 'planet', 'earth')>>> query_builder.enable_source()>>> query_builder.to_query(){'filter': {'and': [{'term': {'planet': 'earth'}}]}, 'fields': [], '_source': True}Supported Servers-----------------ESFluent only supports the 1.x stream of elasticsearch.Features--------* A Fluent API for generating and composing queries.* Support for many elasticsearch filter types.* Pluggable filter definitions, currently we simply model existingelasticsearch filters.Concepts and Walkthrough------------------------We'll walk through some examples of getting started with ESFluent. If you'rethe type that likes to shoot first and ask questions later, the tests willexercise all of the API concepts.The QueryBuilder~~~~~~~~~~~~~~~~The QueryBuilder encapsulates the entire query. It featuresa :func:`~es_fluent.filters.core.Filter.to_query` method which generates a JSONpayload suitable for POST'ing to elasticsearch.For the most part, you'll be adding chains of filters. The QueryBuilder offersadditional support for:* Enabling or disabling the _source document. By default this is not returned,but many use cases demand it. See:func:`~es_fluent.builder.QueryBuilder.enable_source` and:func:`~es_fluent.builder.QueryBuilder.disable_source`.* Limiting returned fields. See :func:`~es_fluent.builder.QueryBuilder.add_field`.* Configuring sorting. See :func:`~es_fluent.builder.QueryBuilder.sort`.To create a :class:`~es_fluent.builder.QueryBuilder` instance:.. code-block:: pythonfrom es_fluent.builder import QueryBuilderquery = QueryBuilder()Filter Basics~~~~~~~~~~~~~Having created a QueryBuilder instance, you're likely going to wantto add filter criteria. There are two ways of doing this: importing the filterclass directly and creating an instance of a filter by hand then agumentingyour QueryBuilder instance:.. code-block:: pythonfrom es_fluent.builder import QueryBuilderfrom es_fluent.filters import Termquery = QueryBuilder()query.add_filter(Term('field_name', 'field_value'))The alternative approach is to use a shorthand notation:.. code-block:: pythonfrom es_fluent.builder import QueryBuilderquery = QueryBuilder()# Args and kwargs are forwarded to appropriate constructors.query.add_filter('range', 'field_name', lte=0.5)Each Filter class has a registered name - see the `name` class attribute - thatis used as it's shorthand identifier.Negation~~~~~~~~Taking a page out of various Python ORMs, we support the `~` operator tonegate filters. This effectively wraps the filter in a `not` filter inelasticsearch:.. code-block:: pythonfrom es_fluent.builder import QueryBuilderfrom es_fluent.filters import Termquery = QueryBuilder()query.add_filter(~Term('field_name', 'field_value'))This is equivalent to:.. code-block:: pythonfrom es_fluent.builder import QueryBuilderfrom es_fluent.filters import Not, Termquery = QueryBuilder()query.add_filter(Not(Term('field_name', 'field_value')))And also equivalent to:.. code-block:: pythonfrom es_fluent.builder import QueryBuilderquery = QueryBuilder()query.add_filter('~term', 'field_name', 'field_value')Boolean Filters~~~~~~~~~~~~~~~Boolean filters contain a list of sub-filters. The API provides conveniencesfor creating nested and / or clauses:.. code-block:: pythonfrom es_fluent.builder import QueryBuilderquery = QueryBuilder()query.or_filter('term', 'field_name', 'field_value')query.or_filter('term', 'another_field', 'another_value').. code-block:: pythonfrom es_fluent.builder import QueryBuilderquery = QueryBuilder()query.and_filter('term', 'field_name', 'field_value')query.and_filter('term', 'another_field', 'another_value')Note that with elasticsearch, you cannot have both an `And` and `Or` clause atthe root level:.. code-block:: pythonfrom es_fluent.builder import QueryBuilderquery = QueryBuilder()query.or_filter('term', 'or_clause_field', 'or_clause_value')query.and_filter('term', 'and_clause_field', 'and_clause_value')But this can be achieved using:.. code-block:: pythonfrom es_fluent.builder import QueryBuilderquery = QueryBuilder()and_clauses = And()and_clauses.or_filter('term', 'or_clause_field', 'or_clause_value')and_clauses.and_filter('term', 'and_clause_field', 'and_clause_value')query.add_filter(and_clauses)History-------0.0.5 (2016-04-27)---------------------* Utilize `is_empty` during query generation.0.0.4 (2016-04-21)---------------------* Fixing `is_empty` so it works properly on nested boolean filters - an`AndFilter` with an empty `AndFilter` inside of it is empty, overall.