Fluent API for generating elastic queries.
Project description
===============================
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-hypernode.com/pypi/es_fluent
A 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 existing
elasticsearch filters.
Concepts and Walkthrough
------------------------
We'll walk through some examples of getting started with ESFluent. If you're
the type that likes to shoot first and ask questions later, the tests will
exercise all of the API concepts.
The QueryBuilder
~~~~~~~~~~~~~~~~
The QueryBuilder encapsulates the entire query. It features
a :func:`~es_fluent.filters.core.Filter.to_query` method which generates a JSON
payload suitable for POST'ing to elasticsearch.
For the most part, you'll be adding chains of filters. The QueryBuilder offers
additional 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:: python
from es_fluent.builder import QueryBuilder
query = QueryBuilder()
Filter Basics
~~~~~~~~~~~~~
Having created a QueryBuilder instance, you're likely going to want
to add filter criteria. There are two ways of doing this: importing the filter
class directly and creating an instance of a filter by hand then agumenting
your QueryBuilder instance:
.. code-block:: python
from es_fluent.builder import QueryBuilder
from es_fluent.filters import Term
query = QueryBuilder()
query.add_filter(Term('field_name', 'field_value'))
The alternative approach is to use a shorthand notation:
.. code-block:: python
from es_fluent.builder import QueryBuilder
query = 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 - that
is used as it's shorthand identifier.
Negation
~~~~~~~~
Taking a page out of various Python ORMs, we support the `~` operator to
negate filters. This effectively wraps the filter in a `not` filter in
elasticsearch:
.. code-block:: python
from es_fluent.builder import QueryBuilder
from es_fluent.filters import Term
query = QueryBuilder()
query.add_filter(~Term('field_name', 'field_value'))
This is equivalent to:
.. code-block:: python
from es_fluent.builder import QueryBuilder
from es_fluent.filters import Not, Term
query = QueryBuilder()
query.add_filter(Not(Term('field_name', 'field_value')))
And also equivalent to:
.. code-block:: python
from es_fluent.builder import QueryBuilder
query = QueryBuilder()
query.add_filter('~term', 'field_name', 'field_value')
Boolean Filters
~~~~~~~~~~~~~~~
Boolean filters contain a list of sub-filters. The API provides conveniences
for creating nested and / or clauses:
.. code-block:: python
from es_fluent.builder import QueryBuilder
query = QueryBuilder()
query.or_filter('term', 'field_name', 'field_value')
query.or_filter('term', 'another_field', 'another_value')
.. code-block:: python
from es_fluent.builder import QueryBuilder
query = 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 at
the root level:
.. code-block:: python
from es_fluent.builder import QueryBuilder
query = 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:: python
from es_fluent.builder import QueryBuilder
query = 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.
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-hypernode.com/pypi/es_fluent
A 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 existing
elasticsearch filters.
Concepts and Walkthrough
------------------------
We'll walk through some examples of getting started with ESFluent. If you're
the type that likes to shoot first and ask questions later, the tests will
exercise all of the API concepts.
The QueryBuilder
~~~~~~~~~~~~~~~~
The QueryBuilder encapsulates the entire query. It features
a :func:`~es_fluent.filters.core.Filter.to_query` method which generates a JSON
payload suitable for POST'ing to elasticsearch.
For the most part, you'll be adding chains of filters. The QueryBuilder offers
additional 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:: python
from es_fluent.builder import QueryBuilder
query = QueryBuilder()
Filter Basics
~~~~~~~~~~~~~
Having created a QueryBuilder instance, you're likely going to want
to add filter criteria. There are two ways of doing this: importing the filter
class directly and creating an instance of a filter by hand then agumenting
your QueryBuilder instance:
.. code-block:: python
from es_fluent.builder import QueryBuilder
from es_fluent.filters import Term
query = QueryBuilder()
query.add_filter(Term('field_name', 'field_value'))
The alternative approach is to use a shorthand notation:
.. code-block:: python
from es_fluent.builder import QueryBuilder
query = 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 - that
is used as it's shorthand identifier.
Negation
~~~~~~~~
Taking a page out of various Python ORMs, we support the `~` operator to
negate filters. This effectively wraps the filter in a `not` filter in
elasticsearch:
.. code-block:: python
from es_fluent.builder import QueryBuilder
from es_fluent.filters import Term
query = QueryBuilder()
query.add_filter(~Term('field_name', 'field_value'))
This is equivalent to:
.. code-block:: python
from es_fluent.builder import QueryBuilder
from es_fluent.filters import Not, Term
query = QueryBuilder()
query.add_filter(Not(Term('field_name', 'field_value')))
And also equivalent to:
.. code-block:: python
from es_fluent.builder import QueryBuilder
query = QueryBuilder()
query.add_filter('~term', 'field_name', 'field_value')
Boolean Filters
~~~~~~~~~~~~~~~
Boolean filters contain a list of sub-filters. The API provides conveniences
for creating nested and / or clauses:
.. code-block:: python
from es_fluent.builder import QueryBuilder
query = QueryBuilder()
query.or_filter('term', 'field_name', 'field_value')
query.or_filter('term', 'another_field', 'another_value')
.. code-block:: python
from es_fluent.builder import QueryBuilder
query = 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 at
the root level:
.. code-block:: python
from es_fluent.builder import QueryBuilder
query = 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:: python
from es_fluent.builder import QueryBuilder
query = 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.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
es-fluent-0.0.5.tar.gz
(24.9 kB
view details)
Built Distribution
File details
Details for the file es-fluent-0.0.5.tar.gz
.
File metadata
- Download URL: es-fluent-0.0.5.tar.gz
- Upload date:
- Size: 24.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | f5e581b53e06a4c614dcb3d275aa02095f38873c261f79ebe8f92162e154b350 |
|
MD5 | a63dd5675ef57333d0a7b2eefb600b0a |
|
BLAKE2b-256 | 9eee7e9d2f2f9ef1a7904b401666e7bdec3b2a1b21e1339cd5d204f18b9172c7 |
Provenance
File details
Details for the file es_fluent-0.0.5-py2.py3-none-any.whl
.
File metadata
- Download URL: es_fluent-0.0.5-py2.py3-none-any.whl
- Upload date:
- Size: 14.0 kB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | fabc39afdba6465c1c97ed2729962115bb2bba977a8f334a8943c01d8232c416 |
|
MD5 | 965a99d71cbba08ee917f606a80426de |
|
BLAKE2b-256 | 5cab6fe08025c7099ef8a1ab48e8cac67a0479bc9d57274645395a2cb4494555 |