BUILD INDEX
The BUILD INDEX statement enables you to build one or more GSI indexes that are marked for deferred building all at once.
By default, CREATE INDEX statement starts building the created index.
However for more efficient building of multiple indexes, CREATE INDEX command can mark indexes for deferred building using the defer_build:true
option.
BUILD INDEX is capable of building multiple indexes at once, and can utilize a single scan of documents in the bucket to feed many index build operations.
BUILD INDEX is an asynchronous operation.
BUILD INDEX creates a task to build the primary or secondary GSI indexes and returns as soon as the task is queued for execution.
The full index creation operation happen in the background.
Indexes of type GSI provide a status field and mark index status pending while the index build operation is in progress.
This status field and other index metadata can be queried using system:indexes
.
When building an index which has automatic index replicas, all of the replicas are also built as part of the BUILD INDEX statement, without having to manually specify them.
RBAC Privileges
User executing the BUILD INDEX statement must have the Query Manage Index privilege granted on the keyspace/bucket. For more details about user roles, see Authorization.
Known Issue
If multiple index building operations are kicked off without waiting for all indexes to get to the online state, index building for some indexes might fail.
In this case,
To work around this issue, wait for index building to complete (that is, for all indexes to get to the online state), then issue the BUILD INDEX command again. |
Syntax
build-index ::= BUILD INDEX ON keyspace-ref '(' index-name [ ',' index-name ]* ')' [ index-using ]

Keyspace Reference
keyspace-ref ::= [ namespace ':' ] keyspace

- namespace
-
(Optional) An identifier that refers to the namespace of the bucket to be indexed. Currently, only the
default
namespace is available. If the namespace name is omitted, the default namespace in the current session is used. - keyspace
-
(Required) An identifier that refers to the bucket name or keyspace. It specifies the bucket as the source for which the index needs to be created.
For example, default:`travel-sample`
indicates the travel-sample
keyspace in the default
namespace.
Index Name
An identifier that refers to the name of an index.
You can specify one index name, or multiple index names separated by commas. An index name must be specified for each index to be built.
Examples
Create a set of primary and secondary indexes on the travel-sample
bucket with the defer_build
option.
CREATE INDEX `travel-sample-type-index` ON `travel-sample`(type) USING GSI
WITH {"defer_build":true};
CREATE INDEX `travel-sample-name-index` ON `travel-sample`(name) USING GSI
WITH {"defer_build":true};
CREATE PRIMARY INDEX `travel-sample-primary-index` ON `travel-sample` USING GSI
WITH {"defer_build":true};
Query system:indexes
for the status of an index.
SELECT * FROM system:indexes WHERE name="travel-sample-type-index";
[
{
"indexes": {
"datastore_id": "http://127.0.0.1:8091",
"id": "91e28fbb76aa93f6",
"index_key": [
"`type`"
],
"keyspace_id": "travel-sample",
"name": "travel-sample-type-index",
"namespace_id": "default",
"state": "deferred", (1)
"using": "gsi"
}
}
]
1 | The travel-sample-type-index is in the pending state (deferred). |
Kick off a deferred build using the index name.
BUILD INDEX ON `travel-sample`(`travel-sample-type-index`) USING GSI;
List all deferred builds in the keyspace.
SELECT RAW name (1)
FROM system:indexes
WHERE keyspace_id = 'travel-sample'
AND state = 'deferred';
[
"travel-sample-name-index",
"travel-sample-primary-index"
]
1 | The RAW keyword forces the subquery to return a flattened array of strings, each of which refers to an index name. |
Kick off multiple deferred builds in the keyspace.
BUILD INDEX ON `travel-sample`(`travel-sample-name-index`, `travel-sample-primary-index`);
Query system:indexes
for the status of an index.
SELECT * FROM system:indexes WHERE name="travel-sample-type-index";
[
{
"indexes": {
"datastore_id": "http://127.0.0.1:8091",
"id": "91e28fbb76aa93f6",
"index_key": [
"`type`"
],
"keyspace_id": "travel-sample",
"name": "travel-sample-type-index",
"namespace_id": "default",
"state": "online", (1)
"using": "gsi"
}
}
]
1 | The index has now been created. |