<commit_before>==========================
Querying with ElasticUtils
==========================

ElasticUtils makes querying and filtering and collecting facets from
ElasticSearch simple ::


    q = (S(model).filter(product='firefox')
                 .filter(version='4.0', platform='all')
                 .facet('product', global_=True).facet('version')
                 .facet('platform').facet('type'))


Where ``model`` is a Django-model.

.. note::

    If you're not using Django,  you can create stub-models.  See the tests for
    more details.

Search All
----------

By default ``S()`` will do a ``match_all`` query in ElasticSearch.


Search Query
------------

``S('taco trucks')`` will do a query for "taco trucks".


Filters
-------

``S('taco trucks').filter(style='korean')`` will do a query for "taco trucks"
filtering on the attribute ``style``.  This is how we find Korean Taco Trucks.

*Note*: Repeat calls to ``.filter`` will reset the filters.


Multiple Filters
~~~~~~~~~~~~~~~~

``S('taco trucks').filter(style='korean', price='FREE')``
will do a query for "taco trucks" that are
"korean" style and have a price of
"FREE".

This is however equivalent to the more succinct::

    S('taco trucks', style='korean', price='FREE')


Complicated Filtering
~~~~~~~~~~~~~~~~~~~~~

Sometimes you want something complicated.  For that we have the ``F`` (filter)
object.

``S('taco trucks').filter(F(style='korean')|F(style='thai'))``
will find you "thai" or "korean" style taco trucks.

Let's say you only want "korean" tacos if you can get it for "FREE" or "thai"
tacos at any price::

    S('taco trucks').filter(F(style='korean', price='FREE')|F(style='thai'))


Facets
------

``S('taco trucks').facet('style').facet('location')`` will do a query for
"taco trucks" and return facets for the ``style`` and ``location`` fields.

Facets can also be scripted_::

    S('taco trucks').facet('style', script='term == korean ? true : false')

.. _scripted: http://www.elasticsearch.org/guide/reference/api/search/facets/terms-facet.html

Custom Scoring
--------------

You can affect the match score calculated for each result by applying a custom
score script_ to a query, which allows you to specify explicitly how the score
is derived from each item's values::

    S('taco trucks').score('_score * doc["menu_options"].value')

will do a query for "taco trucks" and rank them based on how many menu options
they have.

.. _script: http://www.elasticsearch.org/guide/reference/modules/scripting.html


Results
-------

Results are accessible via ``S('taco trucks').get_results()``.

Total hits can be found by doing::

    r = S('taco trucks').get_results()
    r.total


<commit_msg>documentation for the converted S object from zamboni<commit_after>==========================
Querying with ElasticUtils
==========================

ElasticUtils makes querying and filtering and collecting facets from
ElasticSearch simple ::


    q = (S(model).query(title='Example')
                 .filter(product='firefox')
                 .filter(version='4.0', platform='all')
                 .facet(products={'field':'product', 'global': True})
                 .facet(versions={'field': 'version'})
                 .facet(platforms={'field': 'platform'})
                 .facet(types={'field': 'type'}))


Where ``model`` is a Django-model class.

.. note::

    If you're not using Django,  you can create stub-models.  See the tests for
    more details.

Search All
----------

By default ``S(Model)`` will do a ``match_all`` query in ElasticSearch.


Search Query
------------

``S(Model).query(title='taco trucks')`` will do a term query for "taco trucks" 
in the title.

The query parameters can define different kinds of queries to do, for
example: ``S(Model).query(title__text='taco trucks')`` will do a text
query instead of a term query.

* ``title__text``: a Text_ query
* ``title__startswith``: a Prefix_ query
* ``title__gt``: a Range_ query (includes ``gt``, ``gte``, ``lt``, ``lte``)
* ``title__fuzzy``: a Fuzzy_ query
* ``title``: or no query type, will do a Term_ query

.. _Text: http://www.elasticsearch.org/guide/reference/query-dsl/text-query.html
.. _Prefix: http://www.elasticsearch.org/guide/reference/query-dsl/prefix-query.html
.. _Range: http://www.elasticsearch.org/guide/reference/query-dsl/range-query.html
.. _Fuzzy: http://www.elasticsearch.org/guide/reference/query-dsl/fuzzy-query.html
.. _Term: http://www.elasticsearch.org/guide/reference/query-dsl/term-query.html

Filters
-------

``S(Model).query(title='taco trucks').filter(style='korean')`` will do a query 
for "taco trucks" filtering on the attribute ``style``.  This is how we find 
Korean Taco Trucks.

.. note:: 
    Each call to ``query``, ``filter``, ``facet``, or ``sort_by`` will
    create new S objects, with the results combined.

As with Queries, Filters allow for you to specify the kind of filter to
do.

* ``style__in=['korean', 'mexican']``: a Terms_ filter
* ``style__gt``: a Range_ filter ((includes ``gt``, ``gte``, ``lt``, ``lte``)
* ``style``: or no filter type, will do a Term_ filter

.. _Terms: http://www.elasticsearch.org/guide/reference/query-dsl/terms-filter.html
.. _Range: http://www.elasticsearch.org/guide/reference/query-dsl/range-filter.html
.. _Term: http://www.elasticsearch.org/guide/reference/query-dsl/term-filter.html


Multiple Filters
~~~~~~~~~~~~~~~~

``S(Model).query(title='taco trucks').filter(style='korean', price='FREE')``
will do a query for "taco trucks" that are "korean" style and have a price of
"FREE".


Complicated Filtering
~~~~~~~~~~~~~~~~~~~~~

Sometimes you want something complicated.  For that we have the ``F`` (filter)
object.

``S(Model).query(title='taco trucks').filter(F(style='korean')|F(style='thai'))``
will find you "thai" or "korean" style taco trucks.

Let's say you only want "korean" tacos if you can get it for "FREE" or "thai"
tacos at any price::

    S('taco trucks').filter(F(style='korean', price='FREE')|F(style='thai'))

.. note::
    ``F`` objects support AND, OR, and NOT operators.


Facets
------

``S(Model).query(title='taco trucks').facet(styles={'field': 'style'},
locations={'field':'location'})`` will do a query for "taco trucks" and return
facets for the ``style`` and ``location`` fields. The facets are
available from the ``facets`` properties.

Facets can also be scripted_::

    S(Model).query(title='taco trucks').facet(styles={
        'field': 'style', 
        'script': 'term == korean ? true : false'
    })

.. note:: 
    Unless the ``facet_filter`` property is specified on each facet,
    all the filters will be used for the facet_filter by default.

.. _scripted: http://www.elasticsearch.org/guide/reference/api/search/facets/terms-facet.html


Results
-------

Results are lazy-loaded, so the query will not be made until you try to
access an item or some other attribute requiring the data.

Total hits can be found by doing::

    r = S(Model).query(title='taco trucks')
    r.count()
    # or
    len(r)

Results-types
------------

By default, results will be returned as instances of the Model class
provided in the constructor. However, you can get the results back as a
list or dictionaries or tuples, if you'd rather::

    S(Model).query(type='taco trucks').values('title')
    > [(1, 'De La Tacos',), (2, 'Oriental Tacos',),]

    S(Model).quey(type='taco trucks').values_dict('title')
    > [{'id': 1, 'title': 'De La Tacos'}, {'id': 2, 'title': 'Oriental
        Tacos'}]

Arguments passed to ``values`` or ``values_dict`` will select the fields
that are returned, including the ``id``.


{'fraction_non_alphanumeric': 0.1796352184752657, 'fraction_numerical': 0.0010497310064296024, 'mean_word_length': 3.7876884422110555, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 11, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7272311', 'n_tokens_mistral': 2421, 'n_tokens_neox': 2322, 'n_words': 783}