.. _queryref:

The Query Object
================

Queries at the ODM layer are encapsulated in the `Query` object. This
object is generated by the :ref:`QueryBuilder <qbref_workingwiththequerybuilder>`
and is the object which mediates the transformation of queries to results.

Simple example:

.. code-block:: php

    <?php

    $qb = // create a new query builder instance
    $qb->where($qb->expr()->eq('foo', 'bar'));
    $query = $qb->getQuery(); // return a new Query object
    $results = $query->getResult(); // get the results of the query

Once you have retrieved this class from the query builder it is
ready to go, you have multiple ways for retrieving your data.

Getting single results
----------------------

getSingleResult
~~~~~~~~~~~~~~~

Returns a **single** result using the given :ref:`hydration mode <queryref_hydration>`, if
no results are found, or if the number of results exceeds one it will throw a ``QueryException``.

.. code-block:: php

    <?php

    use Doctrine\ODM\PHPCR\Query\QueryException;

    $query = // get query
    $query->setMaxResults(1); // remember we get an exception if there is more than one

    try {
        // default action is always to return a Document
        $document = $query->getSingleResult();
    } catch (QueryException $e)
        // no result or non unique result
    }

    // we can specify an alternative hydration mode if we want
    $node = $query->getSingleResult(Query::HYDRATE_PHPCR)

.. note::

   We should be providing seperate exception types for NoResult and NonUniqueResult
   respectively. QueryException can also mean "Hydration Mode not implemented"" for example.

getOneOrNullResult
~~~~~~~~~~~~~~~~~~

Either returns a **single** result or returns ``NULL`` using the 
given :ref:`hydration mode <queryref_hydration>`

Getting multiple results
------------------------

.. _queryref_getresult:

getResult
~~~~~~~~~

Returns **all** results for the query using the given 
:ref:`hydration mode <queryref_hydration>`.

.. _queryref_getphpcrnoderesult:

getPhpcrNodeResult
~~~~~~~~~~~~~~~~~~

Returns **all** results for the query in PHPCR node format,
this method is a proxy for ``getResult(Query::HYDRATE_PHPCR)``.

execute
~~~~~~~

This method is the base method for all other retrieval methods. It
is equivalent to the :ref:`getResult <queryref_getresult>` method, but allows you
to specify an array of parameters as the first argument.

.. code-block:: php

    <?php

    $query = // get new query 
    $docs = $q->execute();

    // is equivalenet to

    $query = // get new query 
    $docs = $query->execute(array(), Query::HYDRATE_DOCUMENT);

.. note::

    At time of writing parameters are not yet supported in the ODM.

.. _queryref_hydration:

Hydration modes
---------------

Currently the ``Query`` object allows you to retrieve data in two formats, raw
PHPCR nodes and ODM Documents. The later being the default.

The hydration mode is specified by the use of the ``Query::HYDRATE_*`` constants.

.. code-block:: php
    
    <?php

    use Doctrine\ODM\PHPCR\Query\Query;

    // HYDRATE_DOCUMENT
    $document = $query->getSingleResult(Query::HYDRATE_DOCUMENT); // the default mode
    $document->getSomething();

    // HYDRATE_PHPCR
    $node = $query->getSingleResult(Query::HYDRATE_PHPCR);
    $node->getProperty('my_property_name');

.. note::

    In the future we will also enable the retrieval of results in Array format.

.. _queryref_limitingresults:

Limiting results
----------------

The ``Query`` object allows you to specify the maximum number of results
that should be retrieved, and also the record index from which the results 
should be retrieved.

.. code-block:: php

    <?php

    $query = // get query
    $query->setMaxResults(100);
    $res = $query->getResult(); // will return a maximum of 100 results

    $query = // get query
    $query->setOffset(50);
    $query->setMaxResults(150);
    $res = $query->getResult(); // will return a maximum of 100 results from result index 50