主键列自增

注意事项

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

前提条件

已初始化Client。具体操作，请参见初始化Tablestore Client。

使用方法

1. 创建表时，将非分区键的主键列设置为自增列。

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

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

   如果需要获取写入数据后系统自动生成的自增列的值，将ReturnType设置为RT_PK，可以在数据写入成功后返回自增列的值。

   读取数据时，需要完整的主键值。通过设置PutRow、UpdateRow或者BatchWriteRow中的ReturnType为RT_PK可以获取完整的主键值。

   读取数据时，如果已记录完整主键，您可以使用读取单行数据或者批量读取数据方式读取数据；如果未记录自增主键列的值，您可以使用范围读取数据方式按照第一个主键列确定范围读取数据。

   说明

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

示例

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());
   }