MongoDB ODM: Query Builder API
Posted on
The Doctrine MongoDB Object Document Mapper includes a fluent object oriented API for building queries to execute against MongoDB. Recently some changes were made to the API to simplify it and make it more readable. This blog post aims to demonstrate and introduce the new API to you!
Query Types
The API still supports all the types of queries you would expect:
Continue reading to see examples for each of the above types of queries!
## Find
You can easily find documents by just creating a new Query
object with
the createQuery()
method. A new Query
object defaults to a find
query so you just need to pass the name of the document to query for:
<?php
$q = $dm->createQuery('User');
You can change the document being queried for by using the find()
method:
<?php
$q->find('Project');
Conditions
You can limit the returned documents by specifying some conditions:
<?php
$q->field('title')->equals('The Doctrine Project');
Maybe you want to only return projects created after today:
<?php
$q->field('createdAt')->greaterThan(new MongoDate(time()));
You can even a condition on an embedded document:
<?php
$q->field('profile.firstName')->equals('Jonathan');
Also, you can add a condition for a referenced document to filter by id:
<?php
$q->field('account.$id')->equals($accountId);
The field()
method specifies the current field to add the conditions
to. You can optionally use the magical __call()
feature of the Query
object to specify the current field as well:
<?php
$q->createdAt()->greaterThan(new MongoDate(time()));
All the methods you'd expect can be used in combination with the
field()
method for adding conditions to your query:
- equal(\$value)
- where(\$javascript)
- not(\$value)
- in(\$values)
- notIn(\$values)
- notEqual(\$value)
- greaterThan(\$value)
- greaterThanOrEq(\$value)
- lessThan(\$value)
- lessThanOrEq(\$value)
- range(\$start, \$end)
- size(\$size)
- exists(\$bool)
- type(\$type)
- all(\$values)
- mod(\$mod)
## Insert
You can easily insert new documents using the Query
API as well. Just
use the insert()
method in combination with field()
and set()
:
<?php
$q = $dm->createQuery('User')
->insert()
->field('username')->set('jwage')
->field('password')->set('password');
If you want to set the new document to insert you can use the
setNewObj()
method:
<?php
$q = $dm->createQuery('User')
->insert()
->setNewObj(array(
'username' => 'jwage',
'password' => 'password'
));
## Update
If you want to update a document you can use the update()
method in
combination with field()
, set()
and conditions. Here is an example
where we create a query to update a user with the username jwage
and
give him a new password:
<?php
$q = $dm->createQuery('User')
->update()
->field('password')->set('newpassword')
->field('username')->equals('jwage');
## Delete
You can delete documents as well by using the delete()
method in
combination with conditions. Here is an example where we create a query
to delete the user document with a username of jwage
:
<?php
$q = $dm->createQuery('User')
->delete()
->field('username')->equals('jwage');
As you can see the fluent API makes it a bit easier to express queries that are easy to read in the same way you would read english from left to right. We hope to enhance and improve this API even more before we release the stable 1.0 version.
You can read more about the Query Builder API in the documentation.