表格存储Java SDK动态修改Schema-表格存储 Tablestore(Tablestore)-阿里云帮助中心

修改多元索引的 schema 时，需通过重建索引完成变更。使用 Tablestore Java SDK创建灰度索引后，可在表格存储控制台完成后续切换操作，全程不中断线上业务。

工作原理

修改 schema 时，系统在原索引基础上创建灰度索引，并将全量历史数据重建到灰度索引中。重建过程中：

系统将原索引中的全量数据按新 schema 同步到灰度索引。
新写入数据同时同步到原索引和灰度索引，确保数据一致性。
在控制台完成索引切换后，灰度索引成为主索引，原索引随即删除。

切换前，可通过 A/B 测试验证新 schema 的效果，确认无误后再完成切换。

使用限制

单次最多并发重建 5 个索引。等待全部索引重建完成（即控制台中灰度索引与原索引数据量接近，或完成切换流程）后，再启动下一批重建。
灰度索引名称必须以 _reindex 结尾。

操作步骤

步骤一：通过SDK创建灰度索引

基于原索引创建灰度索引，通过 setSourceIndexName 关联源索引，并在新 schema 中定义变更后的字段（支持新增、修改或删除字段）。

// 本示例展示如何创建灰度索引（重建索引）来动态修改多元索引的 Schema
// 使用前请配置环境变量 TABLESTORE_ACCESS_KEY_ID 和 TABLESTORE_ACCESS_KEY_SECRET

import com.alicloud.openservices.tablestore.SyncClient;
import com.alicloud.openservices.tablestore.core.ResourceManager;
import com.alicloud.openservices.tablestore.core.auth.CredentialsProvider;
import com.alicloud.openservices.tablestore.core.auth.DefaultCredentialProvider;
import com.alicloud.openservices.tablestore.core.auth.DefaultCredentials;
import com.alicloud.openservices.tablestore.core.auth.V4Credentials;
import com.alicloud.openservices.tablestore.model.search.CreateSearchIndexRequest;
import com.alicloud.openservices.tablestore.model.search.CreateSearchIndexResponse;
import com.alicloud.openservices.tablestore.model.search.FieldSchema;
import com.alicloud.openservices.tablestore.model.search.FieldType;
import com.alicloud.openservices.tablestore.model.search.IndexSchema;
import com.alicloud.openservices.tablestore.model.search.IndexSetting;

import java.util.Arrays;

public class CreateReindex {

    public static void main(String[] args) {
        String accessKeyId = System.getenv("TABLESTORE_ACCESS_KEY_ID");
        String accessKeySecret = System.getenv("TABLESTORE_ACCESS_KEY_SECRET");

        // 实例配置
        String region = "<region-id>";
        String instanceName = "example-instance";
        String endpoint = "https://example-instance.<region-id>.ots.aliyuncs.com";

        // 表名和索引名
        String tableName = "example_table";
        String sourceIndexName = "example_index";
        // 灰度索引名必须以 _reindex 结尾
        String reindexName = sourceIndexName + "_reindex";

        SyncClient client = null;
        try {
            DefaultCredentials credentials = new DefaultCredentials(accessKeyId, accessKeySecret);
            V4Credentials credentialsV4 = V4Credentials.createByServiceCredentials(credentials, region);
            CredentialsProvider provider = new DefaultCredentialProvider(credentialsV4);
            client = new SyncClient(endpoint, provider, instanceName, null, new ResourceManager(null, null));

            // 创建灰度索引请求
            CreateSearchIndexRequest request = new CreateSearchIndexRequest();
            request.setTableName(tableName);
            request.setIndexName(reindexName);
            // 指定源索引，表示这是基于源索引创建的灰度索引
            request.setSourceIndexName(sourceIndexName);

            // 定义新的索引 Schema（可以新增、修改或删除字段）
            IndexSchema indexSchema = new IndexSchema();
            indexSchema.setFieldSchemas(Arrays.asList(
                    new FieldSchema("pk", FieldType.KEYWORD).setIndex(true).setEnableSortAndAgg(true),
                    new FieldSchema("col1", FieldType.LONG).setIndex(true).setEnableSortAndAgg(true),
                    // 新增 col3 字段（原索引只有 pk, col1, col2）
                    new FieldSchema("col3", FieldType.LONG).setIndex(true).setEnableSortAndAgg(true)
            ));

            // 设置路由字段（用于优化查询性能）
            IndexSetting indexSetting = new IndexSetting();
            indexSetting.setRoutingFields(Arrays.asList("pk"));
            indexSchema.setIndexSetting(indexSetting);

            request.setIndexSchema(indexSchema);

            // 创建灰度索引
            CreateSearchIndexResponse response = client.createSearchIndex(request);
            System.out.println("灰度索引创建成功: " + reindexName);
            System.out.println("RequestId: " + response.getRequestId());
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            if (client != null) {
                client.shutdown();
            }
        }
    }
}

步骤二：在控制台完成后续操作

灰度索引重建完成后，在表格存储控制台中执行后续操作，包括查看索引同步进度、设置权重进行 A/B 测试、交换索引 Schema 以及删除灰度索引。具体操作，请参见动态修改schema。