Home

Awesome

⚠️ NOTE ⚠️: this project has moved to the PouchDB GitHub repo. Please submit new issues/PRs there!

The pouchdb-find plugin is being incorporated into PouchDB itself. Original documentation follows:

PouchDB Find Build Status Coverage Status

(Live demo)

Provides a simple, MongoDB-inspired query language that accomplishes the same thing as the map/reduce API, but with far less code.

Eventually this will replace PouchDB's map/reduce API entirely. You'll still be able to use map/reduce, but it will be distributed as a separate plugin.

Status

Implemented: $lt, $gt, $lte, $gte, $eq, $exists, $type, $in, $nin, $all, $size, $or, $nor, $not, $mod, $regex, $elemMatch, multi-field queries, multi-field indexes, multi-field sort, 'deep.fields.like.this', ascending and descending sort.

0.2.0: $and, $ne

0.3.0: limit, skip, ddoc when creating an index

0.4.0: total_rows

0.5.0: $in, $nin, $all, $size

0.6.0: $or, $nor, $not

0.7.0: $elemMatch, $regex

0.8.0: Bug fixes for $and, $type, $exists

0.9.0: Bug fixes for $elemMatch. Rewrite of in-memory operator

0.10.0: Update for latest Mango spec (warnings instead of errors), update for PouchDB 5.4.0.

Usage

In the browser

To use this plugin in the browser, include it after pouchdb.js in your HTML page:

<script src="pouchdb.js"></script>
<script src="pouchdb.find.js"></script>

You can also download it from Bower:

bower install pouchdb-find

In Node.js/Browserify

Or to use it in Node.js, just npm install it:

npm install pouchdb-find

And then attach it to the PouchDB object:

var PouchDB = require('pouchdb');
PouchDB.plugin(require('pouchdb-find'));

API

This API is modeled after the Cloudant query API, merged into CouchDB 2.0. Read that page for more details.

As with PouchDB, the entire API accepts either the callback or the Promise style.

Overview

db.createIndex(index [, callback])

Create an index if it doesn't exist, or do nothing if it already exists.

Example:

db.createIndex({
  index: {
    fields: ['foo']
  }
}).then(function (result) {
  // yo, a result
}).catch(function (err) {
  // ouch, an error
});

The result can be either:

{"result": "created"} // index was created

or:

{"result": "exists"} // index already exists

You can also create an index on multiple fields:

db.createIndex({
  index: {
    fields: ['foo', 'bar', 'baz']
  }
});

Or an index on deep fields:

db.createIndex({
  index: {
    fields: ['person.address.zipcode']
  }
});

You can also specify additional options, if you want more control over how your index is created:

db.createIndex({
  index: {
    fields: ['foo', 'bar'],
    name: 'myindex',
    ddoc: 'mydesigndoc'
    type: 'json',
  }
});

Options

db.getIndexes([callback])

Get a list of all the indexes you've created. Also tells you about the special _all_docs index, i.e. the default index on the _id field.

Example:

db.getIndexes().then(function (result) {
  // yo, a result
}).catch(function (err) {
  // ouch, an error
});

Example result:

{
  "indexes": [
    {
      "ddoc": null,
      "name": "_all_docs",
      "type": "special",
      "def": {
        "fields": [
          {
            "_id": "asc"
          }
        ]
      }
    },
    {
      "ddoc": "_design/idx-0f3a6f73110868266fa5c688caf8acd3",
      "name": "idx-0f3a6f73110868266fa5c688caf8acd3",
      "type": "json",
      "def": {
        "fields": [
          {
            "foo": "asc"
          },
          {
            "bar": "asc"
          }
        ]
      }
    }
  ]
}

db.deleteIndex(index [, callback])

Delete an index and clean up any leftover data on the disk.

Options

Example:

db.deleteIndex({
  "ddoc": "_design/idx-0f3a6f73110868266fa5c688caf8acd3",
  "name": "idx-0f3a6f73110868266fa5c688caf8acd3",
  "type": "json",
  "def": {
    "fields": [
      {
        "foo": "asc"
      },
      {
        "bar": "asc"
      }
    ]
  }
}).then(function (result) {
  // yo, a result
}).catch(function (err) {
  // ouch, an error
});

Notice that you don't need to provide a _rev! The design doc is also deleted.

db.find(request [, callback])

Query the API to find some documents.

Example:

db.find({
  selector: {name: 'Mario'},
  fields: ['_id', 'name'],
  sort: ['name']
}).then(function (result) {
  // yo, a result
}).catch(function (err) {
  // ouch, an error
});

Example result:

{
  "docs": [
    {
      "_id": "mario",
      "name": "Mario"
    }
  ]
}

Options;

If there's no index that matches your selector/sort, then this method will issue a warning.

The best index will be chosen automatically. If you want to see the query plan for your query, then turn on debugging.

See the Cloudant docs for more details.

Examples

Equals

Find all docs where doc.name === 'Mario':

db.find({
  selector: {name: {$eq: 'Mario'}}
});

This is equivalent to:

db.find({
  selector: {name: 'Mario'}
});

Multi-selectors

Find all docs where doc.series === 'Mario' and doc.debut > 1990:

db.find({
  selector: {
    series: 'Mario',
    debut: { $gt: 1990 }
  }
});

This is equivalent to:

db.find({
  selector: {
    $and: [
      { series: 'Mario' },
      { debut: { $gt: 1990 } }
    ]
  }
});

Sorting

Return all docs sorted by doc.debut descending:

db.find({
  selector: {
    debut: {'$exists': true}
  },
  sort: [{debut: 'desc'}]
});

For more examples, refer to Cloudant's _find documentation.

With a remote database

Over HTTP, this plugin currently works with Cloudant and CouchDB 2.0. Cloudant is the reference implementation, so the API should be the same.

PouchDB Server also has this API, since it includes this very plugin by default.

Debugging

Just call:

PouchDB.debug.enable('pouchdb:find')

Then pouchdb-find will start logging some debug information to the console. This can be useful if, for instance, you want to see the query plan that is being used to execute your queries.

Kudos

Thanks very much to @garrensmith for implementing all the new features from 0.4.0 to 0.6.0!

How to contribute to this thing

Instructions are in CONTRIBUTING.md.