数据表主要用于数据的存储与查询。创建数据表后,您可以根据实际管理数据表,例如获取实例中的所有表名称、查询数据表的配置信息、更新数据表的配置信息等。

说明 本文均以Java SDK为例介绍不同表操作的代码示例。

接口

表操作包括CreateTable、ListTable、UpdateTable、DescribeTable和DeleteTable接口,详细说明请参见下表。

接口 说明
CreateTable 创建一张数据表或者创建一张带有索引表的数据表。
ListTable 获取当前实例下已创建的所有表的表名。
UpdateTable 更新数据表的配置信息。
DescribeTable 查询数据表的配置信息。
DeleteTable 删除一张数据表。

创建数据表(CreateTable)

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

使用SDK

参数

参数 说明
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(数据永不过期)。
  • maxVersions:最大版本数,即属性列能够保留数据的最大版本个数。当属性列数据的版本个数超过设置的最大版本数时,系统会自动删除较早版本的数据。

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

    说明 如果需要使用索引,则最大版本数必须设置为1。
  • maxTimeDeviation:有效版本偏差,即写入数据的时间戳与系统当前时间的偏差允许最大值。只有当写入数据所有列的版本号与写入时时间的差值在数据有效版本偏差范围内,数据才能成功写入。

    属性列的有效版本范围为[数据写入时间-有效版本偏差,数据写入时间+有效版本偏差)

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

    单位为秒。

reservedThroughtput 为数据表配置预留读吞吐量或预留写吞吐量。

容量型实例中的数据表的预留读/写吞吐量只能设置为0,不允许预留。

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

单位为CU。

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

示例

  • 创建数据表(不带索引)
    private static void createTable(SyncClient client) {
            TableMeta tableMeta = new TableMeta(TABLE_NAME);
            tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema(PRIMARY_KEY_NAME, PrimaryKeyType.STRING)); //为主表添加主键列。
            int timeToLive = -1; //数据的过期时间,单位为秒,-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
            int maxVersions = 3; //保存的最大版本数,1表示每列上最多保存一个版本即保存最新的版本。带索引表的数据表最大版本数必须设置为1。
            TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
            CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
            request.setReservedThroughput(new ReservedThroughput(new CapacityUnit(0, 0))); //设置预留读写吞吐量,容量型实例中的数据表只能设置为0,高性能实例中的数据表可以设置为非零值。
            client.createTable(request);
    }
  • 创建数据表(带索引且索引类型为全局二级索引)
    private static void createTable(SyncClient client) {
        TableMeta tableMeta = new TableMeta(TABLE_NAME);
        tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema(PRIMARY_KEY_NAME_1, PrimaryKeyType.STRING)); //为数据表添加主键列。
        tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema(PRIMARY_KEY_NAME_2, PrimaryKeyType.INTEGER)); //为数据表添加主键列。
        tableMeta.addDefinedColumn(new DefinedColumnSchema(DEFINED_COL_NAME_1, DefinedColumnType.STRING)); //为数据表添加预定义列。
        tableMeta.addDefinedColumn(new DefinedColumnSchema(DEFINED_COL_NAME_2, DefinedColumnType.INTEGER)); //为数据表添加预定义列。
    
        int timeToLive = -1; //数据的过期时间,单位为秒,-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
        int maxVersions = 1; //保存的最大版本数,1表示每列上最多保存一个版本即保存最新的版本。带索引表的数据表最大版本数必须设置为1。
    
        TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
    
        ArrayList<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
        IndexMeta indexMeta = new IndexMeta(INDEX_NAME);
        indexMeta.addPrimaryKeyColumn(DEFINED_COL_NAME_1); //为索引表添加主键列。
        indexMeta.addDefinedColumn(DEFINED_COL_NAME_2); //为索引表添加属性列。
        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);
        tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema(PRIMARY_KEY_NAME_1, PrimaryKeyType.STRING)); //为数据表添加主键列。
        tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema(PRIMARY_KEY_NAME_2, PrimaryKeyType.INTEGER)); //为数据表添加主键列。
        tableMeta.addDefinedColumn(new DefinedColumnSchema(DEFINED_COL_NAME_1, DefinedColumnType.STRING)); //为数据表添加预定义列。
        tableMeta.addDefinedColumn(new DefinedColumnSchema(DEFINED_COL_NAME_2, DefinedColumnType.INTEGER)); //为数据表添加预定义列。
    
        int timeToLive = -1; //数据的过期时间,单位为秒,-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
        int maxVersions = 1; //保存的最大版本数,1表示每列上最多保存一个版本即保存最新的版本。带索引表的数据表最大版本数必须设置为1。
    
        TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
    
        ArrayList<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
        IndexMeta indexMeta = new IndexMeta(INDEX_NAME);
        indexMeta.setIndexType(IT_LOCAL_INDEX);     //设置索引类型为本地二级索引(IT_LOCAL_INDEX)。
        indexMeta.setIndexUpdateMode(IUM_SYNC_INDEX);  //设置索引更新模式为同步更新(IUM_SYNC_INDEX)。当索引类型为本地二级索引时,索引更新模式必须为同步更新。
    
        indexMeta.addPrimaryKeyColumn(PRIMARY_KEY_NAME_1); //为索引表添加主键列。索引表的第一列主键必须与数据表的第一列主键相同。
        indexMeta.addPrimaryKeyColumn(DEFINED_COL_NAME_1); //为索引表添加主键列。
        indexMeta.addDefinedColumn(DEFINED_COL_NAME_2); //为索引表添加属性列。
        indexMetas.add(indexMeta);
    
        CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, indexMetas); //创建数据表的同时创建索引表。
    
        client.createTable(request);
    }

列出表名称(ListTable)

使用ListTable接口获取当前实例下已创建的所有表的表名。

使用SDK

示例

获取实例下所有表的表名。

private static void listTable(SyncClient client) {
    ListTableResponse response = client.listTable();
    System.out.println("表的列表如下:");
    for (String tableName : response.getTableNames()) {
        System.out.println(tableName);
    }
}

更新表信息(UpdateTable)

使用UpdateTable接口修改配置信息(TableOptions)、预留读吞吐量或者预留写吞吐量(ReservedThroughput)。

使用SDK

参数

  • TableOptions

    TableOptions 包含表的 TTL、MaxVersions 和 MaxTimeDeviation 。

    参数 定义 说明
    TTL TimeToLive,数据存活时间
    • 单位:秒。
    • 如果期望数据永不过期,TTL 可设置为 -1。
    • 数据是否过期是根据数据的时间戳当前时间表的 TTL三者进行判断的。当前时间 - 数据的时间戳 > 表的 TTL时,数据会过期并被清理。
    • 在使用 TTL 功能时需要注意写入时是否指定了时间戳,以及指定的时间戳是否合理。如需指定时间戳,建议设置MaxTimeDeviation。
    MaxTimeDeviation 写入数据的时间戳与系统当前时间的偏差允许最大值
    • 默认情况下系统会为新写入的数据生成一个时间戳,数据自动过期功能需要根据这个时间戳判断数据是否过期。用户也可以指定写入数据的时间戳。如果用户写入的时间戳非常小,与当前时间偏差已经超过了表上设置的 TTL 时间,写入的数据会立即过期。设置 MaxTimeDeviation 可以避免这种情况。
    • 单位:秒。
    MaxVersions 每个属性列保留的最大版本数 如果写入的版本数超过 MaxVersions,服务端只会保留 MaxVersions 中指定的最大的版本。
  • ReservedThroughtput

    表的预留读/写吞吐量配置。

    • ReservedThroughput 的调整有时间间隔限制,目前调整间隔为 1 分钟。
    • 设置 ReservedThroughtput 后,表格存储按照您预留读/写吞吐量进行计费。
    • 当 ReservedThroughtput 大于 0 时,表格存储会按照预留量和持续时间进行计费,超出预留的部分进行按量计费。更多信息参见计费,以免产生未期望的费用。
    • 默认值为 0,即完全按量计费。
    • 容量型实例的预留读/写吞吐量只能设置为 0,不允许预留。

示例

更新表的TTL和最大版本数。

private static void updateTable(SyncClient client) {
    int timeToLive = -1;
    int maxVersions = 5; // 将最大版本数更新为5。
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
    UpdateTableRequest request = new UpdateTableRequest(TABLE_NAME);
    request.setTableOptionsForUpdate(tableOptions);
    client.updateTable(request);
}

查询表描述信息(DescribeTable)

使用DescribeTable接口可以查询指定表的结构、预留读/写吞吐量详情等信息。

使用SDK

参数

参数 说明
tableName 表名。

示例

private static void describeTable(SyncClient client) {
    DescribeTableRequest request = new DescribeTableRequest(TABLE_NAME);
    DescribeTableResponse response = client.describeTable(request);
    TableMeta tableMeta = response.getTableMeta();
    System.out.println("表的名称:" + tableMeta.getTableName());
    System.out.println("表的主键:");
    for (PrimaryKeySchema primaryKeySchema : tableMeta.getPrimaryKeyList()) {
        System.out.println(primaryKeySchema);
    }
    TableOptions tableOptions = response.getTableOptions();
    System.out.println("表的TTL:" + tableOptions.getTimeToLive());
    System.out.println("表的MaxVersions:" + tableOptions.getMaxVersions());
    ReservedThroughputDetails reservedThroughputDetails = response.getReservedThroughputDetails();
    System.out.println("表的预留读吞吐量:"
            + reservedThroughputDetails.getCapacityUnit().getReadCapacityUnit());
    System.out.println("表的预留写吞吐量:"
            + reservedThroughputDetails.getCapacityUnit().getWriteCapacityUnit());
}

删除数据表(DeleteTable)

使用DeleteTable接口删除当前实例下指定数据表。

使用SDK

参数

参数 说明
tableName 数据表名称。

示例

private static void deleteTable(SyncClient client) {
    DeleteTableRequest request = new DeleteTableRequest(TABLE_NAME);
    client.deleteTable(request);
}

其他操作方式

您还可以使用控制台或者命令行工具进行表操作。