Mango Query¶
Summary¶
With the new release of CouchDB 2.0, Apache brought us the Mango Query. It’s an adapted version of Cloudant Query for CouchDB. It’s very similar to MongoDB Query syntax.
It lets you create indexes and perform queries with more ease that map/reduce. For more details, you may take a look at this :
PHPOnCouch and Mango¶
With the recently added new available function to let you use the new Mango Query. This is very minimalist at the moment but feel free to suggest any ameliorations.
The Mango Query functionalities have been implemented directly in the CouchClient.
Functions¶
-
class
PHPOnCouch\
CouchClient
¶
getIndexes¶
PHPOnCouch\CouchClient::
getIndexes
()¶This function returns you an array of indexes. Each index will have those properties :
- ddoc: The design document id of the index
- name: The name of the index
- type: The type of the index (special,text,json)
- def: The fields indexes
By default, you always have one index: _all_docs
Example :
$indexes = $client->getIndexes(); /* [ { "ddoc": null, "name": "_all_docs", "type": "special", "def": { "fields": [ { "_id": "asc" } ] } } ] */ }
createIndex¶
PHPOnCouch\CouchClient::
createIndex
(array $fields, $name = null, $ddoc = null, $type = 'json')¶This function creates an index.
Params array $fields: The fields that will be indexed
Params string $name: The name of the index. If null, one will be generated by Couch.
Params string $ddoc: The design document id to store the index. If null, CouchDB will create one.
Params string $type: The type of the index. Only JSON is supported for the moment.
Returns stdClass: An object. The object contains the following properties:
- result : Message that normally returns “created” or “exists”
- id : The id of the undex.
- name : The name of the index.
Example :
$index = client->createIndex(['firstName', 'birthDate', 'lastName'], 'personIdx', 'person'); /* $index should give : { "result":"created", "id":"_design/person", "name":"personIdx" } */
find¶
PHPOnCouch\CouchClient::
find
($selector, $index = null)¶The new find() function let you query the database by using the new Mango Query. You can provide a selector query multiple fields and use conditional queries. You can sort your query and also determine which fields you want to retrieve. CouchDB will automatically select the most efficient index for your query but it’s preferred to specify the index for faster results. Also, the limit(number) and skip(number) can be applied to the client before the query.
Supported query parameters
You can use the following query parameters :
- limit(number) : Limit the number of documents that will be returned.
- skip(n) : Skip n documents and return the documents following.
- sort(sortSyntax) : Array or values that follow the sort syntax
- fields(fieldsArray) : An array of fields that you want to return from the documents. If null, all the fields will be returned.
Params stdClass|array $selector: A selector object or array that follows the Mango query documentation Params string $index: The name of the index to use(“<design_document>” or [“<design_document>”, “<index_name>”]). Otherwise automatically choosen. Returns array: Returns an array of documents Example :
$selector = [ '$and' => [ ['age' => ['$gt' => 16]], ['gender' => ['$eq' => 'Female']] ] ]; $docs = $client->skip(10)->limit(30)->sort(["age"])->fields(['firstName'])->find($selector);
explain¶
PHPOnCouch\CouchClient::
explain
($selector, $index = null)¶Let you perform a query like if you were using the
CouchClient::find
function. Therefore, the explain will not returns any documents. Instead, it will give you all the details about the query. For example, it could tell you which index has been automatically selected.For the parameter, please refer to the
CouchClient::find
parameters.
Returns: It returns a object with a lot of detailed properties. Here are main properties :
- dbname : The name of the database
- index : Index object used to fullfil the query
- selector : The selector used for the query
- opts : The query options used for the query
- limit : The limit used
- skip : The skip parameter used
- fields : The fields returned by the query
- range : Range parameters passed to the underlying view
Example :
$selector = [ 'year'=>['$gt'=>2010] ]; $details = $client->skip(0)->limit(2)->fields(['_id','_rev','year','title'])->sort(['year'=>'asc'])->find($selector);The $details values would be the equivalent in JSON :
{ "dbname": "movies", "index": { "ddoc": "_design/0d61d9177426b1e2aa8d0fe732ec6e506f5d443c", "name": "0d61d9177426b1e2aa8d0fe732ec6e506f5d443c", "type": "json", "def": { "fields": [ { "year": "asc" } ] } }, "selector": { "year": { "$gt": 2010 } }, "opts": { "use_index": [], "bookmark": "nil", "limit": 2, "skip": 0, "sort": {}, "fields": [ "_id", "_rev", "year", "title" ], "r": [ 49 ], "conflicts": false }, "limit": 2, "skip": 0, "fields": [ "_id", "_rev", "year", "title" ], "range": { "start_key": [ 2010 ], "end_key": [ {} ] } }