Added query reference

en/index.rst

@@ -48,6 +48,7 @@ Working with Objects
 
 * **Query Reference**:
   :doc:`Query Builder API <reference/query-builder>`
+  :doc:`The Query Object <reference/query>`
 
 Advanced Topics
 ---------------

en/reference/query-builder.rst

@@ -1,11 +1,10 @@
+.. _qbref:
+
 The QueryBuilder
 ================
 
 The ``QueryBuilder`` provides an API that is designed for
-programmatically constructing an ODM query object.
-
-It provides a set of classes and methods that is able to
-programmatically build queries, and also provides a fluent API.
+programmatically constructing ODM :ref:`query <queryref>` objects.
 
 Creating a query builder instance
 ---------------------------------
@@ -393,15 +392,23 @@ Perform a text search - perform a full text search on the specified field.
 
 See `the JCR reference <http://docs.jboss.org/jbossdna/0.7/manuals/reference/html/jcr-query-and-search.html#fulltext-search-query-language>`_ for more information about query syntax.
 
+Search on **all** document types where **body** fields are equal to **dog**:
+
 .. code-block:: php
 
    <?php
 
+   $qb = // new query builder
    $qb->expr()->textSearch('body', 'dog');
 
-.. note::
+Search on **all** document types where **any** field **contains** the word "computer":
+
+.. code-block:: php
+
+   <?php
 
-   TODO: It would be really good to have some good text search examples here.
+   $qb = // new query builder
+   $qb->expr()->textSearch(null, '*computer*');
 
 .. _qbref_phpcrquerybuilder:
 

en/reference/query.rst

@@ -0,0 +1,154 @@
+.. _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->getResults(); // 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
+