AI 助理
文档备案控制台
官方文档
首页

创建数据表

更新时间：
复制 MD 格式
产品详情
我的收藏

使用 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 及以上版本支持局部事务。

  • 局部事务和主键列自增不能同时使用。如果配置了主键列自增，即使开启局部事务也不会生效。

  • 如果创建数据表时未开启局部事务，后续需要使用该功能，请提交工单或加入钉钉技术交流群36165029092。

服务端加密配置

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);
上一篇：数据表操作下一篇：更新表配置