使用 Java SDK 创建数据表_表格存储(Tablestore)-阿里云帮助中心

本文将通过参数说明和示例代码为您介绍如何使用 Java SDK 创建数据表。在创建数据表时，您需要指定数据表的结构信息和配置信息。CU 模式（原按量模式）下高性能型实例中的数据表还可以根据需要设置预留读写吞吐量。

注意事项

创建数据表后需要几秒钟进行加载，在此期间对该数据表的读写数据操作均会失败。请等待数据表加载完毕后再进行数据操作。
表格存储提供数据加密存储功能，如果您有高安全性或合规性要求，可以在创建数据表时配置加密相关参数。具体操作，请参见创建加密表。
如果您有主键数据自增的需求，例如电商网站的商品 ID、论坛帖子的 ID 等场景，可以在创建数据时配置主键列自增。具体操作，请参见主键列自增。

前提条件

已通过控制台创建实例。具体操作，请参见创建实例。
已初始化 OTSClient。具体操作，请参见初始化 OTSClient。

接口

/**
 * 说明：根据指定表结构信息创建数据表。
 * 当创建一个数据表后，通常需要等待几秒钟时间使partition load完成，才能进行各种操作。
 * 返回：CreateTableResponse。
 */
CreateTableResponse createTable(CreateTableRequest createTableRequest) throws TableStoreException, ClientException

参数说明

createTableRequest包含以下参数：

参数	说明
tableMeta（必选）	数据表的结构信息，包括如下内容： tableName（必选）：数据表名称。 primaryKey（必选）：数据表的主键定义。更多信息，请参见核心组件。主键数据类型可以为 STRING、INTEGER 或 BINARY。可以设置 1~4 个主键列。表格存储将按照设置的顺序生成主键，默认按升序进行排序。第一个主键列将作为分区键。 definedColumns（可选）：预定义列信息。数据类型可以为 STRING、INTEGER、BINARY、DOUBLE 或 BOOLEAN。说明预定义列是预先定义的一些非主键列，通常被用作二级索引的主键列或预定义列，以实现快速查询数据的需求。属性列在创建表时无需定义，您可以在写入数据时为每行数据指定不同的属性列和列名。
tableOptions（必选）	数据表的配置信息，包括如下内容： timeToLive（必选）：数据生命周期，即数据的过期时间，单位为秒。数据生命周期的取值最低为 86400 秒（一天），也可设置为 -1（永不过期）。重要如果要使用多元索引或二级索引，必须将数据生命周期设置为 -1，或者将 allowUpdate 参数设置为 false。 maxVersions（必选）：最大版本数，即属性列能够保留数据的最大版本个数。重要如果要使用多元索引或二级索引，最大版本数必须设置为 1。 maxTimeDeviation（可选）：有效版本偏差，即写入数据的时间戳与系统当前时间的偏差允许最大值，单位为秒。默认值 86400 秒（一天）。属性列的有效取值范围是一个左闭右开的区间：`[max{数据写入时间-有效版本偏差,数据写入时间-数据生命周期}，数据写入时间+有效版本偏差)`。 allowUpdate（可选）：是否允许更新。默认为true。重要如果要使用多元索引的生命周期功能，必须设置此参数为 false。如果您需要更新数据，可使用 PutRow 接口写入数据。
indexMeta（可选）	索引列表。每个索引包含以下内容： indexName（必选）：索引名称。 primaryKey（必选）：索引的主键列。可以由数据表的主键列和预定义列组成。重要使用本地二级索引时，索引第一个主键列必须是数据表的第一个主键列。 definedColumns（可选）：索引的预定义列。可以由数据表的预定义列组成。 indexType（可选）：索引类型。取值范围如下： IT_GLOBAL_INDEX （默认值）：全局二级索引。 IT_LOCAL_INDEX：本地二级索引。 indexUpdateMode（可选）：索引更新模式。取值范围如下： IUM_ASYNC_INDEX（默认值）：异步更新。说明使用全局二级索引时，索引更新模式必须设置为异步更新。 IUM_SYNC_INDEX：同步更新。说明使用本地二级索引时，索引更新模式必须设置为同步更新。
reservedThroughtput（可选）	预留读写吞吐量，单位为 CU。默认值为 0。重要仅 CU 模式下高性能型实例支持设置数据表的预留读写吞吐量为非零值。
streamSpecification（可选）	数据表的 Stream 配置信息，包括如下内容： enableStream（可选）：是否开启 stream。默认值为 false，即不开启 stream。 expirationTime（可选）：stream 过期时间，表示增量日志过期时长。单位为小时，最大值为 168 小时（7 天）。说明开启 stream 时，必须设置 expirationTime 参数。
sseSpecification（可选）	数据表的加密配置。重要数据表创建后，不支持修改加密相关配置。
enableLocalTxn（可选）	是否开启局部事务功能。默认值为 false，表示不开启局部事务功能。重要仅 Java SDK 5.11.0 及以上版本支持此功能。主键列自增和局部事务功能无法同时使用，如果您配置了主键列自增，即使开启局部事务也不会生效。如果创建数据表时未开启局部事务功能，创建数据表后需要使用该功能，请提交工单进行申请或者加入钉钉群 23307953（表格存储技术交流群-3）进行咨询。

示例

创建数据表

以下示例用于创建数据表。

private static void createTable(SyncClient client) {
    //设置数据表名称。
    TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
    //为数据表添加主键列。主键为pk1（String类型）和pk2（Integer类型），其中pk1主键列为分区键，pk2主键列为自增列。
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING));
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER, PrimaryKeyOption.AUTO_INCREMENT));
    //数据的过期时间，-1表示永不过期。
    int timeToLive = -1;
    //最大版本数，属性列值最多保留1个版本，即保存最新的版本。
    int maxVersions = 1;
    //有效版本偏差，即写入数据的时间戳与系统当前时间的偏差允许最大值为86400秒（1天）。
    long maxTimeDeviation = 86400L;
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions, maxTimeDeviation);
    //设置预留读写吞吐量，容量型实例下的数据表只能设置为0，高性能型实例下的数据表可以设置为非零值。
    ReservedThroughput reservedThroughput = new ReservedThroughput(new CapacityUnit(0, 0));
    
    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, reservedThroughput);
    client.createTable(request);
}

创建数据表时配置二级索引

创建数据表时配置全局二级索引

以下示例用于同时创建数据表和全局二级索引。

private static void createTable(SyncClient client) {
    //设置数据表名称。
    TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
    //为数据表添加主键列。主键为pk1（String类型）和pk2（Integer类型）。
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING));
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER));
    //为数据表添加预定义列。预定义列为defcol1（String类型）和defcol2（Integer类型）。
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol1", DefinedColumnType.STRING));
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol2", DefinedColumnType.INTEGER));
    //数据永不过期，-1表示永不过期。
    int timeToLive = -1;
    //最大版本数，属性列值最多保留1个版本，即保存最新的版本。
    int maxVersions = 1;
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
    
    //全局二级索引
    ArrayList<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
    //设置索引名称。
    IndexMeta indexMeta = new IndexMeta("<INDEX_NAME>");
    //为索引添加主键列。主键列为defcol1、pk1和pk2
    indexMeta.addPrimaryKeyColumn("defcol1");
    indexMeta.addPrimaryKeyColumn("pk1");
    indexMeta.addPrimaryKeyColumn("pk2");
    //为索引添加预定义列。预定义列为defcol2。
    indexMeta.addDefinedColumn("defcol2");
    indexMetas.add(indexMeta);
    
    //创建数据表的同时创建索引。
    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, indexMetas);
    client.createTable(request);
}

创建数据表时配置本地二级索引

以下示例用于同时创建数据表和本地二级索引。

private static void createTable(SyncClient client) {
    //设置数据表名称。
    TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
    //为数据表添加主键列。主键为pk1（String类型）和pk2（Integer类型）。
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING));
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER));
    //为数据表添加预定义列。预定义列为defcol1（String类型）和defcol2（Integer类型）。
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol1", DefinedColumnType.STRING));
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol2", DefinedColumnType.INTEGER));
    //数据的过期时间，-1表示永不过期。1。
    int timeToLive = -1;
    //最大版本数，属性列值最多保留1个版本，即保存最新的版本。
    int maxVersions = 1;
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
    
    //本地二级索引
    ArrayList<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
    //设置索引名称。
    IndexMeta indexMeta = new IndexMeta("<INDEX_NAME>");
    //设置索引类型为本地二级索引（IT_LOCAL_INDEX）。
    indexMeta.setIndexType(IT_LOCAL_INDEX);
    //设置索引更新模式为同步更新（IUM_SYNC_INDEX）。当索引类型为本地二级索引时，索引更新模式必须为同步更新。
    indexMeta.setIndexUpdateMode(IUM_SYNC_INDEX);
    //为索引添加主键列。主键列为pk1、defcol1和pk2。
    indexMeta.addPrimaryKeyColumn("pk1");
    indexMeta.addPrimaryKeyColumn("defcol1");
    indexMeta.addPrimaryKeyColumn("pk2");
    //为索引添加预定义列。预定义列为defcol2。
    indexMeta.addDefinedColumn("defcol2");
    indexMetas.add(indexMeta);
    
    //创建数据表的同时创建索引。
    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, indexMetas); 
    client.createTable(request);
}

创建数据表时开启局部事务

以下示例用于创建数据表时开启局部事务功能。

private static void createTable(SyncClient client) {
    //设置数据表名称。
    TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
    //为数据表添加主键列。主键为pk1（String类型）和pk2（Integer类型）。
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING));
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER));
    //数据的过期时间，-1表示永不过期。
    int timeToLive = -1;
    //最大版本数，属性列值最多保留1个版本，即保存最新的版本。
    int maxVersions = 1;
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
    
    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
    //开启局部事务。如果数据表配置了主键自增列，则开启局部事务配置不会生效。
    request.setLocalTxnEnabled(true);
    client.createTable(request);
}