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

### 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