npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

pouchdb-find

v9.0.0

Published

Easy-to-use query language for PouchDB

Downloads

157,334

Readme

PouchDB Find

(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.

Warning: this is beta software! It may change at anytime and could be unstable.

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, partial indexes.

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

  • fields is a list of fields to index
  • name (optional) name of the index, auto-generated if you don't include it
  • ddoc (optional) design document name (i.e. the part after '_design/', auto-generated if you don't include it
  • type (optional) only supports 'json', and it's also the default

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

  • index Definition of an index to delete. You can pass it in exactly as you received it from the getIndexes() API. You cannot delete the built-in _all_docs index.

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;

  • 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.

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.