设置非分区键的主键列为自增列后,在写入数据时,无需为自增列设置具体值,表格存储会自动生成自增列的值。该值在分区键级别唯一且严格递增。

特点

主键列自增具有如下特点:

  • 自增列的值在分区键级别唯一且严格递增,但不保证连续。
  • 自增列的数据类型为64位的有符号长整型。
  • 自增列是数据表级别的,同一个实例下可以有自增列或者非自增列的数据表。
说明 无论是否使用主键列自增功能,不影响条件更新的规则,条件更新的规则请参见条件更新

场景

适用于系统设计中需要使用主键列自增功能的场景,例如电商网站的商品ID、大型网站的用户ID、论坛帖子的ID、聊天工具的消息ID等。

应用案例请参见Tablestore主键列自增功能在IM系统中的应用

限制

主键列自增有如下限制:

  • 每张数据表最多只能设置一个主键列为自增列,主键中的分区键不能设置为自增列。
  • 只能在创建数据表时指定自增列,对于已存在的数据表不能创建自增列。
  • 只有整型的主键列才能设置为自增列,系统自动生成的自增列值为64位的有符号长整型。
  • 属性列不能设置为自增列。

接口

主键列自增的相关接口说明请参见下表。
接口 说明
CreateTable 创建数据表时,请设置非分区键的主键列为自增列,否则无法使用主键列自增功能。
UpdateTable 数据表创建后,不能通过UpdateTable修改数据表的主键列为自增列。
PutRow 写入数据时,无需为自增列设置具体值,表格存储会自动生成自增列的值。

通过设置ReturnType为RT_PK,可以获取完整的主键值,完整的主键值可以用于GetRow查询数据。

UpdateRow
BatchWriteRow
GetRow 使用GetRow时需要完整的主键值,通过设置PutRow、UpdateRow或者BatchWriteRow中的ReturnType为RT_PK可以获取完整的主键值。
BatchGetRow

示例

主键自增列功能主要涉及创建表(CreateTable)和写数据(PutRow、UpdateRow和BatchWriteRow)两类接口。

  1. 创建表

    创建表时,只需将自增的主键属性设置为AUTO_INCREMENT。

    private static void createTable(SyncClient client) {
            TableMeta tableMeta = new TableMeta(“table_name”);
            //第一列为分区键。
            tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("PK_1", PrimaryKeyType.STRING));
            //第二列为自增列,类型为INTEGER,属性为AUTO_INCREMENT。
            tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("PK_2", PrimaryKeyType.INTEGER, PrimaryKeyOption.AUTO_INCREMENT));
            int timeToLive = -1;  //数据永不过期。
            int maxVersions = 1;  //只保存一个数据版本。
            TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
            CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
            client.createTable(request);
        }
  2. 写数据

    写入数据时,无需为自增列设置具体值,只需将自增列的值设置为占位符AUTO_INCREMENT。

        private static void putRow(SyncClient client, String receive_id) {
            //构造主键。
            PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
            //第一列的值为md5(receive_id)前4位。
            primaryKeyBuilder.addPrimaryKeyColumn(“PK_1”, PrimaryKeyValue.fromString("Hangzhou");
            //第二列是主键自增列,此处无需填入具体值,只需要一个占位符AUTO_INCREMENT,表格存储会自动生成此值。
            primaryKeyBuilder.addPrimaryKeyColumn("PK_2", PrimaryKeyValue.AUTO_INCREMENT);
            PrimaryKey primaryKey = primaryKeyBuilder.build();
            RowPutChange rowPutChange = new RowPutChange("table_name", primaryKey);
            //此处设置返回类型为RT_PK,即在返回结果中包含PK列的值。如果不设置ReturnType,默认不返回。
            rowPutChange.setReturnType(ReturnType.RT_PK);
            //加入属性列。
            rowPutChange.addColumn(new Column("content", ColumnValue.fromString(content)));
            //写入数据到表格存储。
            PutRowResponse response = client.putRow(new PutRowRequest(rowPutChange));
            //打印返回的PK列。
            Row returnRow = response.getRow();
            if (returnRow != null) {
                System.out.println("PrimaryKey:" + returnRow.getPrimaryKey().toString());
            }
            //打印消耗的CU。
            CapacityUnit  cu = response.getConsumedCapacity().getCapacityUnit();
            System.out.println("Read CapacityUnit:" + cu.getReadCapacityUnit());
            System.out.println("Write CapacityUnit:" + cu.getWriteCapacityUnit());
        }

使用

您可以使用如下语言的SDK实现主键列自增功能。

计费

使用主键列自增功能不影响现有计费规则,返回的主键列数据不会额外消耗读CU。