全部產品
Search
文件中心

Tablestore:建立資料表

更新時間:May 14, 2025

本文介紹如何通過Java SDK建立Table Store的資料表。

注意事項

建立資料表後,請等待資料表載入完成後再進行資料操作,否則資料操作會失敗,這個過程通常需要幾秒鐘。

前提條件

初始化 Tablestore Client

方法說明

public CreateTableResponse createTable(CreateTableRequest createTableRequest) throws TableStoreException, ClientException

CreateTableRequest參數說明

  • tableMeta(必選)TableMeta:表結構資訊,包含以下參數。

    名稱

    類型

    說明

    tableName(必選)

    String

    資料表名稱。

    primaryKey(必選)

    List<PrimaryKeySchema>

    主鍵資訊。

    • 可以設定1~4個主鍵列,預設按升序進行排序,第一個主鍵列將作為分區鍵。

    • 主鍵資料類型包含STRING、INTEGER和BINARY,非分區鍵中整型的主鍵列可以設定主鍵列自增

    definedColumns(可選)

    List<DefinedColumnSchema>

    預定義列資訊。

    • 預定義列是預先定義的屬性列,可以用於建立二級索引多元索引

    • 預定義列資料類型包含STRING、INTEGER、BINARY、DOUBLE和BOOLEAN。

  • tableOptions(必選)TableOptions:配置資訊,包含以下參數。

    名稱

    類型

    說明

    timeToLive(必選)

    OptionalValue<Integer>

    資料生命週期,單位為秒。

    • 設定為-1時表示資料永不到期,否則取值最低為86400(1天),超出生命週期的資料將會被自動清除。

    • 如果要使用多元索引或二級索引功能,必須將資料生命週期設定為-1,或者將 allowUpdate參數設定為false。

    maxVersions(必選)

    OptionalValue<Integer>

    最大版本數。

    • 如果要使用多元索引或二級索引,最大版本數必須設定為 1。

    maxTimeDeviation(可選)

    OptionalValue<Long>

    有效版本偏差,單位為秒,預設值為86400(1天)。

    • 寫入資料的時間戳記與系統目前時間的差值必須在有效版本偏差範圍內,否則寫入資料將會失敗。

    • 屬性列資料的有效版本範圍為 [max(資料寫入時間-有效版本偏差, 資料寫入時間-資料生命週期), 資料寫入時間+有效版本偏差)

    allowUpdate(可選)

    OptionalValue<Boolean>

    是否允許更新,預設值為true。

    • 設定為false時,無法通過 updateRow() 方法更新資料。

  • indexMeta(可選)List<IndexMeta>:二級索引列表,每個索引包含以下參數。

    名稱

    類型

    說明

    indexName(必選)

    String

    索引名稱。

    primaryKey(必選)

    List<String>

    索引的主鍵列。

    • 可以由資料表的主鍵列和預定義列組成。

    • 使用本地二級索引時,索引第一個主鍵列必須是資料表的第一個主鍵列。

    definedColumns(可選)

    List<String>

    索引的預定義列。

    • 可以由資料表的預定義列組成。

    indexType(可選)

    IndexType

    索引類型,取值範圍:

    • IT_GLOBAL_INDEX(預設值):全域二級索引。

    • IT_LOCAL_INDEX:本地二級索引。

    indexUpdateMode(可選)

    IndexUpdateMode

    索引更新模式,取值範圍:

    • IUM_ASYNC_INDEX(預設值):非同步更新。全域二級索引的更新模式必須設定為非同步更新。

    • IUM_SYNC_INDEX:同步更新。本地二級索引的更新模式必須設定為同步更新。

  • streamSpecification(可選)OptionalValue<StreamSpecification>:Stream配置資訊,包含以下參數。

    名稱

    類型

    說明

    enableStream(必選)

    boolean

    是否開啟Stream,預設值為false。

    expirationTime(可選)

    OptionalValue<Integer>

    Stream到期時間,表示增量日誌到期時間長度。單位為小時,最大值為168(7天)。

    • enableStream設定為true時,必須設定expirationTime。

  • enableLocalTxn(可選)OptionalValue<Boolean>:是否開啟局部事務,預設值為false,表示不開啟局部事務。

    • 僅 Java SDK 5.11.0 及以上版本支援此功能。

    • 局部事務功能和主鍵列自增無法同時使用,如果您配置了主鍵列自增,局部事務功能即使設定開啟也不會生效。

    • 如果建立資料表時未開啟局部事務功能,建立資料表後需要使用該功能,請提交工單進行申請

  • sseSpecification(可選)OptionalValue<SSESpecification>資料加密設定,包含以下參數。

    重要

    資料加密功能只支援在建立資料表時開啟和配置,建立資料表後無法關閉加密功能。

    名稱

    類型

    說明

    enable(必選)

    boolean

    是否開啟資料加密功能,預設值為false。

    keyType(可選)

    OptionalValue<SSEKeyType>

    加密類型。SSEKeyType包含以下類型。

    • SSE_KMS_SERVICE:KMS加密。

    • SSE_BYOK:BYOK加密。

    keyId(可選)

    OptionalValue<String>

    使用者主要金鑰ID。僅當keyType為SSE_BYOK時需設定此參數。

    roleArn(可選)

    OptionalValue<String>

    RAM角色ARN。僅當keyType為SSE_BYOK時需設定此參數。

  • reservedThroughput(可選)ReservedThroughput預留讀寫輸送量,單位為CU,預設值為0,僅CU模式的高效能型執行個體可以設定且有效。

範例程式碼

以下範例程式碼建立了一張test_table表,該表包含1個 String類型的主鍵。

public static void createTableExample(SyncClient client) {
    // 構造資料表的結構資訊
    TableMeta tableMeta = new TableMeta("test_table");
    // 建立資料表至少需要添加一個主鍵
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("id", PrimaryKeyType.STRING));

    // 構造資料表的配置資訊
    TableOptions tableOptions = new TableOptions();
    // 建立資料表時必須指定最大版本數
    tableOptions.setMaxVersions(1);
    // 建立資料表時必須指定資料生命週期,-1表示資料永不到期
    tableOptions.setTimeToLive(-1);

    // 構造Request並發起請求
    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
    client.createTable(request);
}

您也可以在建立資料表的同時參考範例程式碼進行以下設定。

  • 添加預定義列

    tableMeta.addDefinedColumn(new DefinedColumnSchema("name", DefinedColumnType.STRING));
  • 設定有效版本偏差

    tableOptions.setMaxTimeDeviation(86400);
  • 設定是否允許更新

    tableOptions.setAllowUpdate(false);
  • 添加二級索引

    // 構造二級索引列表
    ArrayList<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
    // 構造二級索引
    IndexMeta indexMeta = new IndexMeta("test_table_idx");
    // 設定索引主鍵
    indexMeta.addPrimaryKeyColumn("id");
    indexMeta.addPrimaryKeyColumn("name");
    // 設定索引類型
    indexMeta.setIndexType(IndexType.IT_LOCAL_INDEX);
    // 設定索引更新模式
    indexMeta.setIndexUpdateMode(IndexUpdateMode.IUM_SYNC_INDEX);
    // 添加二級索引
    indexMetas.add(indexMeta);
    
    // 構造Request請求
    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, indexMetas);
  • 設定Stream資訊

    StreamSpecification streamSpecification = new StreamSpecification(true, 168);
    request.setStreamSpecification(streamSpecification);
  • 設定是否開啟局部事務

    request.setLocalTxnEnabled(true);
  • 設定預留讀寫輸送量

    // 設定預留讀輸送量為10000,預留寫輸送量為5000
    ReservedThroughput reservedThroughput = new ReservedThroughput(10000, 5000);
    request.setReservedThroughput(reservedThroughput);
  • 設定資料加密方式

    • KMS祕密金鑰加密

      SSESpecification sseSpecification = new SSESpecification(true, SSEKeyType.SSE_KMS_SERVICE);
      request.setSseSpecification(sseSpecification);
    • BYOK加密

      說明

      運行代碼前需要擷取使用者主要金鑰ID和RAM角色ARN,具體操作請參見BYOK加密

      String keyId = "key-hzz6*****************";
      String roleArn = "acs:ram::1705************:role/tabletorebyok";
      SSESpecification sseSpecification = new SSESpecification(true, SSEKeyType.SSE_BYOK, keyId, roleArn);
      request.setSseSpecification(sseSpecification);

相關文檔