Permalink
Browse files

Merge pull request #15 from dantleech/qb_reference

Added descendant(), like and textSearch doc section
  • Loading branch information...
2 parents c71d796 + 2686ef5 commit 4cf7f3ea4f7816eda6e1cb3ca8df48022086d87b @lsmith77 lsmith77 committed Jan 20, 2013
Showing with 217 additions and 6 deletions.
  1. +1 −0 en/index.rst
  2. +62 −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
---------------------------------
@@ -40,7 +39,7 @@ is equal to ``daniel`` and orders the results by ``username`` in ascending order
.. note::
Unlike the ORM it is not nescessary to specify a source to select from, the above
- example will **any** document matching the criteria.
+ example will find **any** class of document matching the criteria.
Via a document repository
~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -57,7 +56,9 @@ will automatically select only those records which are associated with the ``Doc
$posts = $qb->getQuery()->execute();
The above code block will select all documents in the document tree of class ``Post``. This
-feature is especially usefull within a document repository class.
+feature is especially useful within a document repository class.
+
+Example showing the use of the query builder in a ``DocumentRepository``:
.. code-block:: php
@@ -354,6 +355,61 @@ than or equal to the given value.
$qb->expr()->lte('number_of_logins', 50);
+.. _qbref_expr_like:
+
+like
+~~~~
+
+Specify that the value of the given field name on the candidate document must match
+the given pattern. "%" is a wildcard.
+
+.. code-block:: php
+
+ <?php
+
+ $qb->expr()->like('name', 'cAtS'); // case insesitive will match "CATS" and "cats"
+ $qb->expr()->like('name', '%og'); // will match "dog" but not "doggy"
+ $qb->expr()->like('name', '%og%'); // will match "dog" and "dogs"
+ $qb->expr()->like('name', 'dog%'); // will match "dog" and "dogs" but not "the dog"
+
+.. _qbref_expr_descendant:
+
+descendant
+~~~~~~~~~~
+
+Specify that candidate documents must be descendants of the ancestor at the given path.
+
+.. code-block:: php
+
+ <?php
+
+ $qb->expr()->descendant('/blog/posts');
+
+textSearch
+~~~~~~~~~~
+
+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');
+
+Search on **all** document types where **any** field **contains** the word "computer":
+
+.. code-block:: php
+
+ <?php
+
+ $qb = // new query builder
+ $qb->expr()->textSearch(null, '*computer*');
+
.. _qbref_phpcrquerybuilder:
The PHPCR QueryBuilder
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 4cf7f3e

Please sign in to comment.