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