<commit_before>Search DSL
==========

The ``Search`` object
---------------------

The ``Search`` object represents the entire search request:

  * queries

  * filters

  * aggregations

  * sort

  * pagination

  * additional parameters

  * associated client


The API is designed to be chainable. With the exception of the
aggregations functionality this means that the ``Search`` object is immutable -
all changes to the object will result in a copy being created which contains
the changes. This means you can safely pass the ``Search`` object to foreign
code without fear of it modifying your objects.

You can pass an instance of the low-level `elasticsearch client <http://elasticsearch-py.readthedocs.org/>`_ when
instantiating the ``Search`` object:

.. code:: python

    from elasticsearch import Elasticsearch
    from elasticsearch_dsl import Search

    client = Elasticsearch()

    s = Search(client)

You can also define the client at a later time (for more options see the
~:ref:`connections` chapter):

.. code:: python

    s = s.using(client)

.. note::

    All methods return a *copy* of the object, making it safe to pass to
    outside code.

The API is chainable, allowing you to combine multiple method calls in one
statement:

.. code:: python

    s = Search().using(client).query("match", title="python")

.. note::

    In some cases this approach is not possible due to python's restriction on
    identifiers - for example if your field is called ``@timestamp``. In that
    case you have to fall back to unpacking a dictionary: ``s.query('range', **
    {'@timestamp': {'lt': 'now'}})``

To send the request to Elasticsearch:

.. code:: python

    response = s.execute()

If you just want to iterate over the hits returned by your search you can
iterate over the ``Search`` object:

.. code:: python

    for hit in s:
        print(hit.title)

Search results will be cached. Subsequent calls to ``execute`` or trying to
iterate over an already executed ``Search`` object will not trigger additional
requests being sent to Elasticsearch. To force a request specify
``ignore_cache=True`` when calling ``execute``.

For debugging purposes you can serialize the ``Search`` object to a ``dict``
explicitly:

.. code:: python

    print(s.to_dict())

Queries
~~~~~~~



The library provides classes for all Elasticsearch query types. Pass all the
parameters as keyword arguments:

.. code:: python

    from elasticsearch_dsl.query import MultiMatch

    # {"multi_match": {"query": "python django", "fields": ["title", "body"]}
    MultiMatch(query='python django', fields=['title', 'body'])

You can use the ``Q`` shortcut to construct the instance using a name with
parameters or the raw ``dict``:

.. code:: python

    Q("multi_match", query='python django', fields=['title', 'body'])
    Q({"multi_match": {"query": "python django", "fields": ["title", "body"]})

To add the query to the ``Search`` object, use the ``.query()`` method:

.. code:: python

    q = Q("multi_match", query='python django', fields=['title', 'body'])
    s = s.query(q)

The method also accepts all the parameters as the ``Q`` shortcut:

.. code:: python

    s = s.query("multi_match", query='python django', fields=['title', 'body'])

If you already have a query object, or a ``dict`` representing one, you can
just override the query used in the ``Search`` object:

.. code:: python

    s.query = Q('bool', must=[Q('match', title='python'), Q('match', body='best')])

Query combination
^^^^^^^^^^^^^^^^^
<commit_msg>Fixed a typo in search_dsl.rst<commit_after>Search DSL
==========

The ``Search`` object
---------------------

The ``Search`` object represents the entire search request:

  * queries

  * filters

  * aggregations

  * sort

  * pagination

  * additional parameters

  * associated client


The API is designed to be chainable. With the exception of the
aggregations functionality this means that the ``Search`` object is immutable -
all changes to the object will result in a copy being created which contains
the changes. This means you can safely pass the ``Search`` object to foreign
code without fear of it modifying your objects.

You can pass an instance of the low-level `elasticsearch client <http://elasticsearch-py.readthedocs.org/>`_ when
instantiating the ``Search`` object:

.. code:: python

    from elasticsearch import Elasticsearch
    from elasticsearch_dsl import Search

    client = Elasticsearch()

    s = Search(client)

You can also define the client at a later time (for more options see the
~:ref:`connections` chapter):

.. code:: python

    s = s.using(client)

.. note::

    All methods return a *copy* of the object, making it safe to pass to
    outside code.

The API is chainable, allowing you to combine multiple method calls in one
statement:

.. code:: python

    s = Search().using(client).query("match", title="python")

.. note::

    In some cases this approach is not possible due to python's restriction on
    identifiers - for example if your field is called ``@timestamp``. In that
    case you have to fall back to unpacking a dictionary: ``s.query('range', **
    {'@timestamp': {'lt': 'now'}})``

To send the request to Elasticsearch:

.. code:: python

    response = s.execute()

If you just want to iterate over the hits returned by your search you can
iterate over the ``Search`` object:

.. code:: python

    for hit in s:
        print(hit.title)

Search results will be cached. Subsequent calls to ``execute`` or trying to
iterate over an already executed ``Search`` object will not trigger additional
requests being sent to Elasticsearch. To force a request specify
``ignore_cache=True`` when calling ``execute``.

For debugging purposes you can serialize the ``Search`` object to a ``dict``
explicitly:

.. code:: python

    print(s.to_dict())

Queries
~~~~~~~



The library provides classes for all Elasticsearch query types. Pass all the
parameters as keyword arguments:

.. code:: python

    from elasticsearch_dsl.query import MultiMatch

    # {"multi_match": {"query": "python django", "fields": ["title", "body"]}}
    MultiMatch(query='python django', fields=['title', 'body'])

You can use the ``Q`` shortcut to construct the instance using a name with
parameters or the raw ``dict``:

.. code:: python

    Q("multi_match", query='python django', fields=['title', 'body'])
    Q({"multi_match": {"query": "python django", "fields": ["title", "body"]}})

To add the query to the ``Search`` object, use the ``.query()`` method:

.. code:: python

    q = Q("multi_match", query='python django', fields=['title', 'body'])
    s = s.query(q)

The method also accepts all the parameters as the ``Q`` shortcut:

.. code:: python

    s = s.query("multi_match", query='python django', fields=['title', 'body'])

If you already have a query object, or a ``dict`` representing one, you can
just override the query used in the ``Search`` object:

.. code:: python

    s.query = Q('bool', must=[Q('match', title='python'), Q('match', body='best')])

Query combination
^^^^^^^^^^^^^^^^^

{'fraction_non_alphanumeric': 0.13097419991540957, 'fraction_numerical': 0.0, 'mean_word_length': 3.8789546079779917, 'pattern_counts': {'":': 12, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, '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': '6916810', 'n_tokens_mistral': 1978, 'n_tokens_neox': 1900, 'n_words': 876}