全部产品
Search
文档中心

表格存储:创建数据表

更新时间:Oct 16, 2024

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

注意事项

  • 创建数据表后需要几秒钟进行加载,在此期间对该数据表的读写数据操作均会失败。请等待数据表加载完毕后再进行数据操作。

  • 创建数据表时必须指定数据表的主键。主键包含 1~4 个主键列,每一个主键列都包括名称和类型。

  • 如果要使用落盘加密数据,您可以通过在创建数据表时配置数据加密实现。具体操作,请参见创建加密表

  • 如果在系统设计中存在使用主键列自增功能的场景,例如电商网站的商品 ID、大型网站的用户 ID、论坛帖子的 ID、聊天工具的消息 ID 等,您可以通过在创建数据表时配置主键列自增实现。具体操作,请参见主键列自增

前提条件

接口

/**
 * CreateTableRequest包含创建一张新的表所必需的一些参数,包括表的Meta、预留读写吞吐量、表的配置、表的服务端加密配置、是否启用本地事务等。
 */
public class CreateTableRequest implements Request {
    /** 表的结构信息。*/
    private TableMeta tableMeta;
    /** 索引信息。*/
    private List<IndexMeta> indexMeta;
    /** 表的预留吞吐量设置。*/
    private ReservedThroughput reservedThroughput;
    /** 表的配置项, 包括TTL和最大版本数等。*/
    private TableOptions tableOptions;
    /** 表的Stream配置,一般无需配置。*/
    private OptionalValue<StreamSpecification> streamSpecification;
    /** 表的服务器端加密配置。*/
    private OptionalValue<SSESpecification> sseSpecification;
    /** 是否启用局部事务。*/
    private OptionalValue<Boolean> enableLocalTxn;
}

参数

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

参数

是否必选

说明

tableMeta

数据表的结构信息,包括如下内容:

说明

属性列不需要定义。表格存储每行的数据列都可以不同,属性列的列名在写入时指定。

  • tableName(必选):数据表名称。

  • primaryKey(必选):数据表的主键定义。更多信息,请参见核心组件

    • 表格存储可包含 1~4 个主键列。主键列是有顺序的,与用户添加的顺序相同,例如 PRIMARY KEY(A, B, C)与 PRIMARY KEY(A, C, B)是不同的两个主键结构。表格存储会按照主键的大小对行进行排序。

    • 第一列主键作为分区键。分区键相同的数据会存放在同一个分区内,相同分区键下的数据尽量不要超过 10 GB,否则会导致单分区过大,无法分裂。另外,数据的读/写访问最好在不同的分区键上均匀分布,有利于负载均衡。

  • definedColumns(可选):预先定义一些非主键列以及其类型,可以作为索引表的属性列或索引列。

    重要

    如果要在创建数据表时同时配置二级索引,则需要配置此项。

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

tableOptions

数据表的配置信息。更多信息,请参见数据版本和生命周期

配置信息包括如下内容:

  • timeToLive:数据生命周期,即数据的过期时间,单位为秒。当数据的保存时间超过设置的数据生命周期时,系统会自动清理超过数据生命周期的数据。

    数据生命周期的取值最低为 86400 秒(一天),也可设置为 -1(永不过期)。

    创建数据表时,如果希望数据永不过期,可以设置数据生命周期为 -1;创建数据表后,可以通过 UpdateTable 接口动态修改数据生命周期。

    重要

    如果需要使用索引,则数据生命周期必须满足如下条件中的任意一个。

    • 数据表的数据生命周期为 -1(数据永不过期)。

    • 数据表的数据生命周期不为 -1时,数据表为禁止更新状态。

  • maxVersions:最大版本数,即属性列能够保留数据的最大版本个数。当属性列数据的版本个数超过设置的最大版本数时,系统会自动删除较早版本的数据。

    创建数据表时,可以自定义属性列的最大版本数;创建数据表后,可以通过 UpdateTable 接口动态修改数据表的最大版本数。

    重要

    如果需要使用索引,则最大版本数必须设置为 1。

  • maxTimeDeviation:有效版本偏差,即写入数据的时间戳与系统当前时间的偏差允许最大值。只有当写入数据所有列的版本号与写入时时间的差值在数据有效版本偏差范围内,数据才能成功写入。

    属性列的有效版本范围为[max{数据写入时间-有效版本偏差,数据写入时间-数据生命周期},数据写入时间+有效版本偏差)

    创建数据表时,如果未设置有效版本偏差,系统会使用默认值 86400;创建数据表后,可以通过 UpdateTable 接口动态修改有效版本偏差。

    单位为秒。

  • allowUpdate:是否允许 UpdateRow 相关更新写入操作。默认值为 true,表示允许 UpdateRow 相关更新写入操作;当设置 allowUpdate 为 false 时,表示禁止 UpdateRow 相关更新写入操作。

    重要

    如果需要使用多元索引生命周期功能,您必须设置此参数为 false,即不允许通过 UpdateRow 更新写入数据。

如果希望修改表的数据生命周期、最大版本数等配置信息,请通过调用 UpdateTable 接口实现。具体操作,请参见更新表配置

reservedThroughtput

为数据表配置预留读吞吐量或预留写吞吐量,可选配置。

重要

仅高性能型实例中的数据表支持此功能;其他规格实例中的数据表的预留读/写吞吐量只能设置为 0,不允许预留。

默认值为 0,即完全按量计费。

单位为 CU。

  • 当预留读吞吐量或预留写吞吐量大于 0 时,表格存储会根据配置为数据表预留相应资源,且数据表创建成功后,将会立即按照预留吞吐量开始计费,超出预留的部分进行按量计费。更多信息,请参见计费概述

  • 当预留读吞吐量或预留写吞吐量设置为 0 时,表格存储不会为数据表预留相应资源。

sseSpecification

数据表的加密配置。更多信息,请参见创建加密表

enableLocalTxn

是否开启局部事务功能。类型为 Boolean。默认值为 false,表示不开启局部事务。

如果要在创建数据表时开启局部事务,请将此参数设置为 true。

重要
  • 仅 Java SDK 5.11.0 及以上版本支持此功能。

  • 主键自增列功能和局部事务功能不能同时使用。如果创建数据表时配置了主键自增列,则开启局部事务的配置会不生效。

  • 如果创建数据表时未开启局部事务功能,创建数据表后需要使用该功能,请提交工单进行申请。

示例

创建数据表时不带索引

以下示例用于创建数据表。该表的主键为 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);
}

相关文档

  • 如果要读写表中数据,您可以通过调用读写数据接口实现。具体操作,请参见基础数据操作

  • 为数据表开启局部事务后,您可以创建局部事务用于读写局部事务范围内的数据。具体操作,请参见局部事务

  • 如果不再使用数据表,您可以删除数据表。具体操作,请参见删除数据表