Dynamically modify a search index schema - Tablestore SDK for Java - Tablestore

Prerequisites

You have installed the Tablestore SDK for Java and initialized the client.

Description

Call createSearchIndex to create a canary index that contains the complete new schema from a source index. The process does not interrupt table reads or writes, and query code that uses the source index name does not need to change. The process consists of the following steps:

public CreateSearchIndexResponse createSearchIndex(CreateSearchIndexRequest request)

Create a canary index from the source index and submit the complete new schema.
Wait until the existing and incremental data is synchronized and the canary index catches up with the source index.
Optionally distribute query traffic between the source and canary indexes for A/B testing.
After query results are verified, swap the indexes so that the source index name points to the new schema.
Observe the index for a stabilization period after the swap. Then, delete the canary index that points to the old schema.

Important

A canary index is a temporary index used during the schema modification process, and its name must end with _reindex. Index mappings and traffic weights change during the process. Do not query data by using the canary index name.
You can rebuild up to five indexes at the same time. Before you start another batch, wait until the canary indexes in the current batch catch up with their source indexes or complete the index swaps.

Create a canary index

The following example changes col1 from Long to Keyword, removes col2, adds the Long field col3, and configures id as a routing field.

String tableName = "example_table";
String sourceIndexName = "example_index";
String reindexName = "example_index_reindex";
IndexSchema indexSchema = new IndexSchema();
indexSchema.setFieldSchemas(Arrays.asList(
        new FieldSchema("id", FieldType.KEYWORD),
        new FieldSchema("col1", FieldType.KEYWORD),
        new FieldSchema("col3", FieldType.LONG)));

IndexSetting indexSetting = new IndexSetting();
indexSetting.setRoutingFields(Arrays.asList("id"));
indexSchema.setIndexSetting(indexSetting);

CreateSearchIndexRequest request = new CreateSearchIndexRequest();
request.setTableName(tableName);
request.setIndexName(reindexName);
request.setSourceIndexName(sourceIndexName);
request.setIndexSchema(indexSchema);
client.createSearchIndex(request);

After the request succeeds, query the canary index information. Verify that its status is RUNNING, brotherIndexName contains the source index name, and the new schema is correct. The RUNNING state indicates that the canary index was created. It does not indicate that the canary index has caught up with the source index.

Validate and switch the indexes

Important

Perform A/B testing and swap the indexes only after the console indicates that the canary index is safe to switch. After the swap, the source index name points to the new schema and the canary index name points to the old schema. Verify the index and observe it for a stabilization period before you delete the canary index.

Use the Tablestore console to check synchronization progress, configure traffic weights, swap the indexes, and delete the canary index. For instructions, see Dynamically modify a search index schema.

Parameters

CreateSearchIndexRequest contains the following parameters:

Name	Type	Description
tableName (required)	`String`	The table name.
indexName (required)	`String`	The canary index name. The name must end with `_reindex`.
indexSchema (required)	`IndexSchema`	The complete new schema of the canary index.
sourceIndexName (required)	`String`	The source index on which the rebuild is based. Tablestore creates the canary index from this index and synchronizes existing and incremental table data to the canary index.
timeToLive (optional)	`Integer`	The canary index data TTL in seconds. To specify the TTL in days, call `setTimeToLiveInDays`. For valid values and constraints, see Configure the TTL of a search index.

Index schema

indexSchema is of the IndexSchema type and contains the following parameters.

Name	Type	Description
fieldSchemas (required)	`List<FieldSchema>`	The complete field list after the change. Add, remove, or modify fields in this list to change the index fields.
indexSetting (optional)	`IndexSetting`	The index settings. Use `routingFields` to change routing fields.
indexSort (optional)	`Sort`	The index presorting settings.

For the complete parameter structures and constraints of index fields, index settings, and presorting settings, see Create a search index.