Query Builder Reference

Note

This document is generated by the PHPCR-ODM from the API, if you wish to contribute a fix please either create an issue or make a pull request on the phpcr-odm repository.

All the classes here documented can be found in the namespace: Doctrine\ODM\PHPCR\Query\Builder

Reference

Node: ConstraintAndx

Contraint which evaluates to true when all its child constraints evaluate to true.

If only a single constraint is appended, the appended constraint will behave as if it were not preceded by the ConstraintAndX.

Type: constraint

Extends: ConstraintFactory

Inherited methods: andX, orX, fieldIsset, fullTextSearch, same, descendant, child, eq, neq, lt, lte, gt, gte, like

Child Cardinality:
  • 1..* constraint

Node: ConstraintComparison

Constraint which evaluates to true if the dynamic child operand and the static child operand evaluate to true when operated upon by the given operator.

The ConstraintFactory will specify the corresponding operator for each of “eq”, “gte”, “gt”, “lte”, “lt”, “like”, etc.

A dynamic operand is an operand whose value is derived from the persisted object set.

A static operand is a non-changing value, either a literal or a bound property.

Comparisons can only be made one dynamic and one static operand. When comparing the values between joined tables you will need to use the JoinConditionFactory.

Type: constraint

Extends: OperandFactory

Inherited methods: parameter, literal, fullTextSearchScore, length, lowerCase, upperCase, localName, name, field

Child Cardinality:
  • 1..1 operand_dynamic
  • 1..1 operand_static

Node: ConstraintFactory

This factory node provides both leaf and factory nodes all of which return nodes of type “constraint”.

Type: constraint_factory

Child Cardinality:
  • 1..1 constraint

->andX

And composite constraint.

<?php
$qb->where()->andX()
  ->fieldIsset('f.foo')
  ->gt()->field('f.max')->literal(40);

The andX node allows you to add 1, 2 or many operand nodes. When one operand is added the “and” is removed, when more than one is added the “and” operands are nested.

<?php
// when adding only a single operand,
$qb->where()->andX()->eq()->field('f.foo')->literal('bar');
// is equivilent to:
$qb->where()->eq()->field('f.foo')->literal('bar');


// when adding more than one,
$qb->where()->andX()
  ->fieldIsset('f.foo')
  ->gt()->field('f.max')->literal(40);
  ->eq()->field('f.zar')->literal('bar')

// is equivilent to:
$qb->where()->andX()
  ->andX()
    ->fieldIsset('f.foo')
    ->gt()->field('f.max')->literal(40);
  ->eq()->field('f.zar')->litreal('bar');

Adds: constraint (ConstraintAndx)

Returns: ConstraintAndx

->orX

Or composite constraint.

<?php
$qb->where()
  ->orX()
    ->fieldIsset('sel_1.prop_1')
    ->fieldIsset('sel_1.prop_2')
  ->end();

As with “andX”, “orX” allows one to many operands.

Adds: constraint (ConstraintOrx)

Returns: ConstraintOrx

->fieldIsset

Field existance constraint:

<?php
$qb->where()->fieldIsset('sel_1.prop_1');

Adds: constraint (ConstraintFieldIsset)

Returns: ConstraintFactory

Arguments:

  • $field: string - Field to check

->fullTextSearch

Full text search constraint.

<?php
$qb->where()->fullTextSearch('sel_1.prop_1', 'search_expression');

Adds: constraint (ConstraintFullTextSearch)

Returns: ConstraintFactory

Arguments:

  • $field: string - Name of field to check, including alias name.
  • $fullTextSearchExpression: string - Search expression.

->same

Same document constraint.

<?php
$qb->where()->same('/path/to/doc', 'sel_1');

Relates to PHPCR QOM SameNodeInterface.

Adds: constraint (ConstraintSame)

Returns: ConstraintFactory

Arguments:

  • $path: string - Path to reference document.
  • $alias: string - Name of alias to use.

->descendant

Descendant document constraint.

<?php
  $qb->where()->descendant('/ancestor/path', 'sel_1');

Relates to PHPCR QOM DescendantNodeInterface

Adds: constraint (ConstraintDescendant)

Returns: ConstraintFactory

Arguments:

  • $ancestorPath: string - Select descendants of this path.
  • $alias: string - Name of alias to use.

->child

Select children of the aliased document at the given path.

<?php
$qb->where()->child('/parent/path', 'sel_1');

Relates to PHPCR QOM ChildNodeInterface.

Adds: constraint (ConstraintChild)

Returns: ConstraintFactory

Arguments:

  • $parentPath: string - Select children of this path.
  • $alias: string - Name of alias to use

->eq

Equality comparison constraint.

<?php
$qb->where()
  ->eq()
    ->field('sel_1.foobar')
    ->literal('var_1');

Adds: constraint (ConstraintComparison)

Returns: ConstraintComparison

->neq

Inequality comparison constraint

<?php
$qb->where()
  ->neq()
    ->field('sel_1.foobar')
    ->literal('var_1');

Adds: constraint (ConstraintComparison)

Returns: ConstraintComparison

->lt

Less than comparison constraint.

<?php
$qb->where()
  ->lt()
    ->field('sel_1.foobar')
    ->literal(5);

Adds: constraint (ConstraintComparison)

Returns: ConstraintComparison

->lte

Less than or equal to comparison constraint.

<?php
$qb->where()
  ->lte()
    ->field('sel_1.foobar')
    ->literal(5);

Adds: constraint (ConstraintComparison)

Returns: ConstraintComparison

->gt

Greater than comparison constraint.

<?php
$qb->where()
  ->gt()
    ->field('sel_1.foobar')
    ->literal(5);

Adds: constraint (ConstraintComparison)

Returns: ConstraintComparison

->gte

Greater than or equal to comparison constraint.

<?php
$qb->where()
  ->gte()
    ->field('sel_1.foobar')
    ->literal(5);

Adds: constraint (ConstraintComparison)

Returns: ConstraintComparison

->like

Like comparison constraint.

Use “%” as wildcards.

<?php
$qb->where()
  ->like()
    ->field('sel_1.foobar')
    ->literal('foo%');

The above example will match “foo” and “foobar” but not “barfoo”.

Adds: constraint (ConstraintComparison)

Returns: ConstraintComparison

Node: ConstraintNot

Constraint which evaluates to the opposite truth of its child operand.

Type: constraint

Extends: ConstraintFactory

Inherited methods: andX, orX, fieldIsset, fullTextSearch, same, descendant, child, eq, neq, lt, lte, gt, gte, like

Child Cardinality:
  • 1..1 constraint

Node: ConstraintOrx

Constraint which evaluates to true if any one of ites children evaluates to true.

Like the ConstraintAndx constraint a single child will act as if it were not preceded with a ConstraintOrx.

Type: constraint

Extends: ConstraintFactory

Inherited methods: andX, orX, fieldIsset, fullTextSearch, same, descendant, child, eq, neq, lt, lte, gt, gte, like

Child Cardinality:
  • 1..* constraint

Node: From

The From node specifies the document source (or sources in the case of a join).

Type: from

Child Cardinality:
  • 1..1 source

Node: OperandDynamicFactory

Factory node for dynamic operands.

Type: operand_dynamic_factory

Child Cardinality:
  • 1..1 operand_dynamic

->fullTextSearchScore

Represents the aliased documents rank by relevance to the full text search expression given by the “fullTextSearch” constraint.

See also: http://www.day.com/specs/jcr/2.0/6_Query.html#FullTextSearchScore

<?php
$qb->where()
  ->gt()
    ->fullTextSearchScore('sel_1')
    ->literal(50)
  ->end()

$qb->orderBy()
   ->asc()->fullTextSearchScore('sel_1');

Adds: operand_dynamic (OperandDynamicFullTextSearchScore)

Returns: OperandDynamicFactory

Arguments:

  • $alias: string - Name of alias to use

->length

Length operand resolves to length of aliased document.

<?php
$qb->where()
  ->gt()
    ->length('alias_1.prop_1')
    ->literal(50);

$qb->orderBy()->asc()->fullTextSearchScore('sel_1');

Adds: operand_dynamic (OperandDynamicLength)

Returns: OperandDynamicFactory

Arguments:

  • $field: string - Name of field to check.

->lowerCase

LowerCase operand evaluates to lower-cased string of child operand:

<?php
$qb->where()
  ->eq()
    ->lowerCase()->field('sel_1.prop_1')->end()
    ->literal('lower_case');

Adds: operand_dynamic (OperandDynamicLowerCase)

Returns: OperandDynamicLowerCase

->upperCase

UpperCase operand evaluates to upper-cased string of child operand:

<?php
$qb->where()
  ->eq()
      ->upperCase()->field('sel_1.prop_1')->end()
      ->literal('UPPER_CASE');

Adds: operand_dynamic (OperandDynamicUpperCase)

Returns: OperandDynamicUpperCase

->localName

Document local name evaluates to the local (non namespaced) name of the node being compared.

For example, if a node has the path “/path/to/foobar”, then “foobar” is the local node name.

<?php
$qb->where()
  ->eq()
    ->localName('sel_1')
    ->literal('my_node_name');

Relates to PHPCR NodeLocalNameInterface

Adds: operand_dynamic (OperandDynamicLocalName)

Returns: OperandDynamicFactory

Arguments:

  • $alias: string - Name of alias to use

->name

Evaluates to the namespaced name of the node being compared.

For example, if a node has the path “/path/to/bar:foobar”, then “bar:foobar” is the namespaced node name.

<?php
$qb->where()
  ->eq()
    ->name('sel_1')
    ->literal('namespace:my_node_name');

Relates to PHPCR NodeNameInterface.

Adds: operand_dynamic (OperandDynamicName)

Returns: OperandDynamicFactory

Arguments:

  • $alias: string - Name of alias to use

->field

Evaluates to the value of the specified field.

<?php
$qb->where()
  ->eq()
    ->field('sel_1.prop_name')
    ->literal('my_field_value');

Adds: operand_dynamic (OperandDynamicField)

Returns: OperandDynamicFactory

Arguments:

  • $field: string - name of field to check, including alias name.

Node: OperandDynamicLowerCase

Dynamic operand which evaluates to the lowercased value of the child operand.

Type: operand_dynamic

Extends: OperandDynamicFactory

Inherited methods: fullTextSearchScore, length, lowerCase, upperCase, localName, name, field

Child Cardinality:
  • 1..1 operand_dynamic

Node: OperandDynamicUpperCase

Operand which evaluates to the upper case version of its child operand.

Type: operand_dynamic

Extends: OperandDynamicFactory

Inherited methods: fullTextSearchScore, length, lowerCase, upperCase, localName, name, field

Child Cardinality:
  • 1..1 operand_dynamic

Node: OperandFactory

Factory node for all operands, both dynamic and static.

Type: operand_dynamic_factory

Extends: OperandDynamicFactory

Inherited methods: fullTextSearchScore, length, lowerCase, upperCase, localName, name, field

Child Cardinality:
  • 1..1 operand_dynamic

->parameter

Evaluates to the value of the parameter bound to the given $name.

Relates to PHPCR BindVariableValueInterface

<?php
$qb->where()->eq()->field('f.foobar')->parameter('param_1');
$qb->setParameter('param_1', 'foo');

Adds: operand_static (OperandStaticParameter)

Returns: OperandFactory

Arguments:

  • $name: string - Name of parameter to resolve.

->literal

Evaluates to the given literal value.

<?php
$qb->where()->eq()->field('f.foobar')->litreal('Literal Value');

Adds: operand_static (OperandStaticLiteral)

Returns: OperandStaticLiteral

Arguments:

  • $value: string - Literal value.

Node: OperandStaticFactory

Factory node for static operands.

Note that this class is not used by the query builder and is only featured here to help with tests.

Type: operand_static_factory

Extends: OperandFactory

Inherited methods: parameter, literal, fullTextSearchScore, length, lowerCase, upperCase, localName, name, field

Child Cardinality:
  • 1..1 operand_static

Node: OrderBy

Factory node for order by.

Query results can be ordered by any dynamic operand in either ascending or descending order.

Type: order_by

Child Cardinality:
  • 0..* ordering

->asc

Add ascending ordering:

<?php
$qb->orderBy()->asc()->field('sel_1.prop_1');

Adds: ordering (Ordering)

Returns: Ordering

->desc

Add descending ordering:

<?php
$qb->orderBy()->desc()->field('sel_1.prop_1');

Adds: ordering (Ordering)

Returns: Ordering

Node: OrderByAdd

Node for adding an additional order by.

Type: order_by

Extends: OrderBy

Inherited methods: asc, desc

Child Cardinality:
  • 0..* ordering

Node: Ordering

Type: ordering

Extends: OperandDynamicFactory

Inherited methods: fullTextSearchScore, length, lowerCase, upperCase, localName, name, field

Child Cardinality:
  • 1..1 operand_dynamic

Node: QueryBuilder

The Query Builder root node.

This is the node which is returned when a query builder is asked for.

<?php
$dm = // get document manager
$qb = $dm->createQueryBuilder();
$qb->fromDocument('Blog\Post', 'p');
$qb->where()->eq()->field('p.title')->literal('My Post');
$docs = $qb->getQuery()->execute();

A converter is required to be set if the purpose of the query builder is to be fulfilled. The PHPCR converter walks over the query builder node hierarchy and converts the object graph the PHPCR QOM object graph.

Type: builder

Child Cardinality:
  • 0..* select
  • 1..1 from
  • 0..1 where
  • 0..* order_by

->where

Where factory node is used to specify selection criteria.

<?php
 $qb->where()->eq()->field('a.foobar')->literal('bar');

Adds: where (Where)

Returns: Where

->andWhere

Add additional selection criteria using the AND operator.

Adds: where (WhereAnd)

Returns: WhereAnd

->orWhere

Add additional selection criteria using the OR operator.

Adds: where (WhereOr)

Returns: WhereOr

->from

Set the from source for the query.

<?php
 $qb->from()->document('Foobar', 'a')

 // or with a join ...

 -$qb->from('a')->joinInner()
   ->left()->document('Foobar', 'a')->end()
   ->right()->document('Barfoo', 'b')->end()
   ->condition()->equi('a.prop_1', 'b.prop_1');

Adds: from (From)

Returns: From

Arguments:

  • $primaryAlias: string - Alias to use as primary source (optional for single sources)

->fromDocument

Shortcut for:

<?php
$qb->from()->document('Foobar', 'a')->end()

Which becomes:

<?php
$qb->fromDocument('Foobar', 'a');

Replaces any existing from source.

Adds: from (From)

Returns: QueryBuilder

Arguments:

  • $documentFqn: string - Fully qualified class name for document.
  • $primaryAlias: string - Alias for document source and primary alias when using multiple sources.

->addJoinLeftOuter

Replace the existing source with a left outer join source using the existing source as the left operand.

<?php
$qb->fromDocument('Foobar', 'a')
->addJoinLeftOuter()
  ->right()->document('Barfoo', 'b')->end()
  ->condition()->equi('a.prop_1', 'b.prop_2');
->end();

Note that this method is currently not implemented until we can decide on how it should work.

Adds: select (Select)

Returns: SourceJoin

->addJoinRightOuter

Replace the existing source with a right outer join source using the existing source as the left operand.

<?php
$qb->fromDocument('Foobar', 'a')
  ->addJoinRightOuter()
    ->right()->document('Barfoo', 'b')->end()
    ->condition()->equi('a.prop_1', 'b.prop_2');

Note that this method is currently not implemented until we can decide on how it should work.

Adds: select (Select)

Returns: SourceJoin

->addJoinInner

Replace the existing source with an inner join source using the existing source as the left operand.

<?php
$qb->fromDocument('Foobar', 'a')
->addJoinInner()
  ->right()->document('Barfoo', 'b')->end()
  ->condition()->equi('a.prop_1', 'b.prop_2');
->end()

Note that this method is currently not implemented until we can decide on how it should work.

Adds: select (Select)

Returns: SourceJoin

->select

Method to add properties for selection to builder tree, replaces any existing select.

Number of property nodes is unbounded.

<?php
$qb->select()
  ->field('a.prop_1')
  ->field('a.prop_2')
  ->field('a.prop_3');

Adds: select (Select)

Returns: Select

->addSelect

Add additional properties to selection.

<?php
$qb->select()
    ->field('a.prop_1')
  ->end()
  ->addSelect()
    ->field('a.prop_2')
    ->field('a.prop_3')
    ->field('a.prop_4');

Adds: select (SelectAdd)

Returns: SelectAdd

->orderBy

Add orderings to the builder tree.

Number of orderings is unbounded.

<?php
$qb->orderBy()
    ->asc()->field('a.prop_1')->end()
    ->desc()->field('a.prop_2');

Adds: order_by (OrderBy)

Returns: OrderBy

->addOrderBy

Add additional orderings to the builder tree.

Adds: order_by (OrderByAdd)

Returns: OrderByAdd

Node: Select

Factory node for adding selection fields.

Type: select

Child Cardinality:
  • 0..* property

Node: SelectAdd

Factory node for adding additional selection fields.

Type: select

Extends: Select

Inherited methods:

Child Cardinality:
  • 0..* property

Node: SourceJoin

$from->joinInner()->left()->document()->

Type: source

Child Cardinality:
  • 1..1 source_join_condition_factory
  • 1..1 source_join_left
  • 1..1 source_join_right

Node: SourceJoinConditionFactory

Factory node for join conditions.

Type: source_join_condition_factory

Child Cardinality:
  • 1..1 source_join_condition

->descendant

Descendant join condition.

<?php
  $qb->from('alias_1')
    ->joinInner()
      ->left()->document('Foo/Bar/One', 'alias_1')->end()
      ->right()->document('Foo/Bar/Two', 'alias_2')->end()
      ->condition()
        ->descendant('alias_1', 'alias_2')
      ->end()
  ->end()

Adds: source_join_condition (SourceJoinConditionDescendant)

Returns: SourceJoinConditionFactory

Arguments:

  • $descendantAlias: string - Name of alias for descendant documents.
  • $ancestorAlias: string - Name of alias to match for ancestor documents.

->equi

Equi (equality) join condition.

<?php
  $qb->from('alias_1')
    ->joinInner()
      ->left()->document('Foo/Bar/One', 'alias_1')->end()
      ->right()->document('Foo/Bar/Two', 'alias_2')->end()
      ->condition()->equi('alias_1.prop_1', 'alias_2.prop_2');

See: http://en.wikipedia.org/wiki/Join_%28SQL%29#Equi-join

Adds: source_join_condition (SourceJoinConditionEqui)

Returns: SourceJoinConditionFactory

Arguments:

  • $field1: string - Field name for first field.
  • $field2: string - Field name for second field.

->child

Child document join condition.

<?php
  $qb->from('alias_1')
    ->joinInner()
      ->left()->document('Foo/Bar/One', 'alias_1')->end()
      ->right()->document('Foo/Bar/Two', 'alias_2')->end()
      ->condition()->child('alias_1', 'alias_2');

Adds: source_join_condition (SourceJoinConditionChildDocument)

Returns: SourceJoinConditionFactory

Arguments:

  • $childAlias: string - Name of alias for child documents.
  • $parentAlias: string - Name of alias to match for parent documents.

->same

Same document join condition:

<?php
  $qb->from('alias_1')
    ->joinInner()
      ->left()->document('Foo/Bar/One', 'alias_1')->end()
      ->right()->document('Foo/Bar/Two', 'alias_2')->end()
      ->condition()
        ->same('alias_1', 'alias_2', '/path_to/alias_2/document')
      ->end()
    ->end()

Adds: source_join_condition (SourceJoinConditionSameDocument)

Returns: SourceJoinConditionFactory

Arguments:

  • $alias1: string - Name of first alias.
  • $alias2: string - Name of first alias.
  • $alias2Path: string - Path for documents of second alias.

Node: SourceJoinLeft

Factory node for “left” source in join.

Type: source_join_left

Extends: From

Inherited methods: document, joinInner, joinLeftOuter, joinRightOuter

Child Cardinality:
  • 1..1 source

Node: SourceJoinRight

Factory node for “right” source in join.

Type: source_join_right

Extends: From

Inherited methods: document, joinInner, joinLeftOuter, joinRightOuter

Child Cardinality:
  • 1..1 source

Node: Where

Factory node for where.

Type: where

Extends: ConstraintFactory

Inherited methods: andX, orX, fieldIsset, fullTextSearch, same, descendant, child, eq, neq, lt, lte, gt, gte, like

Child Cardinality:
  • 1..1 constraint

Node: WhereAnd

Factory node for appending additional “wheres” with an AND

Type: where

Extends: Where

Inherited methods: andX, orX, fieldIsset, fullTextSearch, same, descendant, child, eq, neq, lt, lte, gt, gte, like

Child Cardinality:
  • 1..1 constraint

Node: WhereOr

Factory node for appending additional “wheres” with an OR

Type: where

Extends: Where

Inherited methods: andX, orX, fieldIsset, fullTextSearch, same, descendant, child, eq, neq, lt, lte, gt, gte, like

Child Cardinality:
  • 1..1 constraint
Fork me on GitHub