Permalink
Browse files

Added query reference

  • Loading branch information...
1 parent 067f9a1 commit 2686ef598d58f16b6b3411a349232bc2cd75c17e @dantleech dantleech committed Jan 20, 2013
Showing with 168 additions and 6 deletions.
  1. +1 −0 en/index.rst
  2. +13 −6 en/reference/query-builder.rst
  3. +154 −0 en/reference/query.rst
View
@@ -48,6 +48,7 @@ Working with Objects
* **Query Reference**:
:doc:`Query Builder API <reference/query-builder>`
+ :doc:`The Query Object <reference/query>`
Advanced Topics
---------------
@@ -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:
View
@@ -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
+

0 comments on commit 2686ef5

Please sign in to comment.