docs/_includes/api/create_index.html

{% include anchor.html edit="true" title="Create index" hash="create_index" %}

{% highlight js %}
db.createIndex(index [, callback])
{% endhighlight %}

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

{% 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="create_idx" type="callback" %}
{% highlight js %}
db.createIndex({
  index: {
    fields: ['foo']
  }
}, function (err, result) {
  if (err) { return console.log(err); }
  // handle result
});
{% endhighlight %}
{% include code/end.html %}

{% include code/start.html id="create_idx" type="async" %}
{% highlight js %}
try {
  var result = await db.createIndex({
    index: {
      fields: ['foo']
    }
  });
} catch (err) {
  console.log(err);
}
{% endhighlight %}
{% include code/end.html %}

{% include code/start.html id="create_idx" type="promise" %}
{% highlight js %}
db.createIndex({
  index: {
    fields: ['foo']
  }
}).then(function (result) {
  // handle result
}).catch(function (err) {
  console.log(err);
});
{% endhighlight %}
{% include code/end.html %}

#### Example Response:

If the index was created, you'll see:

{% highlight js %}
{ "result": "created" }
{% endhighlight %}

Or if the index already exists:

{% highlight js %}
{ "result": "exists" }
{% endhighlight %}

You can also create an index on multiple fields:

{% include code/start.html id="create_idx2" type="callback" %}
{% highlight js %}
db.createIndex({
  index: {
    fields: ['foo', 'bar', 'baz']
  }
}, function (err, result) {
  if (err) { return console.log(err); }
  // handle result
});
{% endhighlight %}
{% include code/end.html %}

{% include code/start.html id="create_idx2" type="async" %}
{% highlight js %}
try {
  var result = await db.createIndex({
    index: {
      fields: ['foo', 'bar', 'baz']
    }
  });
} catch (err) {
  console.log(err);
}
{% endhighlight %}
{% include code/end.html %}

{% include code/start.html id="create_idx2" type="promise" %}
{% highlight js %}
db.createIndex({
  index: {
    fields: ['foo', 'bar', 'baz']
  }
}).then(function (result) {
  // handle result
}).catch(function (err) {
  console.log(err);
});
{% endhighlight %}
{% include code/end.html %}

Or an index on deep fields:

{% include code/start.html id="create_idx3" type="callback" %}
{% highlight js %}
db.createIndex({
  index: {
    fields: ['person.address.zipcode']
  }
}, function (err, result) {
  if (err) { return console.log(err); }
  // handle result
});
{% endhighlight %}
{% include code/end.html %}

{% include code/start.html id="create_idx3" type="async" %}
{% highlight js %}
try {
  var result = await db.createIndex({
    index: {
      fields: ['person.address.zipcode']
    }
  });
} catch (err) {
  console.log(err);
}
{% endhighlight %}
{% include code/end.html %}

{% include code/start.html id="create_idx3" type="promise" %}
{% highlight js %}
db.createIndex({
  index: {
    fields: ['person.address.zipcode']
  }
}).then(function (result) {
  // handle result
}).catch(function (err) {
  console.log(err);
});
{% endhighlight %}
{% include code/end.html %}

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

{% include code/start.html id="create_idx4" type="callback" %}
{% highlight js %}
db.createIndex({
  index: {
    fields: ['foo', 'bar'],
    name: 'myindex',
    ddoc: 'mydesigndoc',
    type: 'json',
  }
}, function (err, result) {
  if (err) { return console.log(err); }
  // handle result
});
{% endhighlight %}
{% include code/end.html %}

{% include code/start.html id="create_idx4" type="async" %}
{% highlight js %}
try {
  var result = await db.createIndex({
    index: {
      fields: ['foo', 'bar'],
      name: 'myindex',
      ddoc: 'mydesigndoc',
      type: 'json',
    }
  });
} catch (err) {
  console.log(err);
}
{% endhighlight %}
{% include code/end.html %}

{% include code/start.html id="create_idx4" type="promise" %}
{% highlight js %}
db.createIndex({
  index: {
    fields: ['foo', 'bar'],
    name: 'myindex',
    ddoc: 'mydesigndoc',
    type: 'json',
  }
}).then(function (result) {
  // handle result
}).catch(function (err) {
  console.log(err);
});
{% endhighlight %}
{% include code/end.html %}

If you want to index a subset of the documents in the database, you can use `partial_filter_selector`. This has the same syntax as the selector you'd pass to `find()`, and only documents matching the selector will be included in the index.

{% include code/start.html id="create_idx5" type="callback" %}
{% highlight js %}
db.createIndex({
  index: {
    fields: ['year', 'title'],
    partial_filter_selector: {
      year: { $gt: 2010 }
    }
  }
}, function (err, result) {
  if (err) { return console.log(err); }
  // handle result
});
{% endhighlight %}
{% include code/end.html %}

{% include code/start.html id="create_idx5" type="async" %}
{% highlight js %}
try {
  var result = db.createIndex({
    index: {
      fields: ['year', 'title'],
      partial_filter_selector: {
        year: { $gt: 2010 }
      }
    }
  });
} catch (err) {
  console.log(err);
}
{% endhighlight %}
{% include code/end.html %}

{% include code/start.html id="create_idx5" type="promise" %}
{% highlight js %}
db.createIndex({
  index: {
    fields: ['year', 'title'],
    partial_filter_selector: {
      year: { $gt: 2010 }
    }
  }
}).then(function (result) {
  // handle result
}).catch(function (err) {
  console.log(err);
});
{% endhighlight %}
{% include code/end.html %}

### Options

* `fields`: 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'`, which is also the default
* `partial_filter_selector` (optional): a _selector_ used to filter the set of documents included in the index

When a PouchDB instance updates an index, it emits `indexing` events that include information about the progress of the index update task.

{% highlight js %}
var db = new PouchDB('my-docs');

db.on('indexing', function (event) {
  // called when indexes are updated
});
{% endhighlight %}

The `event` object contains the following fields:

* `view`: the name of the view that's being updated
* `indexed_docs`: the total number of document updates processed during the current run

When an index is updated this event is emitted once at the start of the update, with `indexed_docs` equal to `0`. It will then emit further events as batches of changes are processed, and those events will also include these fields:

* `last_seq`: the `seq` value of the last event from the database change feed that's been processed
* `results_count`: the number of changes in the most recent batch of changes