docs/_includes/api/query_index.html

{% 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` Matches if all the selectors in the array match.
  * `$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.

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. If you want to see the query plan for your query, then turn on debugging:

{% highlight js %}
PouchDB.debug.enable('pouchdb:find');
{% endhighlight %}

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