Use Tablestore SDK for Java to create a data table - Tablestore

This topic describes how to use Tablestore SDK for Java to create a data table by using parameters and sample code. When you create a data table, you must specify the schema information and configuration information about the data table. You can specify the reserved read and write throughput for a data table in a high-performance instance.

Usage notes

After you create a data table, a few seconds are required to load the data table. 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.
Tablestore provides the data encryption feature. You can configure encryption-related parameters when you create a data table to increase the security of your data and meet compliance requirements. For more information, see Create an encrypted table.
In scenarios that require an auto-increment primary key column, such as item IDs on e-commerce websites and post IDs in forums, you can specify an auto-increment primary key column 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 an instance.
An OTSClient instance is initialized. For more information, see Initialize an OTSClient instance.

API operation

/**
 * Description: Create a data table based on the specified table schema. 
 * After you create a data table, several seconds are required to load the partitions in the data table. You can perform operations on the data table only after the partitions are loaded. 
 * Response: CreateTableResponse. 
 */
CreateTableResponse createTable(CreateTableRequest createTableRequest) throws TableStoreException, ClientException

Parameters

The following table describes the parameters that are included in createTableRequest.

Parameter	Description
tableMeta (required)	The schema information about the data table. You can configure the following parameters to specify the schema information: tableName: This parameter is required and specifies the name of the data table. primaryKey: This parameter is required and specifies the schema of the primary key for the data table. For more information, see Core components. The type of a primary key column can be String, Integer, or Binary. You can specify one to four primary key columns. Tablestore generates the primary key in the order in which the primary key columns are specified. By default, the rows in a data table are sorted in descending order by primary key. The first primary key column is the partition key. definedColumns: This parameter is optional and specifies the predefined columns of the data table. The type of a predefined column can be String, Integer, Binary, Double, or Boolean. Note Predefined columns are non-primary key columns that can be used as primary key columns or predefined columns of a secondary index that is created for the data table to accelerate data queries. You do not need to specify the schema of attribute columns when you create a data table. You can specify different numbers of attribute columns and different attribute column names for each row when you write data to a data table.
tableOptions (required)	The configuration information about the data table. You can configure the following parameters to specify the configuration information: timeToLive: This parameter is required and specifies the retention period of data in the data table. Unit: seconds. You can set this parameter to a value that is greater than or equal to 86400 or -1. A value of 86400 specifies one day. A value of -1 specifies that the data never expires. Important If you want to create a search index or secondary index for the data table, you must set this parameter to -1 or set the allowUpdate parameter to false. maxVersions: This parameter is required and specifies the maximum number of versions that can be retained for the data in each attribute column. Important If you want to create a search index or secondary index for the data table, you must set this parameter to 1. maxTimeDeviation: This parameter is optional and specifies the maximum difference between the current system time and the timestamp of the written data. Unit: seconds. Default value: 86400. The valid version range of data in an attribute column is a left-closed, right-open interval, which is calculated by using the following formula: Valid version range = `[max{Data write time - Max version offset, Data write time - TTL value}, Data write time + Max version offset)`. allowUpdate: This parameter is optional and specifies whether to allow update operations on the data table. Default value: true. Important If you want to use the time to live (TTL) feature of the search index that is created for the data table, you must set this parameter to false. If you want to update data in the data table, you can call the PutRow operation to write data to the data table.
indexMeta (optional)	The list of indexes. You can configure the following parameters for each index: indexName: This parameter is required and specifies the name of the index. primaryKey: This parameter is required and specifies the primary key columns of the index. The primary key columns of an index are a combination of primary key columns and predefined columns of the data table for which the index is created. Important If you want to create a local secondary index, the first primary key column of the index must be the first primary key column of the data table. definedColumns: This parameter is optional and specifies the predefined columns of the index. The predefined columns of an index are a combination of predefined columns of the data table for which the index is created. indexType: This parameter is optional and specifies the type of the index. Valid values: IT_GLOBAL_INDEX: global secondary index. This is the default value. IT_LOCAL_INDEX: local secondary index. indexUpdateMode: This parameter is optional and specifies the update mode of the index. Valid values: IUM_ASYNC_INDEX: asynchronous update mode. This is the default value. Note If you want to use the global secondary index feature, you must set the indexUpdateMode parameter to IUM_ASYNC_INDEX. IUM_SYNC_INDEX: synchronous update mode. Note If you want to use the local secondary index feature, you must set the indexUpdateMode parameter to IUM_SYNC_INDEX.
reservedThroughtput (optional)	The reserved read and write throughput. Unit: capacity unit (CU). Default value: 0. Important You can set the reserved read or write throughput to a value other than 0 only for a data table in a high-performance instance.
streamSpecification (optional)	The Stream configuration information about the data table. You can configure the following parameters to specify the Stream configuration information: enableStream: This parameter is optional and specifies whether to enable the Stream feature. Default value: false. A value of false specifies that the Stream feature is disabled. expirationTime: This parameter is optional and specifies the validity period of incremental logs. Unit: hours. Maximum value: 168. A value of 168 specifies seven days. Note When the Stream feature is enabled, you must configure the expirationTime parameter.
sseSpecification (optional)	The encryption configurations of the data table. Important After you create a data table, you cannot modify the encryption configurations of the data table.
enableLocalTxn (optional)	Specifies whether to enable the local transaction feature. Default value: false. A value of false specifies that the local transaction feature is disabled. Important Only Tablestore SDK for Java V5.11.0 and later support this feature. You cannot use the auto-incremental primary key column feature and the local transaction feature at the same time. If you specify an auto-increment primary key column, the local transaction settings 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

The following sample code provides an example on how to create a data table:

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. The table contains the pk1 primary key column of the String type and the pk2 primary key column of the Integer type. The pk1 primary key column is the partition key. The pk2 primary key column is an auto-increment primary key column. 
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING));
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER, PrimaryKeyOption.AUTO_INCREMENT));
    // Specify the TTL of data in the data table. A value of -1 specifies that data in the data table never expires. 
    int timeToLive = -1;
    // Specify the maximum number of versions that can be retained for data in each attribute column of the data table. In this example, only the latest version of data can be retained for each attribute column. 
    int maxVersions = 1;
    // Specify the maximum difference between the current system time and the timestamp of the written data. In this example, the maximum difference is set to 86,400 seconds (one day). 
    long maxTimeDeviation = 86400L;
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions, maxTimeDeviation);
    // Specify the reserved read or write throughput. You can set the reserved read or write throughput only to 0 for a data table in a capacity instance. You can set the reserved read or write throughput to a value other than 0 for a data table in a high-performance instance. 
    ReservedThroughput reservedThroughput = new ReservedThroughput(new CapacityUnit(0, 0));
    
    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, reservedThroughput);
    client.createTable(request);
}

Create a data table and a secondary index

Create a data table and a global secondary index

The following sample code provides an example on how to create a data table and a global secondary index for the data table at the same time:

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. The data table contains the pk1 primary key column of the String type and the pk2 primary key column of the Integer type. 
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING));
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER));
    // Add predefined columns to the data table. The predefined columns of the data table are the defcol1 column of the String type and the defcol2 column of the Integer type. 
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol1", DefinedColumnType.STRING));
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol2", DefinedColumnType.INTEGER));
    // Specify the TTL of data in the data table. A value of -1 specifies that data in the data table never expires. 
    int timeToLive = -1;
    // Specify the maximum number of versions that can be retained for data in each attribute column of the data table. In this example, only the latest version of data can be retained for each attribute column. 
    int maxVersions = 1;
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
    
    // Specify the configurations of the global secondary index.
    ArrayList<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
    // Specify the name of the index. 
    IndexMeta indexMeta = new IndexMeta("<INDEX_NAME>");
    // Add primary key columns to the index. The primary key columns of the index are defcol1, pk1, and pk2.
    indexMeta.addPrimaryKeyColumn("defcol1");
    indexMeta.addPrimaryKeyColumn("pk1");
    indexMeta.addPrimaryKeyColumn("pk2");
    // Add predefined columns to the index. The predefined column of the index is defcol2. 
    indexMeta.addDefinedColumn("defcol2");
    indexMetas.add(indexMeta);
    
    // Create the data table and global secondary index at the same time. 
    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, indexMetas);
    client.createTable(request);
}

Create a data table and a local secondary index

The following sample code provides an example on how to create a data table and a local secondary index for the data table at the same time:

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. The data table contains the pk1 primary key column of the String type and the pk2 primary key column of the Integer type. 
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING));
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER));
    // Add predefined columns to the data table. The predefined columns of the data table are the defcol1 column of the String type and the defcol2 column of the Integer type. 
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol1", DefinedColumnType.STRING));
    tableMeta.addDefinedColumn(new DefinedColumnSchema("defcol2", DefinedColumnType.INTEGER));
    // Specify the TTL of data in the data table. A value of -1 specifies that data in the data table never expires.  
    int timeToLive = -1;
    // Specify the maximum number of versions that can be retained for data in each attribute column of the data table. In this example, only the latest version of data can be retained for each attribute column. 
    int maxVersions = 1;
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
    
    // Specify the configurations of the local secondary index.
    ArrayList<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
    // Specify the name of the index. 
    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 you set the indexType parameter to IT_LOCAL_INDEX, you must set the indexUpdateMode parameter to IUM_SYNC_INDEX. 
    indexMeta.setIndexUpdateMode(IUM_SYNC_INDEX);
    // Add primary key columns to the index. The primary key columns of the index are pk1, defcol1, and pk2. 
    indexMeta.addPrimaryKeyColumn("pk1");
    indexMeta.addPrimaryKeyColumn("defcol1");
    indexMeta.addPrimaryKeyColumn("pk2");
    // Add predefined columns to the index. The predefined column of the index is defcol2. 
    indexMeta.addDefinedColumn("defcol2");
    indexMetas.add(indexMeta);
    
    // Create the data table and local secondary index at the same time. 
    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, indexMetas); 
    client.createTable(request);
}

Create a data table with the local transaction feature enabled

The following sample code provides an example on how to create a data table with the local transaction feature enabled:

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. The data table contains the pk1 primary key column of the String type and the pk2 primary key column of the Integer type. 
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk1", PrimaryKeyType.STRING));
    tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema("pk2", PrimaryKeyType.INTEGER));
    // Specify the TTL of data in the data table. A value of -1 specifies that data in the data table never expires. 
    int timeToLive = -1;
    // Specify the maximum number of versions that can be retained for data in each attribute column of the data table. In this example, only the latest version of data can be retained for each attribute column. 
    int maxVersions = 1;
    TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
    
    CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
    // Enable the local transaction feature. If you specify an auto-increment primary key column for a data table, the configurations of the local transaction feature do not take effect for the table. 
    request.setLocalTxnEnabled(true);
    client.createTable(request);
}

References

For information about the API operation that you can call to create a data table, see CreateTable.
For information about data versions and TTL, secondary indexes, and reserved read and write throughput, see Data versions and TTL, Overview, and What is reserved read and write throughput?
After you create a data table, you can perform the following operations:
- Operations on the table. For more information, see Operations on tables.
- Operations on data. For more information, see Basic operations on data.