Use auto-increment primary key columns

Use Tablestore SDK for Java to configure a non-partition primary key column as auto-increment when you create a table and retrieve the generated value when you write data.

Prerequisites

Install the Tablestore SDK for Java and initialize the client. Auto-increment primary key columns require version 4.2.0 or later. We recommend that you use the latest version.

Function description

Auto-increment primary key columns require three steps: configure the column, use a placeholder when you write data, and retrieve the generated value.

Note

An auto-increment primary key column must be a non-partition key of the INTEGER type and must be configured when you create the table. Each table can contain only one auto-increment primary key column. Tablestore generates 64-bit signed integers for the column.

Generated values are unique and strictly increase within the same partition key, but they may not be consecutive.

Configure an auto-increment primary key column

Set the option of a non-partition primary key column to PrimaryKeyOption.AUTO_INCREMENT when you create the table.

The following example creates the example_table table. The table uses id as the partition key and incr as the auto-increment primary key column.

Note

Wait until the table is loaded before you write data.

String tableName = "example_table";

TableMeta tableMeta = new TableMeta(tableName);
tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("id", PrimaryKeyType.STRING));
tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema(
        "incr", PrimaryKeyType.INTEGER, PrimaryKeyOption.AUTO_INCREMENT));

TableOptions tableOptions = new TableOptions(-1, 1);
CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
client.createTable(request);

Write data and retrieve the generated value

Set the auto-increment column value to PrimaryKeyValue.AUTO_INCREMENT when you write data. To retrieve the generated value, set the return type to ReturnType.RT_PK. Otherwise, the response does not include primary key information.

The following example writes a row to example_table and retrieves the generated value of the incr column from the response.

PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
primaryKeyBuilder.addPrimaryKeyColumn("id", PrimaryKeyValue.fromString("partition-a"));
primaryKeyBuilder.addPrimaryKeyColumn("incr", PrimaryKeyValue.AUTO_INCREMENT);
PrimaryKey primaryKey = primaryKeyBuilder.build();

RowPutChange rowPutChange = new RowPutChange("example_table", primaryKey);
rowPutChange.addColumn("payload", ColumnValue.fromString("example-value"));
rowPutChange.setReturnType(ReturnType.RT_PK);

PutRowResponse response = client.putRow(new PutRowRequest(rowPutChange));
long generatedValue = response.getRow().getPrimaryKey()
        .getPrimaryKeyColumn("incr").getValue().asLong();
System.out.println("Generated value: " + generatedValue);

Parameters

Auto-increment primary key column

PrimaryKeySchema contains the following parameters related to an auto-increment primary key column.

Name	Type	Description
name (required)	`String`	The name of the auto-increment primary key column.
type (required)	`PrimaryKeyType`	The data type of the auto-increment primary key column. Set this parameter to `INTEGER`.
option (required)	`PrimaryKeyOption`	The primary key column configuration. Set this parameter to `AUTO_INCREMENT`.

Write configurations

RowPutChange contains the following parameters related to an auto-increment primary key column.

Name	Type	Description
primaryKey (required)	`PrimaryKey`	The primary key of the row. The column names, order, and types must match the table schema. Set the auto-increment column value to `PrimaryKeyValue.AUTO_INCREMENT`.
returnType (optional)	`ReturnType`	The return type. The default value is `RT_NONE`, which does not return primary key information. Set this parameter to `RT_PK` to return the complete primary key, including the generated value.

Response

The following PutRowResponse field contains the generated auto-increment value.

Field	Type	Description
`row`	`Row`	Call `getRow()` to obtain the primary key of the written row. The field is returned only when `returnType` is set to `RT_PK` and contains the generated auto-increment value.