创建表时需要指定表的结构信息(TableMeta)和配置信息(TableOptions),也可以根据需求设置表的预留读/写吞吐量(ReservedThroughput)。

说明 表格创建好后服务端需要将表的分片加载到某个节点上,需要等待几秒钟才能对表进行读写,否则会出现异常。

参数说明

  • TableMeta

    TableMeta 包含 TableName 和 List。

    参数 定义 说明
    TableName 表名
    List 表的主键定义
    • 表格存储可包含多个主键列。主键列是有顺序的,与用户添加的顺序相同,例如, PRIMARY KEY (A, B, C) 与 PRIMARY KEY (A, C, B) 是不同的两个主键结构。表格存储会按照主键的大小为行排序,具体参见表格存储数据模型和查询操作
    • 第一列主键作为分片键。分片键相同的数据会存放在同一个分片内,所以相同分片键下最好不要超过 10 G 以上数据,否则会导致单分片过大,无法分裂。另外,数据的读/写访问最好在不同的分片键上均匀分布,有利于负载均衡。
    • 属性列不需要定义。表格存储每行的数据列都可以不同,属性列的列名在写入时指定。
  • TableOptions

    TableOptions 包含表的 TTL、MaxVersions 和 MaxTimeDeviation 。

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

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

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

    索引表的 Meta 信息。使用表格存储创建一张数据表时,可以同时为其创建多张索引表。

    参数 定义 说明
    IndexName 索引表名字
    List<String> primaryKey 索引表类型 当前只支持IT_GLOBAL_INDEX
    List<String> definedColumns 索引表的属性列 必需为主表的预定义列组合。
    IndexType 索引表类型 当前只支持IT_GLOBAL_INDEX
    IndexUpdateMode 索引表更新模式 当前只支持IUM_ASYNC_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代表永不过期,例如设置过期时间为一年, 即为 365 * 24 * 3600。
            int maxVersions = 3; // 保存的最大版本数,设置为3即代表每列上最多保存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);
        }
  • 创建表(带索引)
       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。
    
            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);
        }