Create a table

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

Parameters

CreateTableRequest contains the following parameters.

• tableMeta (required) TableMeta: The table schema, which contains the following parameters.

  Name	Type	Description
  tableName (required)	String	The name of the table.
  primaryKey (required)	List<PrimaryKeySchema>	The primary key schema of the table. You can configure one to four primary key columns. Data is sorted in ascending order by primary key. The first primary key column is the partition key. Primary key columns support the STRING, INTEGER, and BINARY data types. An integer primary key column that is not the partition key can be configured as an auto-increment primary key column.
  definedColumns (optional)	List<DefinedColumnSchema>	The predefined columns of the table. Predefined columns are attribute columns used to create secondary indexes and search indexes. Supported data types: STRING, INTEGER, BINARY, DOUBLE, and BOOLEAN.

• tableOptions (required) TableOptions: The data version and update settings of the table, which contain the following parameters.

  Name	Type	Description
  timeToLive (required)	OptionalValue<Integer>	The time to live (TTL) of data. Unit: 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 search indexes or secondary indexes, set the TTL to -1 or set the allowUpdate parameter to false.
  maxVersions (required)	OptionalValue<Integer>	The maximum number of data versions to retain. To use a search index or secondary index, set this parameter to 1.
  maxTimeDeviation (optional)	OptionalValue<Long>	The max version offset. Unit: seconds. Default value: 86400 (one day). The difference between the timestamp of the written data and the current system time must be within the max version offset. Otherwise, the write operation fails. The valid version range for attribute column data is [max(Data write time - Max version offset, Data write time - Time to live), Data write time + Max version offset).
  allowUpdate (optional)	OptionalValue<Boolean>	Specifies whether data can be updated by using the updateRow method. Default value: true. If this parameter is set to false, data cannot be updated.

• indexMeta (optional) List<IndexMeta>: The secondary indexes to create together with the table. Each index 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. The index primary key can consist of primary key columns and predefined columns from the table. For a local secondary index, the first primary key column of the index must match the first primary key column of the table.
  definedColumns (optional)	List<String>	The predefined columns of the index. The columns must be predefined columns of the table.
  indexType (optional)	IndexType	The type of the index. Valid values: IT_GLOBAL_INDEX (default): global secondary index. IT_LOCAL_INDEX: local secondary index.
  indexUpdateMode (optional)	IndexUpdateMode	The update mode of the index. Valid values: IUM_ASYNC_INDEX (default): asynchronous update. A global secondary index must use asynchronous updates. IUM_SYNC_INDEX: synchronous update. The update mode for a local secondary index must be synchronous.

• streamSpecification (optional) OptionalValue<StreamSpecification>: The Stream configuration, which contains the following parameters.

  Name	Type	Description
  enableStream (required)	boolean	Specifies whether to enable the stream. Default value: false.
  expirationTime (optional)	OptionalValue<Integer>	The retention period of incremental logs. Unit: hours. Maximum value: 168 (7 days). The expirationTime parameter is required if enableStream is set to true.

• enableLocalTxn (optional) OptionalValue<Boolean>: Specifies whether to enable local transactions. Default value: false.

  • 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.

• sseSpecification (optional) OptionalValue<SSESpecification>: The data encryption settings. You can configure encryption only when you create the table. The following table describes the parameters.

  Name	Type	Description
  enable (required)	boolean	Specifies whether to enable data encryption. Default value: false.
  keyType (optional)	OptionalValue<SSEKeyType>	The encryption type. Valid values: SSE_KMS_SERVICE: encryption that uses a KMS service key. SSE_BYOK: Bring-Your-Own-Key (BYOK) encryption.
  keyId (optional)	OptionalValue<String>	The ID of the customer master key (CMK). This parameter is required when keyType is set to SSE_BYOK.
  roleArn (optional)	OptionalValue<String>	The Alibaba Cloud Resource Name (ARN) of the Resource Access Management (RAM) role. This parameter is required when keyType is set to SSE_BYOK.

• reservedThroughput (optional) ReservedThroughput: The reserved read/write throughput. Unit: capacity unit (CU). Default value: 0. Applies only to compute-optimized instances in CU mode.

Examples

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

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

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

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

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

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