Query Index - Pouchdb

{% 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 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 { const 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. ### 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. Default is 25 when connected to a local database. * 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 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 { const 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 { const 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 { const 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 { const 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 { const 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 %}