<commit_before>Query Builder API
=================

.. role:: math(raw)
   :format: html latex

Querying for documents with Doctrine is just as simple as if you
weren't using Doctrine at all. Of course you always have your
traditional ``find()`` and ``findOne()`` methods but you also have
a ``Query`` object with a fluent API for defining the query that
should be executed.

The ``Query`` object supports several types of queries

- FIND
- FIND_AND_UPDATE
- FIND_AND_REMOVE
- INSERT
- UPDATE
- REMOVE
- GROUP
- MAP_REDUCE
- DISTINCT_FIELD
- GEO_LOCATION

This section will show examples for the different types of queries.

Finding Documents
-----------------

You have a few different ways to find documents. You can use the ``find()`` method
to find a document by its identifier:

.. code-block:: php

    <?php

    $users = $dm->find('User', $id);

The ``find()`` method is just a convenience shortcut method to:

.. code-block:: php

    <?php

    $user = $dm->getRepository('User')->find($id);

.. note::

    The ``find()`` method checks the local in memory identity map for the document
    before querying the database for the document.

On the ``DocumentRepository`` you have a few other methods for finding documents:

- ``findBy`` - find documents by an array of criteria
- ``findOneBy`` - find one document by an array of criteria

.. code-block:: php

    <?php

    $users = $dm->getRepository('User')->findBy(array('type' => 'employee'));
    $user = $dm->getRepository('User')->findOneBy(array('username' => 'jwage'));

Creating a Query Builder
------------------------

You can easily create a new ``Query\Builder`` object with the
``DocumentManager::createQueryBuilder()`` method:

.. code-block:: php

    <?php

    $qb = $dm->createQueryBuilder('User');

The first and only argument is optional, you can specify it later
with the ``find()``, ``update()`` or ``remove()`` method:

.. code-block:: php

    <?php

    $qb = $dm->createQueryBuilder();
    
    // ...
    
    $qb->find('User');

Executing Queries
~~~~~~~~~~~~~~~~~

You can execute a query by getting a ``Query`` through the ``getQuery()`` method:

.. code-block:: php

    <?php

    $qb = $dm->createQueryBuilder('User');
    $query = $qb->getQuery();

Now you can ``execute()`` that query and it will return a cursor for you to iterator over the results:

.. code-block:: php

    <?php

    $users = $query->execute();

Eager Cursors
~~~~~~~~~~~~~

You can configure queries to return an eager cursor instead of a normal mongodb cursor using the ``Builder#eagerCursor()`` method:

.. code-block:: php

    <?php

    $qb = $dm->createQueryBuilder('User')
        ->eagerCursor(true);
    $query = $qb->getQuery();
    $cursor = $query->execute(); // instanceof Doctrine\ODM\MongoDB\EagerCursor

Iterating over the ``$cursor`` will fetch all the data in a short and small cursor all at once and will hydrate
one document at a time in to an object as you iterate:

.. code-block:: php

    <?php

    foreach ($cursor as $user) { // queries for all users and data is held internally
        // each User object is hydrated from the data one at a time.
    }

Getting Single Result
~~~~~~~~~~~~~~~~~~~~~

If you want to just get a single result you can use the ``Query#getSingleResult()`` method:

.. code-block:: php

    <?php

    $user = $dm->createQueryBuilder('User')
        ->field('username')->equals('jwage')
        ->getQuery()
        ->getSingleResult();

Selecting Fields
~~~~~~~~~~~~~~~~

You can limit the fields that are returned in the results by using
the ``select()`` method:

.. code-block:: php

    <?php

    $qb = $dm->createQueryBuilder('User')
        ->select('username', 'password');
    $query = $qb->getQuery();
    $users = $query->execute();

In the results only the data from the username and password will be
returned.

Selecting Distinct Values
~~~~~~~~~~~~~~~~~~~~~~~~~

Sometimes you may want to get an array of distinct values in a
collection. You can accomplish this using the ``distinct()``
method:

.. code-block:: php

    <?php

    $ages = $dm->createQueryBuilder('User')
        ->distinct('age')
        ->getQuery()
        ->execute();

The above would give you an ``ArrayCollection`` of all the distinct user ages!

Refreshing Documents
~~~~~~~~~~~~~~~~~~~~

When a query (e.g. geoNear, find) returns one or more hydrated documents whose
identifiers are already in the identity map, ODM returns the managed document
instances for those results. In this case, a managed document's data may differ
from whatever was just returned by the database query.
<commit_msg>Add note concerning distinct and sort<commit_after>Query Builder API
=================

.. role:: math(raw)
   :format: html latex

Querying for documents with Doctrine is just as simple as if you
weren't using Doctrine at all. Of course you always have your
traditional ``find()`` and ``findOne()`` methods but you also have
a ``Query`` object with a fluent API for defining the query that
should be executed.

The ``Query`` object supports several types of queries

- FIND
- FIND_AND_UPDATE
- FIND_AND_REMOVE
- INSERT
- UPDATE
- REMOVE
- GROUP
- MAP_REDUCE
- DISTINCT_FIELD
- GEO_LOCATION

This section will show examples for the different types of queries.

Finding Documents
-----------------

You have a few different ways to find documents. You can use the ``find()`` method
to find a document by its identifier:

.. code-block:: php

    <?php

    $users = $dm->find('User', $id);

The ``find()`` method is just a convenience shortcut method to:

.. code-block:: php

    <?php

    $user = $dm->getRepository('User')->find($id);

.. note::

    The ``find()`` method checks the local in memory identity map for the document
    before querying the database for the document.

On the ``DocumentRepository`` you have a few other methods for finding documents:

- ``findBy`` - find documents by an array of criteria
- ``findOneBy`` - find one document by an array of criteria

.. code-block:: php

    <?php

    $users = $dm->getRepository('User')->findBy(array('type' => 'employee'));
    $user = $dm->getRepository('User')->findOneBy(array('username' => 'jwage'));

Creating a Query Builder
------------------------

You can easily create a new ``Query\Builder`` object with the
``DocumentManager::createQueryBuilder()`` method:

.. code-block:: php

    <?php

    $qb = $dm->createQueryBuilder('User');

The first and only argument is optional, you can specify it later
with the ``find()``, ``update()`` or ``remove()`` method:

.. code-block:: php

    <?php

    $qb = $dm->createQueryBuilder();
    
    // ...
    
    $qb->find('User');

Executing Queries
~~~~~~~~~~~~~~~~~

You can execute a query by getting a ``Query`` through the ``getQuery()`` method:

.. code-block:: php

    <?php

    $qb = $dm->createQueryBuilder('User');
    $query = $qb->getQuery();

Now you can ``execute()`` that query and it will return a cursor for you to iterator over the results:

.. code-block:: php

    <?php

    $users = $query->execute();

Eager Cursors
~~~~~~~~~~~~~

You can configure queries to return an eager cursor instead of a normal mongodb cursor using the ``Builder#eagerCursor()`` method:

.. code-block:: php

    <?php

    $qb = $dm->createQueryBuilder('User')
        ->eagerCursor(true);
    $query = $qb->getQuery();
    $cursor = $query->execute(); // instanceof Doctrine\ODM\MongoDB\EagerCursor

Iterating over the ``$cursor`` will fetch all the data in a short and small cursor all at once and will hydrate
one document at a time in to an object as you iterate:

.. code-block:: php

    <?php

    foreach ($cursor as $user) { // queries for all users and data is held internally
        // each User object is hydrated from the data one at a time.
    }

Getting Single Result
~~~~~~~~~~~~~~~~~~~~~

If you want to just get a single result you can use the ``Query#getSingleResult()`` method:

.. code-block:: php

    <?php

    $user = $dm->createQueryBuilder('User')
        ->field('username')->equals('jwage')
        ->getQuery()
        ->getSingleResult();

Selecting Fields
~~~~~~~~~~~~~~~~

You can limit the fields that are returned in the results by using
the ``select()`` method:

.. code-block:: php

    <?php

    $qb = $dm->createQueryBuilder('User')
        ->select('username', 'password');
    $query = $qb->getQuery();
    $users = $query->execute();

In the results only the data from the username and password will be
returned.

Selecting Distinct Values
~~~~~~~~~~~~~~~~~~~~~~~~~

Sometimes you may want to get an array of distinct values in a
collection. You can accomplish this using the ``distinct()``
method:

.. code-block:: php

    <?php

    $ages = $dm->createQueryBuilder('User')
        ->distinct('age')
        ->getQuery()
        ->execute();

The above would give you an ``ArrayCollection`` of all the distinct user ages!

.. note::

    MongoDB's `distinct command <http://docs.mongodb.org/manual/reference/command/distinct/>`_
    does not support sorting, so you cannot combine ``distinct()`` with
    ``sort()``. If you would like to sort the results of a distinct query, you
    will need to do so in PHP after executing the query.

Refreshing Documents
~~~~~~~~~~~~~~~~~~~~

When a query (e.g. geoNear, find) returns one or more hydrated documents whose
identifiers are already in the identity map, ODM returns the managed document
instances for those results. In this case, a managed document's data may differ
from whatever was just returned by the database query.

{'fraction_non_alphanumeric': 0.152613386404106, 'fraction_numerical': 0.0, 'mean_word_length': 3.404059040590406, 'pattern_counts': {'":': 0, '<': 28, '<?xml version=': 0, '>': 68, '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': '4809507', 'n_tokens_mistral': 2806, 'n_tokens_neox': 2657, 'n_words': 1122}