A newer version of this documentation is available.

View Latest
February 16, 2025
+ 12
How to create deferred indexes and build them later.

Introduction

When you create a primary or secondary index, you can mark it as deferred. This means the index is not built at once; you can build the deferred index later. This enables you to build multiple indexes more efficiently.

If you want to try out the examples in this section, follow the instructions given in Do a Quick Install to install Couchbase Server, configure a cluster, and load a sample dataset. Read the following for further information about the tools available for editing and executing queries:

Deferring an Index

You can defer an index to be built later using a N1QL statement or an SDK call.

Prior to the SDK API 3.3 releases (released alongside Server 7.1), the SDK calls only enabled you to create indexes in the default collection and default scope within a bucket. A N1QL statement enables you to create indexes in any collection and scope within a bucket.

To defer a primary or secondary index to be built later:

  1. Use the WITH clause to specify the index options.

  2. In the index options, set the defer_build attribute to true.


The following queries create a set of primary and secondary indexes in the landmark keyspace, with build deferred until later.

CREATE INDEX idx_landmark_country
  ON `travel-sample`.inventory.landmark(country)
  USING GSI
  WITH {"defer_build":true};
CREATE INDEX idx_landmark_name 
  ON `travel-sample`.inventory.landmark(name)
  USING GSI
  WITH {"defer_build":true};
CREATE PRIMARY INDEX idx_landmark_primary
  ON `travel-sample`.inventory.landmark
  USING GSI
  WITH {"defer_build":true};

For further details and examples, refer to CREATE PRIMARY INDEX and CREATE INDEX.

Building a Deferred Index

You can build one or more deferred primary or secondary indexes using a N1QL statement. You can also build all deferred indexes in a keyspace using an SDK call.

Prior to the SDK API 3.3 releases (released alongside Server 7.1), the SDK calls only enabled you to build indexes in the default collection and default scope within a bucket. A N1QL statement enables you to build indexes in any collection and scope within a bucket.

To build one or more deferred indexes, use the BUILD INDEX statement:

  1. Use the ON keyword to specify the keyspace which contains the index or indexes.

  2. Specify the index or indexes that you want to build in parentheses ().


The following example builds a single deferred index.

BUILD INDEX ON `travel-sample`.inventory.landmark(idx_landmark_country) USING GSI;

The following example builds multiple deferred indexes.

BUILD INDEX ON `travel-sample`.inventory.hotel(idx_landmark_name, idx_landmark_primary);

For further details and examples, refer to BUILD INDEX.

Reference and explanation:

Administrator guides:

Indexes with SDKs: