Create a table

Create a Wide Column model table with the Tablestore SDK for Java, and configure its schema, data versions, indexes, Stream, and encryption in the same request.

Prerequisites

Install the Tablestore SDK for Java and initialize the client.

Description

Call createTable to create a Wide Column model table. The request must contain at least one primary key column and specify the time to live (TTL) and maximum number of versions.

public CreateTableResponse createTable(CreateTableRequest createTableRequest) throws TableStoreException, ClientException

The following example creates a table named example_table. The table has one STRING primary key column, data never expires, and only one data version is retained.

TableMeta tableMeta = new TableMeta("example_table");
tableMeta.addPrimaryKeyColumn(
        new PrimaryKeySchema("id", PrimaryKeyType.STRING));

TableOptions tableOptions = new TableOptions();
tableOptions.setTimeToLive(-1);
tableOptions.setMaxVersions(1);

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

Note

After you create a table, wait until the table is loaded before you perform data operations.

Parameters

CreateTableRequest contains the following parameters.

Name	Type	Description
tableMeta (required)	`TableMeta`	The table schema.
tableOptions (required)	`TableOptions`	The data version and update settings of the table.
reservedThroughput (optional)	`ReservedThroughput`	The reserved read/write throughput, in capacity units (CUs). The default read and write CUs are both `0`. Non-zero values apply only to high-performance instances in CU mode.
indexMeta (optional)	`List<IndexMeta>`	The secondary indexes to create with the table.
streamSpecification (optional)	`StreamSpecification`	The Stream configuration.
enableLocalTxn (optional)	`Boolean`	Specifies whether to enable local transactions. Default value: `false`.
sseSpecification (optional)	`SSESpecification`	The data encryption configuration. You can enable data encryption only when you create a table. After the table is created, you cannot disable encryption or change its configuration.

Table schema

tableMeta is a TableMeta object that contains the following parameters.

Name	Type	Description
tableName (required)	`String`	The name of the table.
primaryKey (required)	`List<PrimaryKeySchema>`	The primary key column configurations. You can configure one to four primary key columns. The first primary key column is the partition key, and data is sorted in ascending order by primary key.
definedColumns (optional)	`List<DefinedColumnSchema>`	The predefined column configurations. Predefined columns can be used to create secondary indexes and search indexes.

Primary key columns

Each element in tableMeta.primaryKey[] is a PrimaryKeySchema object that contains the following parameters.

Name	Type	Description
name (required)	`String`	The name of the primary key column.
type (required)	`PrimaryKeyType`	The type of the primary key column. Valid values: `STRING`, `INTEGER`, and `BINARY`.
option (optional)	`PrimaryKeyOption`	The primary key column option. To use an auto-increment primary key column, set a non-partition `INTEGER` primary key column to `AUTO_INCREMENT`.

Predefined columns

Each element in tableMeta.definedColumns[] is a DefinedColumnSchema object that contains the following parameters.

Name	Type	Description
name (required)	`String`	The name of the predefined column.
type (required)	`DefinedColumnType`	The type of the predefined column. Valid values: `STRING`, `INTEGER`, `BINARY`, `DOUBLE`, and `BOOLEAN`.

Table configurations

tableOptions is a TableOptions object that contains the following parameters.

Name	Type	Description
timeToLive (required)	`Integer`	The time to live (TTL) of data, in seconds. Set this parameter to `-1` to retain data indefinitely. For other values, the minimum is `86400` (one day). Data that exceeds its TTL is automatically deleted. To use a search index or secondary index, set this parameter to `-1` or set `allowUpdate` to `false`.
maxVersions (required)	`Integer`	The maximum number of versions to retain for each attribute column. To use a search index or secondary index, set this parameter to `1`.
maxTimeDeviation (optional)	`Long`	The maximum version offset, in seconds. Default value: `86400` (one day). The difference between the timestamp of written data and the current system time must be within this offset. The valid version range is `[max(data write time - maximum version offset, data write time - TTL), data write time + maximum version offset)`.
allowUpdate (optional)	`Boolean`	Specifies whether data can be updated by calling `updateRow`. Default value: `true`. If you set this parameter to `false`, data cannot be updated.
updateFullRow (optional)	`Boolean`	Specifies whether to enable whole-row updates. Default value: `false`. You can set this parameter only when you create a table. You cannot modify it by calling `updateTable`.

Reserved read/write throughput

reservedThroughput is a ReservedThroughput object that contains the following parameter.

Name	Type	Description
capacityUnit (required)	`CapacityUnit`	The reserved read/write throughput configuration.

Capacity units

reservedThroughput.capacityUnit is a CapacityUnit object that contains the following parameters.

Name	Type	Description
readCapacityUnit (required)	`Integer`	The reserved read throughput, in CUs.
writeCapacityUnit (required)	`Integer`	The reserved write throughput, in CUs.

Secondary indexes

Each element in indexMeta[] is an IndexMeta object that contains the following parameters.

Name	Type	Description
indexName (required)	`String`	The name of the index.
primaryKey (required)	`List<String>`	The primary key columns of the index. They can consist of primary key columns and predefined columns from the table. For a local secondary index, the first primary key column must match the first primary key column of the table.
definedColumns (optional)	`List<String>`	The predefined columns included in the index. They must be predefined columns of the table.
indexType (optional)	`IndexType`	The index type. Valid values: `IT_GLOBAL_INDEX` (default, global secondary index) and `IT_LOCAL_INDEX` (local secondary index).
indexUpdateMode (optional)	`IndexUpdateMode`	The index update mode. A global secondary index must use `IUM_ASYNC_INDEX` (default, asynchronous update). A local secondary index must use `IUM_SYNC_INDEX` (synchronous update).

Stream configuration

streamSpecification is a StreamSpecification object that contains the following parameters.

Name	Type	Description
enableStream (required)	`Boolean`	Specifies whether to enable Stream. Default value: `false`.
expirationTime (optional)	`Integer`	The retention period of incremental logs, in hours. Maximum value: `168` (seven days). This parameter is required if `enableStream` is set to `true`.

Local transaction configuration

enableLocalTxn is a Boolean value. Take note of the following limits when you set this parameter.

Local transactions are supported only in Tablestore SDK for Java 5.11.0 and later.
Local transactions and auto-increment primary key columns are mutually exclusive. If an auto-increment primary key column is configured, local transactions do not take effect even when enabled.
To enable local transactions on an existing table, submit a ticket or join DingTalk technical support group 36165029092.

Server-side encryption configuration

sseSpecification is an SSESpecification object that contains the following parameters.

Name	Type	Description
enable (required)	`Boolean`	Specifies whether to enable data encryption. Default value: `false`.
keyType (optional)	`SSEKeyType`	The encryption type. Valid values: `SSE_KMS_SERVICE` (KMS service key encryption) and `SSE_BYOK` (Bring Your Own Key encryption). This parameter is required when encryption is enabled.
keyId (optional)	`String`	The ID of the customer master key. This parameter is required for BYOK encryption.
roleArn (optional)	`String`	The Alibaba Cloud Resource Name (ARN) of the Resource Access Management (RAM) role. This parameter is required for BYOK encryption.

Examples

Configure the table schema and data versions

The following example creates a table with two primary key columns and one predefined column. The example also configures the max version offset and disables updates.

TableMeta tableMeta = new TableMeta("example_table");
tableMeta.addPrimaryKeyColumn(
        new PrimaryKeySchema("id", PrimaryKeyType.STRING));
tableMeta.addPrimaryKeyColumn(
        new PrimaryKeySchema("device_id", PrimaryKeyType.INTEGER));
tableMeta.addDefinedColumn("status", DefinedColumnType.STRING);

TableOptions tableOptions = new TableOptions();
tableOptions.setTimeToLive(-1);
tableOptions.setMaxVersions(1);
tableOptions.setMaxTimeDeviation(86400L);
tableOptions.setAllowUpdate(false);

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

Create a secondary index together with the table

The following example creates a global secondary index named example_table_index together with the table. The index primary key column category must first be defined as a predefined column of the table.

TableMeta tableMeta = new TableMeta("example_table");
tableMeta.addPrimaryKeyColumn(
        new PrimaryKeySchema("id", PrimaryKeyType.STRING));
tableMeta.addDefinedColumn("category", DefinedColumnType.STRING);

TableOptions tableOptions = new TableOptions();
tableOptions.setTimeToLive(-1);
tableOptions.setMaxVersions(1);

IndexMeta indexMeta = new IndexMeta("example_table_index");
indexMeta.addPrimaryKeyColumn("category");
indexMeta.setIndexType(IndexType.IT_GLOBAL_INDEX);
indexMeta.setIndexUpdateMode(IndexUpdateMode.IUM_ASYNC_INDEX);

List<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
indexMetas.add(indexMeta);
CreateTableRequest request =
        new CreateTableRequest(tableMeta, tableOptions, indexMetas);
client.createTable(request);

Enable Stream

The following example enables Stream when the table is created and sets the expiration time of incremental logs to 24 hours.

TableMeta tableMeta = new TableMeta("example_table");
tableMeta.addPrimaryKeyColumn(
        new PrimaryKeySchema("id", PrimaryKeyType.STRING));

TableOptions tableOptions = new TableOptions();
tableOptions.setTimeToLive(-1);
tableOptions.setMaxVersions(1);

CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
request.setStreamSpecification(new StreamSpecification(true, 24));
client.createTable(request);

Enable local transactions

The following example enables local transactions when the table is created by calling setLocalTxnEnabled.

TableMeta tableMeta = new TableMeta("example_table");
tableMeta.addPrimaryKeyColumn(
        new PrimaryKeySchema("id", PrimaryKeyType.STRING));

TableOptions tableOptions = new TableOptions();
tableOptions.setTimeToLive(-1);
tableOptions.setMaxVersions(1);

CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
request.setLocalTxnEnabled(true);
client.createTable(request);

Encrypt a table

The following examples encrypt a table by using a KMS service key or BYOK.

Important

You can configure data encryption only when you create the table. After the table is created, you cannot disable encryption or change the encryption configuration.

KMS service key encryption

TableMeta tableMeta = new TableMeta("example_table");
tableMeta.addPrimaryKeyColumn(
        new PrimaryKeySchema("id", PrimaryKeyType.STRING));

TableOptions tableOptions = new TableOptions();
tableOptions.setTimeToLive(-1);
tableOptions.setMaxVersions(1);

CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
request.setSseSpecification(
        new SSESpecification(true, SSEKeyType.SSE_KMS_SERVICE));
client.createTable(request);

BYOK encryption

Note

To use BYOK encryption, first obtain the customer master key (CMK) ID and the RAM role ARN. For more information, see BYOK encryption.

TableMeta tableMeta = new TableMeta("example_table");
tableMeta.addPrimaryKeyColumn(
        new PrimaryKeySchema("id", PrimaryKeyType.STRING));

TableOptions tableOptions = new TableOptions();
tableOptions.setTimeToLive(-1);
tableOptions.setMaxVersions(1);

CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
String keyId = "key-xxxx****";
String roleArn = "acs:ram::1234****:role/example-role";
request.setSseSpecification(
        new SSESpecification(true, SSEKeyType.SSE_BYOK, keyId, roleArn));
client.createTable(request);