全部產品
Search

搜尋本產品

    Tablestore：建立資料表

    文件中心

    Tablestore：建立資料表

    更新時間：Aug 05, 2026

    使用 Java SDK 建立寬表模型資料表，並在建立時配置表結構、資料版本、索引、Stream 和加密。

    前提條件

    安裝 Tablestore Java SDK並初始化用戶端。

    功能說明

    調用createTable方法建立寬表模型資料表。請求中至少需要包含一個主鍵列，並指定資料生命週期和最大版本數。

    public CreateTableResponse createTable(CreateTableRequest createTableRequest) throws TableStoreException, ClientException

    以下樣本建立名為example_table的資料表。該表包含一個STRING類型的主鍵列，資料永不到期，最多保留一個版本。

    TableMeta tableMeta = new TableMeta("example_table");
tableMeta.addPrimaryKeyColumn(
        new PrimaryKeySchema("id", PrimaryKeyType.STRING));

TableOptions tableOptions = new TableOptions();
tableOptions.setTimeToLive(-1);
tableOptions.setMaxVersions(1);

CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
client.createTable(request);
    說明

    建立資料表後，請等待資料表載入完成再執行資料操作。

    參數說明

    CreateTableRequest包含以下參數。

    名稱

    類型

    說明

    tableMeta（必選）

    TableMeta

    資料表的表結構。

    tableOptions（必選）

    TableOptions

    資料表的資料版本和更新配置。

    reservedThroughput（可選）

    ReservedThroughput

    預留讀寫輸送量，單位為 CU。預設讀 CU 和寫 CU 均為 0。僅 CU 模式的高效能型執行個體支援設定非零值。

    indexMeta（可選）

    List<IndexMeta>

    與資料表同時建立的二級索引列表。

    streamSpecification（可選）

    StreamSpecification

    Stream 配置。

    enableLocalTxn（可選）

    Boolean

    是否開啟局部事務，預設值為 false。

    sseSpecification（可選）

    SSESpecification

    資料加密配置。資料加密只能在建立資料表時開啟，建立後無法關閉或更改加密配置。

    表結構

    tableMeta 的類型為 TableMeta，包含以下參數。

    名稱

    類型

    說明

    tableName（必選）

    String

    資料表名稱。

    primaryKey（必選）

    List<PrimaryKeySchema>

    主鍵列配置。支援設定 1～4 個主鍵列，第一個主鍵列為分區鍵，資料預設按主鍵升序排列。

    definedColumns（可選）

    List<DefinedColumnSchema>

    預定義列配置，可用於建立二級索引和多元索引。

    主鍵列

    tableMeta.primaryKey[] 中每個元素的類型為 PrimaryKeySchema，包含以下參數。

    名稱

    類型

    說明

    name（必選）

    String

    主鍵列名稱。

    type（必選）

    PrimaryKeyType

    主鍵列類型。取值為 STRING、INTEGER 或 BINARY。

    option（可選）

    PrimaryKeyOption

    主鍵列選項。將非分區鍵的 INTEGER 類型主鍵列設定為 AUTO_INCREMENT 時，該列為主鍵列自增。

    預定義列

    tableMeta.definedColumns[] 中每個元素的類型為 DefinedColumnSchema，包含以下參數。

    名稱

    類型

    說明

    name（必選）

    String

    預定義列名稱。

    type（必選）

    DefinedColumnType

    預定義列類型。取值為 STRING、INTEGER、BINARY、DOUBLE 或 BOOLEAN。

    表配置

    tableOptions 的類型為 TableOptions，包含以下參數。

    名稱

    類型

    說明

    timeToLive（必選）

    Integer

    資料生命週期，單位為秒。設定為 -1 時資料永不到期；設定為其他值時，最小值為 86400（1 天），超出生命週期的資料將被自動清除。使用多元索引或二級索引時，需設定為 -1，或將 allowUpdate 設定為 false。

    maxVersions（必選）

    Integer

    每個屬性列最多保留的版本數。使用多元索引或二級索引時必須設定為 1。

    maxTimeDeviation（可選）

    Long

    有效版本偏差，單位為秒，預設值為 86400（1 天）。寫入資料的時間戳記與系統目前時間的差值必須在有效版本偏差範圍內。屬性列資料的有效版本範圍為 [max(資料寫入時間-有效版本偏差, 資料寫入時間-資料生命週期), 資料寫入時間+有效版本偏差)。

    allowUpdate（可選）

    Boolean

    是否允許通過 updateRow 方法更新資料，預設值為 true。設定為 false 時不允許更新資料。

    updateFullRow（可選）

    Boolean

    是否開啟整行更新，預設值為 false。此參數只能在建立資料表時設定，不能通過 updateTable 方法修改。

    預留讀寫輸送量

    reservedThroughput 的類型為 ReservedThroughput，包含以下參數。

    名稱

    類型

    說明

    capacityUnit（必選）

    CapacityUnit

    預留讀寫輸送量配置。

    容量單元

    reservedThroughput.capacityUnit 的類型為 CapacityUnit，包含以下參數。

    名稱

    類型

    說明

    readCapacityUnit（必選）

    Integer

    預留讀輸送量，單位為 CU。

    writeCapacityUnit（必選）

    Integer

    預留寫輸送量，單位為 CU。

    二級索引

    indexMeta[] 中每個元素的類型為 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（同步更新）。

    Stream 配置

    streamSpecification 的類型為 StreamSpecification，包含以下參數。

    名稱

    類型

    說明

    enableStream（必選）

    Boolean

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

    expirationTime（可選）

    Integer

    增量日誌的保留時間長度，單位為小時，最大值為 168（7 天）。enableStream 設定為 true 時必須設定。

    局部事務配置

    enableLocalTxn 的類型為 Boolean。設定此參數時需注意以下事項。

    • 僅 Java SDK 5.11.0 及以上版本支援局部事務。

    • 局部事務和主鍵列自增不能同時使用。如果配置了主鍵列自增，即使開啟局部事務也不會生效。

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

    服務端加密配置

    sseSpecification 的類型為 SSESpecification，包含以下參數。

    名稱

    類型

    說明

    enable（必選）

    Boolean

    是否開啟資料加密，預設值為 false。

    keyType（可選）

    SSEKeyType

    加密類型。取值為 SSE_KMS_SERVICE（KMS 服務祕密金鑰加密）或 SSE_BYOK（BYOK 加密）。開啟資料加密時必須設定。

    keyId（可選）

    String

    使用者主要金鑰 ID。使用 BYOK 加密時必須設定。

    roleArn（可選）

    String

    RAM 角色 ARN。使用 BYOK 加密時必須設定。

    情境樣本

    配置表結構和資料版本

    以下樣本建立包含兩個主鍵列和一個預定義列的資料表，並設定有效版本偏差和是否允許更新。

    TableMeta tableMeta = new TableMeta("example_table");
tableMeta.addPrimaryKeyColumn(
        new PrimaryKeySchema("id", PrimaryKeyType.STRING));
tableMeta.addPrimaryKeyColumn(
        new PrimaryKeySchema("device_id", PrimaryKeyType.INTEGER));
tableMeta.addDefinedColumn("status", DefinedColumnType.STRING);

TableOptions tableOptions = new TableOptions();
tableOptions.setTimeToLive(-1);
tableOptions.setMaxVersions(1);
tableOptions.setMaxTimeDeviation(86400L);
tableOptions.setAllowUpdate(false);

CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
client.createTable(request);

    建立資料表時添加二級索引

    以下樣本建立資料表時同步建立名為example_table_index的全域二級索引。索引主鍵category必須先聲明為資料表的預定義列。

    TableMeta tableMeta = new TableMeta("example_table");
tableMeta.addPrimaryKeyColumn(
        new PrimaryKeySchema("id", PrimaryKeyType.STRING));
tableMeta.addDefinedColumn("category", DefinedColumnType.STRING);

TableOptions tableOptions = new TableOptions();
tableOptions.setTimeToLive(-1);
tableOptions.setMaxVersions(1);

IndexMeta indexMeta = new IndexMeta("example_table_index");
indexMeta.addPrimaryKeyColumn("category");
indexMeta.setIndexType(IndexType.IT_GLOBAL_INDEX);
indexMeta.setIndexUpdateMode(IndexUpdateMode.IUM_ASYNC_INDEX);

List<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
indexMetas.add(indexMeta);
CreateTableRequest request =
        new CreateTableRequest(tableMeta, tableOptions, indexMetas);
client.createTable(request);

    開啟 Stream

    以下樣本在建立資料表時開啟 Stream，並將增量日誌的到期時間設定為 24 小時。

    TableMeta tableMeta = new TableMeta("example_table");
tableMeta.addPrimaryKeyColumn(
        new PrimaryKeySchema("id", PrimaryKeyType.STRING));

TableOptions tableOptions = new TableOptions();
tableOptions.setTimeToLive(-1);
tableOptions.setMaxVersions(1);

CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
request.setStreamSpecification(new StreamSpecification(true, 24));
client.createTable(request);

    開啟局部事務

    以下樣本在建立資料表時通過setLocalTxnEnabled方法開啟局部事務。

    TableMeta tableMeta = new TableMeta("example_table");
tableMeta.addPrimaryKeyColumn(
        new PrimaryKeySchema("id", PrimaryKeyType.STRING));

TableOptions tableOptions = new TableOptions();
tableOptions.setTimeToLive(-1);
tableOptions.setMaxVersions(1);

CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
request.setLocalTxnEnabled(true);
client.createTable(request);

    加密資料表

    以下樣本分別使用 KMS 服務密鑰和 BYOK 加密資料表。

    重要

    資料加密僅支援在建立資料表時配置。資料表建立完成後，不能關閉加密或更改加密配置。

    KMS 服務祕密金鑰加密

    TableMeta tableMeta = new TableMeta("example_table");
tableMeta.addPrimaryKeyColumn(
        new PrimaryKeySchema("id", PrimaryKeyType.STRING));

TableOptions tableOptions = new TableOptions();
tableOptions.setTimeToLive(-1);
tableOptions.setMaxVersions(1);

CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
request.setSseSpecification(
        new SSESpecification(true, SSEKeyType.SSE_KMS_SERVICE));
client.createTable(request);

    BYOK 加密

    說明

    如需使用 BYOK 加密，請先擷取使用者主要金鑰 ID 和 RAM 角色 ARN。具體操作，請參見BYOK加密。

    TableMeta tableMeta = new TableMeta("example_table");
tableMeta.addPrimaryKeyColumn(
        new PrimaryKeySchema("id", PrimaryKeyType.STRING));

TableOptions tableOptions = new TableOptions();
tableOptions.setTimeToLive(-1);
tableOptions.setMaxVersions(1);

CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
String keyId = "key-xxxx****";
String roleArn = "acs:ram::1234****:role/example-role";
request.setSseSpecification(
        new SSESpecification(true, SSEKeyType.SSE_BYOK, keyId, roleArn));
client.createTable(request);