{% include anchor.html edit="true" title="Query index" hash="query_index" %} {% highlight js %} db.find(request [, callback]) {% endhighlight %} Query an index and return the list of documents that match the request. {% include alert/start.html variant="info"%} {% markdown %} **pouchdb-find plugin needed:** This API requires the `pouchdb-find` plugin. See [Mango queries](/guides/mango-queries.html) for installation instructions. {% endmarkdown %} {% include alert/end.html%} #### Example Usage: {% include code/start.html id="query_idx" type="callback" %} {% highlight js %} db.find({ selector: {name: 'Mario'}, fields: ['_id', 'name'], sort: ['name'] }, function (err, result) { if (err) { return console.log(err); } // handle result }); {% endhighlight %} {% include code/end.html %} {% include code/start.html id="query_idx" type="async" %} {% highlight js %} try { var result = await db.find({ selector: {name: 'Mario'}, fields: ['_id', 'name'], sort: ['name'] }); } catch (err) { console.log(err); } {% endhighlight %} {% include code/end.html %} {% include code/start.html id="query_idx" type="promise" %} {% highlight js %} db.find({ selector: {name: 'Mario'}, fields: ['_id', 'name'], sort: ['name'] }).then(function (result) { // handle result }).catch(function (err) { console.log(err); }); {% endhighlight %} {% include code/end.html %} #### Example Response: {% highlight js %} { "docs": [ { "_id": "mario", "name": "Mario" } ] } {% endhighlight %} The above is a simple example. For an in-depth tutorial, please refer to [the Mango guide](/guides/mango-queries.html). ### Options * `selector` Defines a selector to filter the results. Required. * `$lt` Match fields "less than" this one. * `$gt` Match fields "greater than" this one. * `$lte` Match fields "less than or equal to" this one. * `$gte` Match fields "greater than or equal to" this one. * `$eq` Match fields equal to this one. * `$ne` Match fields not equal to this one. * `$exists` True if the field should exist, false otherwise. * `$type` One of: "null", "boolean", "number", "string", "array", or "object". * `$in` The document field must exist in the list provided. * `$and` Matches if all the selectors in the array match. * `$nin` The document field must not exist in the list provided. * `$all` Matches an array value if it contains all the elements of the argument array. * `$size` Special condition to match the length of an array field in a document. * `$or` Matches if any of the selectors in the array match. All selectors must use the same index. * `$nor` Matches if none of the selectors in the array match. * `$not` Matches if the given selector does not match. * `$mod` Matches documents where (field % Divisor == Remainder) is true, and only when the document field is an integer. * `$regex` A regular expression pattern to match against the document field. * `$elemMatch` Matches all documents that contain an array field with at least one element that matches all the specified query criteria. * `fields` (Optional) Defines a list of fields that you want to receive. If omitted, you get the full documents. * `sort` (Optional) Defines a list of fields defining how you want to sort. Note that sorted fields also have to be selected in the `selector`. * `limit` (Optional) Maximum number of documents to return. * `skip` (Optional) Number of docs to skip before returning. * `use_index` (Optional) Set which index to use for the query. It can be "design-doc-name" or "['design-doc-name', 'name']". If there's no index that matches your `selector`/`sort`, then this method will issue a warning: {% highlight js %} { "docs": [ /* ... */ ], "warning": "No matching index found, create an index to optimize query time." } {% endhighlight %} The best index will be chosen automatically. See the [CouchDB `_find` documentation](http://docs.couchdb.org/en/2.0.0/api/database/find.html) for more details on selectors and the Mango query language. ### More examples Use `$eq` for "equals": {% include code/start.html id="query_idx2" type="callback" %} {% highlight js %} db.find({ selector: {name: {$eq: 'Mario'}} }, function (err, result) { if (err) { return console.log(err); } // handle result }); {% endhighlight %} {% include code/end.html %} {% include code/start.html id="query_idx2" type="async" %} {% highlight js %} try { var result = await db.find({ selector: {name: {$eq: 'Mario'}} }); } catch (err) { console.log(err); } {% endhighlight %} {% include code/end.html %} {% include code/start.html id="query_idx2" type="promise" %} {% highlight js %} db.find({ selector: {name: {$eq: 'Mario'}} }).then(function (result) { // handle result }).catch(function (err) { console.log(err); }); {% endhighlight %} {% include code/end.html %} This is equivalent to: {% include code/start.html id="query_idx3" type="callback" %} {% highlight js %} db.find({ selector: {name: 'Mario'} }, function (err, result) { if (err) { return console.log(err); } // handle result }); {% endhighlight %} {% include code/end.html %} {% include code/start.html id="query_idx3" type="async" %} {% highlight js %} try { var result = await db.find({ selector: {name: 'Mario'} }); } catch (err) { console.log(err); } {% endhighlight %} {% include code/end.html %} {% include code/start.html id="query_idx3" type="promise" %} {% highlight js %} db.find({ selector: {name: 'Mario'} }).then(function (result) { // handle result }).catch(function (err) { console.log(err); }); {% endhighlight %} {% include code/end.html %} You can also do selections on multiple fields. For instance, to find all docs where `series` is `'Mario'` and `debut` is greater than `1990`: {% include code/start.html id="query_idx4" type="callback" %} {% highlight js %} db.find({ selector: { series: 'Mario', debut: { $gt: 1990 } } }, function (err, result) { if (err) { return console.log(err); } // handle result }); {% endhighlight %} {% include code/end.html %} {% include code/start.html id="query_idx4" type="async" %} {% highlight js %} try { var result = await db.find({ selector: { series: 'Mario', debut: { $gt: 1990 } } }); } catch (err) { console.log(err); } {% endhighlight %} {% include code/end.html %} {% include code/start.html id="query_idx4" type="promise" %} {% highlight js %} db.find({ selector: { series: 'Mario', debut: { $gt: 1990 } } }).then(function (result) { // handle result }).catch(function (err) { console.log(err); }); {% endhighlight %} {% include code/end.html %} This is equivalent to: {% include code/start.html id="query_idx5" type="callback" %} {% highlight js %} db.find({ selector: { $and: [ { series: 'Mario' }, { debut: { $gt: 1990 } } ] } }, function (err, result) { if (err) { return console.log(err); } // handle result }); {% endhighlight %} {% include code/end.html %} {% include code/start.html id="query_idx5" type="async" %} {% highlight js %} try { var result = await db.find({ selector: { $and: [ { series: 'Mario' }, { debut: { $gt: 1990 } } ] } }); } catch (err) { console.log(err); } {% endhighlight %} {% include code/end.html %} {% include code/start.html id="query_idx5" type="promise" %} {% highlight js %} db.find({ selector: { $and: [ { series: 'Mario' }, { debut: { $gt: 1990 } } ] } }).then(function (result) { // handle result }).catch(function (err) { console.log(err); }); {% endhighlight %} {% include code/end.html %} You can also sort the returned documents. For instance, to find all docs sorted by `debut` descending: {% include code/start.html id="query_idx6" type="callback" %} {% highlight js %} db.find({ selector: { debut: {'$gte': null} }, sort: [{debut: 'desc'}] }, function (err, result) { if (err) { return console.log(err); } // handle result }); {% endhighlight %} {% include code/end.html %} {% include code/start.html id="query_idx6" type="async" %} {% highlight js %} try { var result = await db.find({ selector: { debut: {'$gte': null} }, sort: [{debut: 'desc'}] }); } catch (err) { console.log(err); } {% endhighlight %} {% include code/end.html %} {% include code/start.html id="query_idx6" type="promise" %} {% highlight js %} db.find({ selector: { debut: {'$gte': null} }, sort: [{debut: 'desc'}] }).then(function (result) { // handle result }).catch(function (err) { console.log(err); }); {% endhighlight %} {% include code/end.html %}