创建数据表

前提条件

安装 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：数据表的表结构，包含以下参数。

  名称	类型	说明
  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>	是否允许通过updateRow方法更新数据，默认值为true。 设置为false时，不允许更新数据。

• 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>	增量日志的保留时长。单位为小时，最大值为 168（7 天）。 enableStream设置为true时，必须设置expirationTime。

• enableLocalTxn（可选）OptionalValue<Boolean>：是否开启局部事务，默认值为false。

  • 仅 Java SDK 5.11.0 及以上版本支持局部事务。

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

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

• sseSpecification（可选）OptionalValue<SSESpecification>：数据加密配置，仅支持在创建数据表时设置。包含以下参数。

  名称	类型	说明
  enable（必选）	boolean	是否开启数据加密功能，默认值为false。
  keyType（可选）	OptionalValue<SSEKeyType>	加密类型，取值如下： SSE_KMS_SERVICE：KMS 加密。 SSE_BYOK：BYOK 加密。
  keyId（可选）	OptionalValue<String>	用户主密钥（CMK）ID。将keyType设置为SSE_BYOK时，必须设置此参数。
  roleArn（可选）	OptionalValue<String>	RAM 角色 ARN。将keyType设置为SSE_BYOK时，必须设置此参数。

• reservedThroughput（可选）ReservedThroughput：预留读写吞吐量。单位为 CU，默认值为 0。仅 CU 模式的高性能型实例可以设置此参数。

场景示例

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);

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);

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);

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);

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);

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);