{% 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 %}