文档

主键列自增

更新时间:

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

特点

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

  • 自增列的值在分区键级别唯一且严格递增,但不保证连续。

  • 自增列的数据类型为64位的有符号长整型。

  • 自增列是数据表级别的,同一个实例下可以有自增列或者非自增列的数据表。

说明

无论是否使用主键列自增功能,不影响条件更新的规则,条件更新的规则请参见条件更新

场景

主键列自增功能适用于为电商网站的商品ID、大型网站的用户ID、论坛帖子的ID、聊天工具的消息ID等生成唯一标识。

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

注意事项

  • 每张数据表最多只能设置一个主键列为自增列,主键中的分区键不能设置为自增列。

  • 只能在创建数据表时指定自增列,对于已存在的数据表不能创建自增列。

  • 只有整型的主键列才能设置为自增列,系统自动生成的自增列值为64位的有符号长整型。

  • 属性列不能设置为自增列。

  • 主键自增列功能和局部事务功能不能同时使用。

  • 写入数据到带有自增主键列的表时,请务必返回并记录自增列的值,用于后续数据更新或者数据读取。

接口

主键列自增的相关接口说明请参见下表。

接口

说明

CreateTable

创建数据表时,请设置非分区键的主键列为自增列,否则无法使用主键列自增功能。

UpdateTable

数据表创建后,不能通过UpdateTable修改数据表的主键列为自增列。

PutRow

写入数据时,无需为自增列设置具体值,表格存储会自动生成自增列的值。

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

重要

要更新已存在的行数据时,如果未记录自增主键列的值,请先通过GetRange接口获取要更新的行主键信息,然后再进行数据更新。

UpdateRow

BatchWriteRow

GetRow

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

重要

写入数据时,如果未记录自增主键列的值,您可以使用范围读取数据按照第一个主键列确定范围读取数据。更多信息,请参见范围读取数据

BatchGetRow

使用方式

使用控制台

  1. 创建带有自增主键列的数据表。

    1. 登录表格存储控制台

    2. 概览页面,单击实例操作列的实例管理

    3. 实例详情页签的数据表列表区域,单击创建数据表

    4. 创建数据表对话框,配置数据表名称表主键,其他参数请根据实际场景进行配置。

      配置表主键时,您需要将其中一个非分区键的主键列类型选择为自增列

      说明

      关于参数配置的更多信息,请参见通过控制台创建数据表

    5. 单击确定

  2. 写入数据。

    1. 实例详情页签的数据表列表区域,单击数据表名称。

    2. 数据管理页签,单击插入数据

    3. 插入数据对话框,输入主键值以及根据实际增加属性列。

      其中自增列的值无需填写,系统会在写入数据时自动生成自增列的值。通过多次单击增加属性列并配置属性列的名称、类型、属性值等信息,您可以增加多个属性列。

    4. 单击确定

      系统会显示写入成功的数据。请记录行数据的完整主键信息用于后续更新或者读取数据。

使用命令行工具

  1. 创建并使用带有自增主键列的数据表。

    1. 执行create命令创建数据表。更多信息,请参见创建表

      以下示例用于创建带有自增主键列的mytable数据表。该数据表有uid(string类型)和pid(integer类型)两个主键列并设置第二主键列pid(integer类型)为自增列,表中数据永不过期。

      create -t mytable --pk '[{"c":"uid", "t":"string"}, {"c":"pid", "t":"integer", "opt":"auto"}]'
    2. 执行use --wc -t mytable命令使用数据表。

  2. 执行put命令写入一行数据。更多信息,请参见插入新数据

    说明

    写入数据后,如果需要获取完整主键信息,您可以执行scan命令获取指定行数据。更多信息,请参见扫描数据或者导出数据

    以下示例用于在数据表中插入一行数据。该行的第一主键列值为“86”,第二主键列值为null,属性列有name(string类型)和country(string类型)两列。

    put --pk '["86", null]' --attr '[{"c":"name", "v":"redchen"}, {"c":"country", "v":"china"}]'

使用SDK

您可以通过Java SDKGo SDKPython SDKNode.js SDK.NET SDKPHP SDK使用主键自增列功能。此处以Java SDK为例介绍主键自增列的使用。

  1. 创建带有自增主键列的数据表。

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

    以下示例用于创建数据表时配置主键自增列。该表的主键为pk1(String类型)和pk2(Integer类型),其中pk1主键列为分区键,pk2主键列为自增列。

    private static void createTable(SyncClient client) {
        //设置数据表名称。
        TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
        //为数据表添加主键列。第一列为分区键。
        tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING));
        //为数据表添加主键列。第二列为自增列,类型为INTEGER,属性为AUTO_INCREMENT。
        tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER, PrimaryKeyOption.AUTO_INCREMENT));
        //数据的过期时间,单位为秒,-1表示数据永不过期。
        int timeToLive = -1;  
        //保存的最大版本数,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();
        //第一列的值为receive_id(String类型)参数的值。
        primaryKeyBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString(receive_id));
        //第二列是主键自增列,此处无需填入具体值,只需要一个占位符AUTO_INCREMENT,表格存储会自动生成此值。
        primaryKeyBuilder.addPrimaryKeyColumn("pk2", 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());
    }

计费说明

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

  • 本页导读 (1)