Secure 5.1: Couchbase createQueryIndex

Couchbase createQueryIndex

Last updated: July 13, 2026

Creates a secondary (named) N1QL query index on a Couchbase collection. Secondary indexes target specific fields and improve query performance for filtered queries.

Known limitations:

Index names must be unique within a bucket.
When deferred is true, the index is created in a pending state and must be built with a BUILD INDEX statement before it is available for query optimization.

Available attributes

You must specify all top-level attributes marked as required. If you specify an optional attribute, you must also specify any nested attributes that it requires.

Attribute	Type	Description	Required
`bucketName`	String	The name of the bucket containing the collection.	Yes
`collectionName`	String	The name of the collection to index.	Yes
`scopeName`	String	The name of the scope containing the collection.	Yes
`indexName`	String	The name of the index to create. Must be unique within the bucket.	Yes
`fields`	Element	One or more fields to include in the index. See nested tags below.	Yes
`deferred`	Boolean	When `true`, the index is created in a deferred state. Build it with `BUILD INDEX` before use.	Yes
`numReplicas`	Integer	Number of index replicas to create (0 or more).	Yes

Nested tags — fields

Attribute	Type	Description	Required
`field`	String	A document field to include in the index. Specify one `field` element per indexed field. For a compound index, include multiple `field` elements.	Yes (at least one)

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.19.xsd
        http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-couchbase-ext.xsd">

    <changeSet id="1" author="liquibase">
        <ext:createQueryIndex>
            <ext:bucketName>myBucket</ext:bucketName>
            <ext:collectionName>myCollection</ext:collectionName>
            <ext:deferred>false</ext:deferred>
            <ext:fields>
                <ext:field>id</ext:field>
                <ext:field>country</ext:field>
            </ext:fields>
            <ext:indexName>myQueryIndex</ext:indexName>
            <ext:numReplicas>0</ext:numReplicas>
            <ext:scopeName>myScope</ext:scopeName>
        </ext:createQueryIndex>
    </changeSet>

</databaseChangeLog>

{
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "1",
        "author": "liquibase",
        "createQueryIndex": {
          "bucketName": "myBucket",
          "collectionName": "myCollection",
          "deferred": false,
          "fields": [
            "id",
            "country"
          ],
          "indexName": "myQueryIndex",
          "numReplicas": 0,
          "scopeName": "myScope"
        }
      }
    }
  ]
}

databaseChangeLog:
  - changeSet:
      id: '1'
      author: liquibase
      createQueryIndex:
        bucketName: myBucket
        collectionName: myCollection
        deferred: false
        fields:
          - id
          - country
        indexName: myQueryIndex
        numReplicas: 0
        scopeName: myScope

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.19.xsd
        http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-couchbase-ext.xsd">

    <changeSet id="1" author="liquibase">
        <ext:createQueryIndex>
            <ext:bucketName>myBucket</ext:bucketName>
            <ext:collectionName>myCollection</ext:collectionName>
            <ext:deferred>false</ext:deferred>
            <ext:fields>
                <ext:field>id</ext:field>
                <ext:field>country</ext:field>
            </ext:fields>
            <ext:indexName>myQueryIndex</ext:indexName>
            <ext:numReplicas>0</ext:numReplicas>
            <ext:scopeName>myScope</ext:scopeName>
        </ext:createQueryIndex>
    </changeSet>

</databaseChangeLog>

{
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "1",
        "author": "liquibase",
        "createQueryIndex": {
          "bucketName": "myBucket",
          "collectionName": "myCollection",
          "deferred": false,
          "fields": [
            "id",
            "country"
          ],
          "indexName": "myQueryIndex",
          "numReplicas": 0,
          "scopeName": "myScope"
        }
      }
    }
  ]
}

databaseChangeLog:
  - changeSet:
      id: '1'
      author: liquibase
      createQueryIndex:
        bucketName: myBucket
        collectionName: myCollection
        deferred: false
        fields:
          - id
          - country
        indexName: myQueryIndex
        numReplicas: 0
        scopeName: myScope

Couchbase createQueryIndex

Available attributes

Nested tags — fields

XML example

JSON example

YAML example

More like this