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

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"
                }
            ]
        }
    }
]
 */
}

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"
}
 */

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);

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": [
            {}
        ]
    }
}