When you create a table, you must specify TableMeta and TableOptions. You can also set ReservedThroughput as needed.

Note After you create the table, Tablestore loads shards of the table to a specified node. And you can read data from or write data to the table within a few seconds. An exception may occur if you immediately attempt to read from or write to the table after you create the table.

Parameters

  • TableMeta

    TableMeta includes the TableName and List parameters.

    Parameter Description
    TableName The name of the table.
    List The list of primary key columns.
    • A table can contain up to four primary key columns. Primary key columns are sorted in the order in which they are added. For example, primary key schema PRIMARY KEY (A, B, C) is different from PRIMARY KEY (A, C, B). Tablestore sorts rows based on the values of all primary key columns.
    • The first primary key column serves as the partition key. Data with the same partition key value is stored in the same partition. Therefore, we recommend that you assign no more than 10 GB of data with the same partition key value. Otherwise, individual partitions are too large and cannot be split. We recommend that you distribute requests in an even manner to read and write data to different partition keys for load balancing.
    • Attribute columns are optional. Different rows in Tablestore can have different data columns. The names of attribute columns can be specified when data is written.
  • TableOptions

    TableOptions includes the TTL, MaxVersions, and MaxTimeDeviation parameters for a table.

    Parameter Description
    TTL The time to live, which indicates the lifespan of data.
    • Unit: seconds.
    • If you do not want data to expire, set TTL to -1.
    • Tablestore checks whether data has expired based on the maxVersions, current time, and timeToLive values. Data is expired and deleted if if the following condition is met: Current time - Data timestamp > Table TTL.
    • When you write data configured with TTL, ensure that you specify a valid timestamp. We recommend that you set MaxTimeDeviation to specify the timestamp.
    MaxTimeDeviation The maximum version offset between the timestamp of written data and the current system time.
    • By default, the system generates a timestamp for new data. The system checks whether data is expired based on the timestamp. You can specify the timestamp of written data. When the version offset between the timestamp of written data and the current system time is greater than the specified TTL, the written data immediately expires. To solve this problem, set MaxTimeDeviation.
    • Unit: seconds.
    • You can specify this parameter when you create the table or modify it by using the UpdateTable operation.
    MaxVersions The maximum number of versions that each attribute column can contain.

    If the number of versions of an attribute column is greater than the value of MaxVersions, Tablestore only keeps the latest version that you have specified for MaxVersions.

  • ReservedThroughtput

    The configuration of reserved read and write throughput of a table.

    • Fees are charged based on the reserved read and write throughput you have specified in the ReservedThroughtput field.
    • If the ReservedThroughtput value is greater than 0, fees are charged based on the reserved throughput and duration. Tablestore charges additional reserved read and write throughput on a pay-as-you-go basis. For more information, see Billing items and pricing to avoid unexpected fees.
    • The default value 0 indicates that all throughput is billed based on a pay-as-you-go basis.
    • You can set the reserved read and write throughput only to 0 for capacity instances. Reserved throughput does not apply to these instances.
  • IndexMetas

    The metadata of the index table. You can create multiple index tables for a data table when creating the data table in Tablestore.

    Parameter Description
    IndexName The name of the index table.
    List<String> primaryKey The type of the index table.

    Only IT_GLOBAL_INDEX is supported.

    List<String> definedColumns The attribute columns in the index table.

    These attribute columns are a combination of columns predefined in the base table.

    IndexType The type of the index table.

    Only IT_GLOBAL_INDEX is supported.

    IndexUpdateMode The mode to update the index table.

    Tablestore only supports IUM_ASYNC_INDEX.

Examples

  • Create a base table without creating an index table
    private static void createTable(SyncClient client) {
            TableMeta tableMeta = new TableMeta(TABLE_NAME);
            tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema(PRIMARY_KEY_NAME, PrimaryKeyType.STRING)); // Specify a primary key column to the base table.
            int timeToLive = -1; // The data expiration time in seconds. A value of -1 indicates that the data never expires. For example, to set the validity period to one year, set this parameter to 31536000.
            int maxVersions = 3; // The maximum number of versions to save. A value of 3 indicates that each column contains only the three latest versions.
            TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
            CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions);
            request.setReservedThroughput(new ReservedThroughput(new CapacityUnit(0, 0))); // Set the reserved read/write throughout. You can set the value only to 0 for capacity instances. However, you can set a non-zero value for high-performance instances.
            client.createTable(request);
        }
  • Create a base table and its index table
       private static void createTable(SyncClient client) {
            TableMeta tableMeta = new TableMeta(TABLE_NAME);
            tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema(PRIMARY_KEY_NAME_1, PrimaryKeyType.STRING)); // Specify a primary key column to the base table.
            tableMeta.addPrimaryKeyColumn(new PrimaryKeySchema(PRIMARY_KEY_NAME_2, PrimaryKeyType.INTEGER)); // Specify a primary key column to the base table.
            tableMeta.addDefinedColumn(new DefinedColumnSchema(DEFINED_COL_NAME_1, DefinedColumnType.STRING)); // Specify a predefined attribute column to the base table.
            tableMeta.addDefinedColumn(new DefinedColumnSchema(DEFINED_COL_NAME_2, DefinedColumnType.INTEGER)); // You can add a predefined attribute column to the base table.
    
            int timeToLive = -1; // Specify the validity period of data in seconds. A value of -1 indicates that the data never expires. You must specify -1 as the TTL value when a table has one or more index tables.
            int maxVersions = 1; // The maximum number of versions. You must specify 1 as the value when a table has one or more index tables.
    
            TableOptions tableOptions = new TableOptions(timeToLive, maxVersions);
    
            ArrayList<IndexMeta> indexMetas = new ArrayList<IndexMeta>();
            IndexMeta indexMeta = new IndexMeta(INDEX_NAME);
            indexMeta.addPrimaryKeyColumn(DEFINED_COL_NAME_1); // Add a primary key column to the index table.
            indexMeta.addDefinedColumn(DEFINED_COL_NAME_2); // Add an attribute column to the index table.
            indexMetas.Add(indexMeta);
    
            CreateTableRequest request = new CreateTableRequest(tableMeta, tableOptions, indexMetas); // Create a base table and its index table.
    
            client.createTable(request);
        }