Create a secondary index - Tablestore SDK for Java - Tablestore

Prerequisites

Install the Tablestore SDK for Java and initialize a client.
The maxVersions value of the data table is 1, and the timeToLive value is -1 or data cannot be updated by calling UpdateRow.
If you want to use non-primary key columns as index columns or attribute columns, configure the columns as predefined columns.

Description

A secondary index uses a different primary key schema composed of primary key columns and predefined columns from a data table to provide additional query dimensions. Secondary indexes are classified into global secondary indexes and local secondary indexes. The two index types have different data synchronization modes and primary key requirements. For more information, see Overview.

Call createIndex to create a secondary index for an existing data table. To create one or more secondary indexes together with a data table, configure the index schemas in the createTable request. For more information, see Create a data table.

public CreateIndexResponse createIndex(CreateIndexRequest createIndexRequest)
        throws TableStoreException, ClientException

The following sample code creates the global secondary index example_global_index for example_table. The index includes existing data.

IndexMeta indexMeta = new IndexMeta("example_global_index");
indexMeta.addPrimaryKeyColumn("category");
indexMeta.addDefinedColumn("status");

CreateIndexRequest request =
        new CreateIndexRequest("example_table", indexMeta, true);
client.createIndex(request);

Parameters

CreateIndexRequest contains the following parameters:

Name	Type	Description
mainTableName (required)	`String`	The name of the data table.
indexMeta (required)	`IndexMeta`	The schema information about the index table.
includeBaseData (required)	`boolean`	Specifies whether the index table includes existing data of the data table. If you set this parameter to `true`, existing data is synchronized, and the synchronization duration varies based on the amount of data. If you set this parameter to `false`, only data that is written after the index is created is synchronized.

Index schema

indexMeta is of the IndexMeta type and contains the following parameters:

Name	Type	Description
indexName (required)	`String`	The name of the index table. The name must be different from the name of an existing data table or time series table.
primaryKey (required)	`List<String>`	An ordered list of index column names. Specify one to four columns, which can be primary key columns or predefined columns of the data table. Tablestore uses the order in which columns are added and automatically appends unspecified primary key columns of the data table to the end of the index primary key. For a local secondary index, the first index primary key column must be the same as the first primary key column of the data table.
definedColumns (optional)	`List<String>`	A list of attribute column names of the index table. Only predefined columns of the data table can be specified.
indexType (optional)	`IndexType`	The index type. Valid values are `IT_GLOBAL_INDEX` and `IT_LOCAL_INDEX`. Default value: `IT_GLOBAL_INDEX`.
indexUpdateMode (optional)	`IndexUpdateMode`	The index update mode. A global secondary index must use `IUM_ASYNC_INDEX`. Tablestore asynchronously synchronizes data in the index columns and primary key columns, and the synchronization latency is typically at the millisecond level. A local secondary index must use `IUM_SYNC_INDEX`. Tablestore synchronously updates the index, and you can query data from the index table after the data is written to the data table. Default value: `IUM_ASYNC_INDEX`.

Scenario examples

Create a local secondary index

To create a local secondary index, specify the first primary key column of the data table as the first index primary key column, and set the index type and update mode to IT_LOCAL_INDEX and IUM_SYNC_INDEX, respectively.

IndexMeta indexMeta = new IndexMeta("example_local_index");
indexMeta.addPrimaryKeyColumn("user_id");
indexMeta.addPrimaryKeyColumn("category");
indexMeta.addDefinedColumn("status");
indexMeta.setIndexType(IndexType.IT_LOCAL_INDEX);
indexMeta.setIndexUpdateMode(IndexUpdateMode.IUM_SYNC_INDEX);

CreateIndexRequest request =
        new CreateIndexRequest("example_table", indexMeta, true);
client.createIndex(request);