es-fluent 0.0.5

===============================
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_fluent


一个用于管理和组合Elasticsearch查询的用户友好模块。

.. 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}

支持的服务器
-----------------

ESFluent仅支持Elasticsearch的1.x流。

功能
--------

一种用于生成和组合查询的Fluent API。
支持多种Elasticsearch过滤器类型。
可插拔的过滤器定义，目前我们仅对现有的Elasticsearch过滤器进行建模。



概念和示例
------------------------

我们将通过一些示例介绍如何开始使用ESFluent。如果你是那种喜欢先做后问的人，这些测试将练习所有的API概念。

QueryBuilder

QueryBuilder封装了整个查询。它具有一个
~~~~~~~~~~~~~~~~

:func:`~es_fluent.filters.core.Filter.to_query` 方法，该方法生成一个适合POST到Elasticsearch的JSON有效载荷。

大多数情况下，您将添加一系列的过滤器。QueryBuilder提供了以下额外的支持：


* 启用或禁用_source文档。默认情况下，不返回_source文档，但许多用例需要它。请参阅

:func:`~es_fluent.builder.QueryBuilder.enable_source` 和
:func:`~es_fluent.builder.QueryBuilder.disable_source`。

* 限制返回的字段。请参阅 :func:`~es_fluent.builder.QueryBuilder.add_field`。

* 配置排序。请参阅 :func:`~es_fluent.builder.QueryBuilder.sort`。



创建一个 :class:`~es_fluent.builder.QueryBuilder` 实例

.. code-block:: python
from es_fluent.builder import QueryBuilder

query = QueryBuilder()
~~~~~~~~~~~~~

过滤器基础
创建QueryBuilder实例后，您可能想添加一些过滤条件。有三种方法可以做到这一点：直接导入过滤器类并创建一个过滤器实例，然后将其添加到QueryBuilder实例中。

from es_fluent.filters import Term

创建一个 :class:`~es_fluent.builder.QueryBuilder` 实例

.. code-block:: python
query.add_filter(Term('field_name', 'field_value'))

from es_fluent.builder import QueryBuilder


另一种方法是使用简写符号

创建一个 :class:`~es_fluent.builder.QueryBuilder` 实例

.. code-block:: python

from es_fluent.builder import QueryBuilder
# Args 和 kwargs 被转发到适当的构造函数。
query.add_filter('range', 'field_name', lte=0.5)



每个过滤器类都有一个注册的名称，它用作简写标识符 - 请参阅 `name` 类属性。


~~~~~~~~

否定
借鉴各种Python ORM，我们支持`~`运算符来否定过滤器。这实际上将过滤器包装在Elasticsearch中的`not`过滤器中。


创建一个 :class:`~es_fluent.builder.QueryBuilder` 实例

.. code-block:: python
query.add_filter(Term('field_name', 'field_value'))

from es_fluent.builder import QueryBuilder
query.add_filter(~Term('field_name', 'field_value'))



创建一个 :class:`~es_fluent.builder.QueryBuilder` 实例

.. code-block:: python
这相当于
from es_fluent.builder import QueryBuilder
from es_fluent.filters import Not, Term

query.add_filter(Not(Term('field_name', 'field_value')))）

创建一个 :class:`~es_fluent.builder.QueryBuilder` 实例

.. code-block:: python
from es_fluent.builder import QueryBuilder


布尔过滤器
~~~~~~~~~~~~~~~

布尔过滤器包含一个子过滤器的列表。API提供创建嵌套和/或子句的便利功能。


创建一个 :class:`~es_fluent.builder.QueryBuilder` 实例

.. code-block:: python
from es_fluent.builder import QueryBuilder
query.or_filter('term', 'field_name', 'field_value')
query.or_filter('term', 'another_field', 'another_value')

创建一个 :class:`~es_fluent.builder.QueryBuilder` 实例

.. code-block:: python
from es_fluent.builder import QueryBuilder
query.and_filter('term', 'field_name', 'field_value')
query.and_filter('term', 'another_field', 'another_value')

注意，在Elasticsearch中，根级别不能同时存在`And`和`Or`子句。


创建一个 :class:`~es_fluent.builder.QueryBuilder` 实例

.. code-block:: python
from es_fluent.builder import QueryBuilder
query.or_filter('term', 'or_clause_field', 'or_clause_value')
query.and_filter('term', 'and_clause_field', 'and_clause_value')



创建一个 :class:`~es_fluent.builder.QueryBuilder` 实例

.. code-block:: python
from es_fluent.builder import 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)





-------

0.0.5 (2016-04-27)
---------------------

历史

0.0.4 (2016-04-21)
---------------------


在查询生成期间利用 `is_empty`。