Java SDK创建数据表_表格存储-阿里云帮助中心

使用CreateTable接口创建数据表时，需要指定数据表的结构信息和配置信息，高性能实例中的数据表还可以根据需要设置预留读/写吞吐量。创建数据表时支持创建一个或者多个索引表。

注意事项

创建数据表后需要几秒钟进行加载，在此期间对该数据表的读写数据操作均会失败。请等待数据表加载完毕后再进行数据操作。
创建数据表时必须指定数据表的主键。主键包含1个~4个主键列，每一个主键列都包括名称和类型。
如果要使用落盘加密数据，您可以通过在创建数据表时配置数据加密实现。具体操作，请参见创建加密表。
如果要系统设计中存在使用主键列自增功能的场景，例如电商网站的商品ID、大型网站的用户ID、论坛帖子的ID、聊天工具的消息ID等，您可以通过在创建数据表时配置主键列自增实现。具体操作，请参见主键列自增。

前提条件

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

参数

请结合下表参数说明和创建数据表APICreateTable中的消息结构介绍进行代码中的参数配置。

参数	说明
tableMeta	数据表的结构信息，包括如下内容： tableName：数据表名称。 primaryKey：数据表的主键定义。更多信息，请参见主键和属性。说明属性列不需要定义。表格存储每行的数据列都可以不同，属性列的列名在写入时指定。表格存储可包含1个~4个主键列。主键列是有顺序的，与用户添加的顺序相同，例如PRIMARY KEY（A, B, C）与PRIMARY KEY（A, C, B）是不同的两个主键结构。表格存储会按照主键的大小为行排序，具体请参见表格存储数据模型和查询操作。第一列主键作为分区键。分区键相同的数据会存放在同一个分区内，所以相同分区键下的数据尽量不要超过10 GB，否则会导致单分区过大，无法分裂。另外，数据的读/写访问最好在不同的分区键上均匀分布，有利于负载均衡。 definedColumns：预先定义一些非主键列以及其类型，可以作为索引表的属性列或索引列。
tableOptions	数据表的配置信息。更多信息，请参见数据版本和生命周期。配置信息包括如下内容： timeToLive：数据生命周期，即数据的过期时间。当数据的保存时间超过设置的数据生命周期时，系统会自动清理超过数据生命周期的数据。数据生命周期至少为86400秒（一天）或-1（数据永不过期）。创建数据表时，如果希望数据永不过期，可以设置数据生命周期为-1；创建数据表后，可以通过UpdateTable接口动态修改数据生命周期。单位为秒。重要如果需要使用索引，则数据生命周期必须满足如下条件中的任意一个。数据表的数据生命周期为-1（数据永不过期）。数据表的数据生命周期不为-1时，数据表为禁止更新状态。 maxVersions：最大版本数，即属性列能够保留数据的最大版本个数。当属性列数据的版本个数超过设置的最大版本数时，系统会自动删除较早版本的数据。创建数据表时，可以自定义属性列的最大版本数；创建数据表后，可以通过UpdateTable接口动态修改数据表的最大版本数。重要如果需要使用索引，则最大版本数必须设置为1。 maxTimeDeviation：有效版本偏差，即写入数据的时间戳与系统当前时间的偏差允许最大值。只有当写入数据所有列的版本号与写入时时间的差值在数据有效版本偏差范围内，数据才能成功写入。属性列的有效版本范围为`[max{数据写入时间-有效版本偏差,数据写入时间-数据生命周期}，数据写入时间+有效版本偏差)`。创建数据表时，如果未设置有效版本偏差，系统会使用默认值86400；创建数据表后，可以通过UpdateTable接口动态修改有效版本偏差。单位为秒。如果希望修改表的数据生命周期、最大版本数等配置信息，请通过调用UpdateTable接口实现。具体操作，请参见更新表。
reservedThroughtput	为数据表配置预留读吞吐量或预留写吞吐量。容量型实例中的数据表的预留读/写吞吐量只能设置为0，不允许预留。默认值为0，即完全按量计费。单位为CU。当预留读吞吐量或预留写吞吐量大于0时，表格存储会根据配置为数据表预留相应资源，且数据表创建成功后，将会立即按照预留吞吐量开始计费，超出预留的部分进行按量计费。更多信息，请参见计费概述。当预留读吞吐量或预留写吞吐量设置为0时，表格存储不会为数据表预留相应资源。
localTxnEnabled	是否开启局部事务功能。类型为Boolean。默认值为false，表示不开启局部事务。如果要在创建数据表时开启局部事务，请设置此参数为true。重要仅Java SDK 5.11.0及以上版本支持此功能。主键自增列功能和局部事务功能不能同时使用。如果创建数据表时配置了主键自增列，则开启局部事务的配置会不生效。如果创建数据表时未开启局部事务功能，创建数据表后需要使用该功能，请提交工单进行申请或者加入钉钉群23307953（表格存储技术交流群-3）进行咨询。
indexMetas	索引表的结构信息，每个indexMeta都包括如下内容： indexName：索引表名称。 primaryKey：索引表的索引列，索引列为数据表主键和预定义列的组合。使用本地二级索引时，索引表的第一个主键列必须与数据表的第一个主键列相同。 definedColumns：索引表的属性列，索引表属性列为数据表的预定义列的组合。 indexType：索引类型。可选值包括IT_GLOBAL_INDEX和IT_LOCAL_INDEX。当不设置indexType或者设置indexType为IT_GLOBAL_INDEX时，表示使用全局二级索引。使用全局索引时，表格存储以异步方式将数据表中被索引的列和主键列的数据自动同步到索引表中，正常情况下同步延迟达到毫秒级别。当设置indexType为IT_LOCAL_INDEX时，表示使用本地二级索引。使用本地二级索引时，表格存储以同步方式将数据表中被索引的列和主键列的数据自动同步到索引表中，当数据写入数据表后，即可从索引表中查询到数据。 indexUpdateMode：索引更新模式。可选值包括IUM_ASYNC_INDEX和IUM_SYNC_INDEX。当不设置indexUpdateMode或者设置indexUpdateMode为IUM_ASYNC_INDEX时，表示异步更新。使用全局二级索引时，索引更新模式必须设置为异步更新（IUM_ASYNC_INDEX）。当设置indexUpdateMode为IUM_SYNC_INDEX时，表示同步更新。使用本地二级索引时，索引更新模式必须设置为同步更新（IUM_SYNC_INDEX）。

示例

创建数据表时不带索引

以下示例用于创建数据表。该表的主键为pk（String类型），属性列值最多保留3个版本数据以及数据永不过期。

private static void createTable(SyncClient client) {
    //设置数据表名称。
    TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
    //为数据表添加主键列。
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk", PrimaryKeyType.STRING)); 
    //数据的过期时间，单位为秒，-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
    int timeToLive = -1; 
    //保存的最大版本数，1表示每列上最多保存一个版本即保存最新的版本。带索引表的数据表最大版本数必须设置为1。
    int maxVersions = 3; 
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
        
    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
    request.setReservedThroughput(new ReservedThroughput(new CapacityUnit(0, 0))); //设置预留读写吞吐量，容量型实例中的数据表只能设置为0，高性能实例中的数据表可以设置为非零值。
    client.createTable(request);
}

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

以下示例用于同时创建数据表和全局二级索引。该表包含pk1（String类型）和pk2（Integer类型）两列主键且包含defcol1（String类型）和defcol2（Integer类型）两个预定义列，属性列值只保留最新版本数据以及数据永不过期。该全局二级索引的主键列为defcol1、pk1和pk2，属性列为defcol2。

private static void createTable(SyncClient client) {
    //设置数据表名称。
    TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
    //为数据表添加主键列。
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING)); 
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER)); 
    //为数据表添加预定义列。
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol1", DefinedColumnType.STRING)); 
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol2", DefinedColumnType.INTEGER)); 
    //数据的过期时间，单位为秒，-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
    int timeToLive = -1; 
    //保存的最大版本数，1表示每列上最多保存一个版本即保存最新的版本。带索引表的数据表最大版本数必须设置为1。
    int maxVersions = 1; 
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);

    ArrayList<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
    //设置索引表名称。
    IndexMeta indexMeta = new IndexMeta("<INDEX_NAME>");
    //为索引表添加主键列。
    indexMeta.addPrimaryKeyColumn("defcol1"); 
    //为索引表添加属性列。
    indexMeta.addDefinedColumn("defcol2"); 
    indexMetas.add(indexMeta);

    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, indexMetas); //创建数据表的同时创建索引表。

    client.createTable(request);
}

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

以下示例用于同时创建数据表和本地二级索引。该表的主键为pk1（String类型）和pk2（Integer类型）且包括defcol1（String类型）和defcol2（Integer类型）两个预定义列，属性列值只保留最新版本数据以及数据永不过期。该本地二级索引的主键列为pk1、defcol1和pk2，属性列为defcol2。

private static void createTable(SyncClient client) {
    //设置数据表名称。
    TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
    //为数据表添加主键列。
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING)); 
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER)); 
    //为数据表添加预定义列。
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol1", DefinedColumnType.STRING)); 
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol2", DefinedColumnType.INTEGER)); 
    //数据的过期时间，单位为秒，-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
    int timeToLive = -1; 
    //保存的最大版本数，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);  
    //为索引表添加主键列。索引表的第一列主键必须与数据表的第一列主键相同。
    indexMeta.addPrimaryKeyColumn("pk1"); 
    //为索引表添加主键列。
    indexMeta.addPrimaryKeyColumn("defcol1"); 
    //为索引表添加属性列。
    indexMeta.addDefinedColumn("defcol2"); 
    indexMetas.add(indexMeta);

    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, indexMetas); //创建数据表的同时创建索引表。

    client.createTable(request);
}

创建表时开启局部事务

以下示例用于创建数据表时开启局部事务功能。该表的主键为pk1（String类型）和pk2（Integer类型），属性列值只保留最新版本数据以及数据永不过期。

private static void createTable(SyncClient client) {
    //设置数据表名称。
    TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
    //为数据表添加主键列。
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING));
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER));
    //数据的过期时间，单位为秒，-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
    int timeToLive = -1; 
    //保存的最大版本数，1表示每列上最多保存一个版本即保存最新的版本。带索引表的数据表最大版本数必须设置为1。
    int maxVersions = 1; 
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);

    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
    //开启局部事务。当为数据表配置了主键自增列时，此配置无效。
    request.setLocalTxnEnabled(true); 

    client.createTable(request);
}