This topic describes how to use an auto-increment primary key column. You cannot set a partition key to an auto-increment column. If you write data to a table that contains an auto-increment primary key column, you do not need to specify a specific value for the auto-increment primary key column because Tablestore generates a value for the auto-increment primary key column. The value generated for the auto-increment primary key column is unique, and all values in auto-increment primary key columns increase sequentially within a partition that shares the same partition key value.

Features

The auto-increment function of the primary key column has the following features:

  • The values of auto-increment primary key columns are unique and increase sequentially but not always continuously within a partition that shares the same partition key value.
  • The value of an auto-increment primary key column is 64-bit signed long integer.
  • You can create an auto-increment primary key column for a table. An instance can include tables that contain and tables that do not contain auto-increment primary key columns.
Note The auto-increment function of the primary key column does not affect the rule of conditional update. For more information about conditional update, see Conditional update.

Limits

The auto-increment function of the primary key column has the following limits:

  • You can create at most one auto-increment primary key column for a table. You cannot set a partition key to an auto-increment column.
  • You can create an auto-increment primary key column only when you create a table. You cannot create an auto-increment primary key column for an existing table.
  • An auto-increment primary key column can only be an integer column. The generated value for an auto-increment primary key column is 64-bit signed long integer.
  • You can not set an attribute column to an auto-increment primary key column.

API operations

The following table describes the API operations for the auto-increment function of the primary key column.
API operation Description
CreateTable When you create a table, you cannot set the partition key to be an auto-increment primary key column. If you set the partition key to be an auto-increment primary key column, values in the column cannot be automatically generated.
UpdateTable After a table is created, you cannot use the UpdateTable operation to change a primary key column to an auto-increment primary key column.
PutRow When you write data to a table, you do not need to specify a specific value for the auto-increment primary key column. Tablestore generates a value for the auto-increment primary key column.

You can set ReturnType to RT_PK to obtain values of all primary key columns and use the values in GetRow to query data.

UpdateRow
BatchWriteRow
GetRow You must use values of all primary key columns when you use GetRow. To obtain values of all primary key columns, you can set ReturnType to RT_PK in PutRow, UpdateRow, or BatchWriteRow.
BatchGetRow

Examples

The use of the auto-increment function of the primary key column involves the CreateTable, PutRow, UpdateRow, and BatchWriteRow operations.

  1. Create a table

    To create an auto-increment primary key column when you create a table, you must set the attribute of the primary key column to AUTO_INCREMENT.

    private static void createTable(SyncClient client) {
            TableMeta tableMeta = new TableMeta(“table_name”);
            // Create the first primary key column, which is also the partition key.
            tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("PK_1", PrimaryKeyType.STRING));
            // Create the second primary key column, and set it to an auto-increment column. The type is set to INTEGER, and the attribute is set to AUTO_INCREMENT.
            tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("PK_2", PrimaryKeyType.INTEGER, PrimaryKeyOption.AUTO_INCREMENT));
            int timeToLive = -1;  // Specify that data never expires.
            int maxVersions = 1;  // Specify that only one version of data is saved.
            TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
            CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
            client.createTable(request);
        }
  2. Write data

    When you write data to a table, you do not need to specify a specific value for the auto-increment primary key column. Instead, you need only to set the value in the auto-increment primary key column to AUTO_INCREMENT.

        private static void putRow(SyncClient client, String receive_id) {
            // Create the primary key.
            PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
            // Set the value in the first primary key column to the first four digits of md5(receive_id).
            primaryKeyBuilder.addPrimaryKeyColumn("PK_1", PrimaryKeyValue.fromString("Hangzhou");
            // Set the value in the second primary key column to AUTO_INCREMENT. The second primary key column is an auto-increment primary key column, and you do not need to specify a specific value for it. Tablestore generates a value for the auto-increment primary key column.
            primaryKeyBuilder.addPrimaryKeyColumn("PK_2", PrimaryKeyValue.AUTO_INCREMENT);
            PrimaryKey primaryKey = primaryKeyBuilder.build();
            RowPutChange rowPutChange = new RowPutChange("table_name", primaryKey);
            // Set ReturnType to RT_PK to include the primary key column values in the returned result. By default, no primary key column values are returned if ReturnType is not set.
            rowPutChange.setReturnType(ReturnType.RT_PK);
            // Add attribute columns.
            rowPutChange.addColumn(new Column("content", ColumnValue.fromString(content)));
            // Write data to the table.
            PutRowResponse response = client.putRow(new PutRowRequest(rowPutChange));
            // Display the returned primary key value.
            Row returnRow = response.getRow();
            if (returnRow ! = null) {
                System.out.println("PrimaryKey:" + returnRow.getPrimaryKey().toString());
            }
            // Display the consumed capacity units (CUs).
            CapacityUnit  cu = response.getConsumedCapacity().getCapacityUnit();
            System.out.println("Read CapacityUnit:" + cu.getReadCapacityUnit());
            System.out.println("Write CapacityUnit:" + cu.getWriteCapacityUnit());
        }

Usage

You can use the following Tablestore SDKs to implement the auto-increment function of the primary key column:

Billing methods

The implementation of the auto-increment function of the primary key column does not affect the current billing rules. Values of returned primary key columns do not consume additional read CUs.