Auto-increment primary key columns - Tablestore SDK for Java - Tablestore

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.
Use Tablestore SDK for Java 4.2.0 or later.

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

PrimaryKeySchema parameters

The following parameters define the 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`.

RowPutChange parameters

The following parameters control writes to an auto-increment primary key column and the returned data.

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.

Return values

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.