How do I create a data table by using Tablestore SDK for Java? - Tablestore

This topic describes how to create a data table by calling the CreateTable operation. When you call the CreateTable operation, you must specify the schema information and configuration information about the data table. You can also configure the reserved read throughput and reserved write throughout based on your business requirements if the data table belongs to a high-performance instance. You can create one or more index tables when you create a data table.

Usage notes

It takes several seconds to load a data table after the data table is created. During this period, all read and write operations on the data table fail. Perform operations on the data table after the data table is loaded.
You must specify the primary key when you create a data table. A primary key consists of one to four primary key columns. Specify a name and data type for each primary key column.
You can enable data at rest encryption (DARE) by configuring data encryption settings when you create a data table. For more information, see Create an encrypted table.
You can configure an auto-increment primary key column for data such as item IDs on e-commerce websites, user IDs of large websites, post IDs on forums, and message IDs in chat tools when you create a data table. For more information, see Configure an auto-increment primary key column.

Prerequisites

A Tablestore instance is created in the Tablestore console. For more information, see Create instances.
An OTSClient instance is initialized. For more information, see Initialize an OTSClient instance.

Syntax

/**
 * When you call the CreateTable operation to create a data table, you must specify the required parameters, including the parameters about the table metadata, reserved read and write throughput, table configurations, server-side encryption configurations, and whether to enable the local transaction feature. 
 */
public class CreateTableRequest implements Request {
    /** The schema information about the data table. */
    private TableMeta tableMeta;
    /** The information about index tables. */
    private List<IndexMeta> indexMeta;
    /** The reserved read and write throughput of the data table. */
    private ReservedThroughput reservedThroughput;
    /** The configurations of the data table, including time-to-live (TTL) and max versions. */
    private TableOptions tableOptions;
    /** The stream configurations of the data table. Generally, this parameter is not required. */
    private OptionalValue<StreamSpecification> streamSpecification;
    /** The server-side encryption configurations of the data table. */
    private OptionalValue<SSESpecification> sseSpecification;
    /** Specifies whether to enable the local transaction feature. */
    private OptionalValue<Boolean> enableLocalTxn;
}

Parameters

Configure the parameters in the code based on the parameter description in the following table and the "Request syntax" section of the CreateTable topic.

Parameter	Description
tableMeta	The schema information about the data table. The schema information contains the following parameters: tableName: the name of the data table. primaryKey: the schema of the primary key for the data table. For more information, see Primary keys and attributes. Note You do not need to specify the schema for attribute columns. Different rows in a Tablestore table can have different attribute columns. You can specify the names of attribute columns when you write data to a data table. The primary key of a data table consists of one to four primary key columns. Primary key columns are sorted in the order in which they are added. For example, PRIMARY KEY (A, B, C) and PRIMARY KEY (A, C, B) have different schemas. Tablestore sorts rows based on the values of all primary key columns. The first primary key column is the partition key. Data that has the same partition key is stored in the same partition. We recommend that you keep the size of data with the same partition key less than or equal to 10 GB. Otherwise, a single partition may be too large to split. We also recommend that you evenly distribute read/write operations among different partition keys to facilitate load balancing. definedColumns: the predefined columns of the data table and the data types of the predefined columns. Primary key columns cannot be specified as predefined columns. You can use predefined columns as the index columns or attribute columns for index tables.
indexMetas	The schema information about the index table. Each indexMeta contains the following parameters: indexName: the name of the index table. primaryKey: the index key columns of the index table. The index key columns are a combination of primary key columns and predefined columns of the data table. If you want to create a local secondary index, the first primary key column of the index table must be the same as the first primary key column of the data table. definedColumns: the attribute columns of the index table. The attribute columns consist of the predefined columns of the data table. indexType: the type of the index. Valid values: IT_GLOBAL_INDEX and IT_LOCAL_INDEX. If the indexType parameter is not specified or is set to IT_GLOBAL_INDEX, the global secondary index feature is used. For more information, see Create a secondary index. Tablestore automatically synchronizes data from the indexed columns and primary key columns of the data table to the columns of the index table that you want to create in asynchronous mode. The synchronization latency is within a few milliseconds. If the indexType parameter is set to IT_LOCAL_INDEX, the local secondary index feature is used. For more information, see Create a secondary index. Tablestore automatically synchronizes the data from the indexed columns and primary key columns of the data table to the columns of the index table in synchronous mode. You can query the data from the index table immediately after the data is written to the data table. indexUpdateMode: the update mode of the index. Valid values: IUM_ASYNC_INDEX and IUM_SYNC_INDEX. If indexUpdateMode is not specified or is set to IUM_ASYNC_INDEX, the asynchronous mode is used to update the index. If you want to create a global secondary index, you must set the indexUpdateMode parameter to IUM_ASYNC_INDEX. If you set indexUpdateMode to IUM_SYNC_INDEX, the synchronous update mode is used to update the index. If you want to create a local secondary index, you must set the indexUpdateMode parameter to IUM_SYNC_INDEX.
tableOptions	The configuration information of the data table. For more information, see Data versions and TTL. The configuration information contains the following parameters: timeToLive: the time to live of data in the data table. The TTL indicates the validity period of data. If the retention period exceeds the timeToLive value, Tablestore automatically deletes expired data. The minimum time_to_live value is 86400, which is equal to one day. A value of -1 indicates that the data never expires. If you set the timeToLive parameter to -1 for the data table, the data in the data table never expires. After the data table is created, you can call the UpdateTable operation to modify the value of the timeToLive parameter. Unit: seconds. Important If you want to create an index table for the data table, the timeToLive parameter must meet one of the following requirements: The TimeToAlive parameter of the data table is set to -1, which means that data in the data table never expires. The timeToLive parameter of the data table is set to a value other than -1 and update operations on the data table are prohibited. maxVersions: the maximum number of versions of the data that can be retained for a single attribute column. If the number of versions of data in an attribute column exceeds the value of the maxVersions parameter, the system automatically deletes the data of earlier versions. When you create a data table, you can set this parameter based on your business requirements. After the data table is created, you can call the UpdateTable operation to modify the value of the maxVersions parameter. Important If you want to create an index table for the data table, you must set the maxVersions parameter to 1. maxTimeDeviation: the max version offset, which is the maximum difference between the current system time and the timestamp of the written data. The difference between the version number and the time at which the data is written must be less than or equal to the value of the maxTimeDeviation parameter. Otherwise, an error occurs when the data is written. The valid version range of data in an attribute column is calculated by using the following formula: Valid version range = `[max{Data written time - Max Version Offset, Data written time - TTL value}, Data written time + Max Version Offset)`. When you create a data table, Tablestore uses the default value of 86400 if you do not specify a max version offset. After the data table is created, you can call the UpdateTable operation to modify the value of the maxTimeDeviation parameter. Unit: seconds. allowUpdate: specifies whether to allow the UpdateRow operation. The default value is true, which indicates that the UpdateRow operation is allowed. If you set allowUpdate to false, the UpdateRow operation is prohibited. Important If you want to use the lifecycle feature of a search index, you must set this parameter to false to prohibit data writes by UpdateRow. You can call the UpdateTable operation to modify the configurations of a data table, including TTL and max versions. For more information, see Update table information.
reservedThroughtput	The reserved read throughput and reserved write throughput of the data table. You can set the reserved read throughput and reserved write throughput only to 0 for data tables in capacity instances. Reserved throughputs do not apply to these instances. The default value 0 indicates that you are charged for all throughput on a pay-as-you-go basis. Unit: CU. If you set the reserved read throughput and reserved write throughout to a value that is greater than 0 for a data table, Tablestore reserves related resources for the data table. After you create the data table, you are charged for the reserved throughput resources. You are charged for additional throughput on a pay-as-you-go basis. For more information, see Billing overview. If you set the reserved read throughput and reserved write throughout to 0, Tablestore does not reserve related resources for the data table.
sseSpecification	The encryption configurations of the data table. Tablestore provides two encryption methods: encryption based on a Key Management Service (KMS) key and encryption based on Bring Your Own Key (BYOK). Select a method based on your business requirements. For more information, see Create an encrypted table.
enableLocalTxn	Specifies whether to enable the local transaction feature. The value of this parameter is of the BOOLEAN type. Default value: false. A value of false indicates that the local transaction feature is disabled. If you want to enable the local transaction feature when you create a data table, set this parameter to true. Important Tablestore SDK for Java V5.11.0 or later supports this feature. You cannot use the auto-increment primary key column feature and the local transaction feature at the same time. If the auto-increment primary key column feature is enabled when you create a data table, the configurations of the local transaction feature do not take effect. If the local transaction feature is disabled when you create a data table and you want to use the feature after the data table is created, submit a ticket.

Examples

Create a data table without an index

The following sample code provides an example on how to create a data table without an index. The primary key column of the data table is the pk column of the STRING type. A maximum of three versions of data can be retained for each attribute column, and the data never expires.

private static void createTable(SyncClient client) {
    // Specify the name of the data table. 
    TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
    // Add a primary key column to the data table. 
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk", PrimaryKeyType.STRING)); 
    // Specify the validity period of data. A value of -1 specifies that the data never expires. Unit: seconds. You must set the timeToLive parameter to -1 for a data table for which you want to create an index table. 
    int timeToLive = -1; 
    // Specify the maximum number of data versions that can be retained for each column. A value of 1 specifies that only the latest version of data is retained for each column. You must set the maxVersions parameter to 1 for a data table for which you want to create an index table. 
    int maxVersions = 3; 
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
        
    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
    request.setReservedThroughput(new ReservedThroughput(new CapacityUnit(0, 0))); // Specify the reserved read throughput and reserved write throughout. The reserved read throughput and reserved write throughout can be set only to 0 for data tables in capacity instances. You can set the reserved read throughput and reserved write throughout to a non-zero value for data tables in high-performance instances. 
    client.createTable(request);
}

Configure a global secondary index when you create a data table

The following sample code provides an example on how to create a data table and configure a global secondary index for the data table at the same time. The data table contains two primary key columns: the pk1 column of the STRING type and the pk2 column of the INTEGER type. The data table also contains two predefined columns: the defcol1 column of the STRING type and the defcol2 column of the INTEGER type. Only the latest version of data is retained for each attribute column, and the data never expires. The primary key columns of the global secondary index are the defcol1, pk1, and pk2 columns. The attribute column of the global secondary index is the defcol2 column.

private static void createTable(SyncClient client) {
    // Specify the name of the data table. 
    TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
    // Add primary key columns to the data table. 
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING)); 
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER)); 
    // Add predefined columns to the data table. 
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol1", DefinedColumnType.STRING)); 
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol2", DefinedColumnType.INTEGER)); 
    // Specify the validity period of data. A value of -1 specifies that the data never expires. Unit: seconds. You must set the timeToLive parameter to -1 for a data table for which you want to create an index table. 
    int timeToLive = -1; 
    // Specify the maximum number of data versions that can be retained for each column. A value of 1 specifies that only the latest version of data is retained for each column. You must set the maxVersions parameter to 1 for a data table for which you want to create an index table. 
    int maxVersions = 1; 
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);

    ArrayList<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
    // Specify the name of the index table. 
    IndexMeta indexMeta = new IndexMeta("<INDEX_NAME>");
    // Add a primary key column to the index table. 
    indexMeta.addPrimaryKeyColumn("defcol1"); 
    // Add an attribute column to the index table. 
    indexMeta.addDefinedColumn("defcol2"); 
    indexMetas.add(indexMeta);

    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, indexMetas); // Create the index table when you create the data table. 

    client.createTable(request);
}

Configure a local secondary index when you create a data table

The following sample code provides an example on how to create a data table and configure a local secondary index for the data table at the same time. The data table contains two primary key columns: the pk1 column of the STRING type and the pk2 column of the INTEGER type. The data table also contains two predefined columns: the defcol1 column of the STRING type and the defcol2 column of the INTEGER type. Only the latest version of data is retained for each attribute column, and the data never expires. The primary key columns of the local secondary index are the defcol1, pk1, and pk2 columns. The attribute column of the local secondary index is the defcol2 column.

private static void createTable(SyncClient client) {
    // Specify the name of the data table. 
    TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
    // Add primary key columns to the data table. 
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING)); 
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER)); 
    // Add predefined columns to the data table. 
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol1", DefinedColumnType.STRING)); 
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol2", DefinedColumnType.INTEGER)); 
    // Specify the validity period of data. A value of -1 specifies that the data never expires. Unit: seconds. You must set the timeToLive parameter to -1 for a data table for which you want to create an index table. 
    int timeToLive = -1; 
    // Specify the maximum number of data versions that can be retained for each column. A value of 1 specifies that only the latest version of data is retained for each column. You must set the maxVersions parameter to 1 for a data table for which you want to create an index table. 
    int maxVersions = 1; 
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);

    ArrayList<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
    // Specify the name of the index table. 
    IndexMeta indexMeta = new IndexMeta("<INDEX_NAME>");
    // Set the index type to IT_LOCAL_INDEX. 
    indexMeta.setIndexType(IT_LOCAL_INDEX); 
    // Set the index update mode to IUM_SYNC_INDEX. If the indexType parameter is set to IT_LOCAL_INDEX, you must set the indexUpdateMode parameter to IUM_SYNC_INDEX. 
    indexMeta.setIndexUpdateMode(IUM_SYNC_INDEX);  
    // Add a primary key column to the index table. The first primary key column of the index table must be the same as the first primary key column of the data table. 
    indexMeta.addPrimaryKeyColumn("pk1"); 
    // Add a primary key column to the index table. 
    indexMeta.addPrimaryKeyColumn("defcol1"); 
    // Add an attribute column to the index table. 
    indexMeta.addDefinedColumn("defcol2"); 
    indexMetas.add(indexMeta);

    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, indexMetas); // Create the index table when you create the data table. 

    client.createTable(request);
}

Enable the local transaction feature when you create a data table

The following sample code provides an example on how to enable the local transaction feature when you create a data table. The data table contains two primary key columns: the pk1 column of the STRING type and the pk2 column of the INTEGER type. Only the latest version of data is retained for each attribute column, and the data never expires.

private static void createTable(SyncClient client) {
    // Specify the name of the data table. 
    TableMeta tableMeta = new TableMeta("<TABLE_NAME>");
    // Add primary key columns to the data table. 
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING));
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER));
    // Specify the validity period of data. A value of -1 specifies that the data never expires. Unit: seconds. You must set the timeToLive parameter to -1 for a data table for which you want to create an index table. 
    int timeToLive = -1; 
    // Specify the maximum number of data versions that can be retained for each column. A value of 1 specifies that only the latest version of data is retained for each column. You must set the maxVersions parameter to 1 for a data table for which you want to create an index table. 
    int maxVersions = 1; 
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);

    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
    // Enable the local transaction feature. If you enable the auto-increment primary key column feature for the data table, the configurations of the local transaction feature do not take effect. 
    request.setLocalTxnEnabled(true); 

    client.createTable(request);
}

References

To read data from and write data to a data table, you can call the related API operations. For more information, see Basic operations on data.
After you enable the local transaction feature for a data table, you can create a local transaction and perform read and write operations on the data in the local transaction. For more information, see Use the local transaction feature.
If you no longer need a data table, you can delete the data table. For more information, see Delete a table.