Tablestore:Data table operations

Usage notes

• You can create a maximum of 64 data tables in a single instance.

• A data table is not immediately available for read and write operations upon creation. In most cases, you can access a new table about one minute later.

• The auto-increment primary key column feature and the local transaction feature cannot be used at the same time. If you configure an auto-increment primary key column when you create a data table, the local transaction feature does not take effect even if it is enabled.

Features

• Create a data table

  When you create a data table, you must specify its schema information and configuration information.

  • The schema information of a data table includes the table name, primary key definition, and predefined column configurations.

  • You can configure the data table based on your business requirements. The following table describes the configuration parameters.

    Parameter	Description
    Auto-increment primary key column	When you create a data table, you can set a primary key column that is not a partition key as an auto-increment primary key column. When you write data to the table, you do not need to specify a value for this column; Tablestore automatically generates one.
    Data versions and TTL	You can use data versions and the time to live (TTL) feature to efficiently manage data, which helps reduce storage usage and lower storage costs.
    Allow updates	By default, you can write data to a data table by calling the UpdateRow API operation. You can change this setting after the table is created. Important If you plan to use the time to live (TTL) feature for a search index, you must prohibit writes that use the UpdateRow API operation.
    Reserved read/write throughput	For High-performance instances that use the , you can configure reserved read/write throughput for a data table based on your requirements.
    Secondary index	Tablestore provides local secondary indexes and global secondary indexes to meet query requirements with different read consistency guarantees. You can create one or more secondary indexes when you create a data table. Note To use a secondary index, you must predefine one or more non-primary key columns and their data types in the data table. These columns can be used as index columns or included columns in the index. You can add or delete predefined columns after the table is created.
    Data encryption	Tablestore provides data encryption at rest to ensure data security. You can configure data encryption when you create a data table.
    Local transaction	After you enable local transactions for a data table, you can create a local transaction within a single partition key value and perform read and write operations on the data within that transaction. Important You can enable local transactions for a data table by using the Tablestore console or Tablestore SDK for Java 5.11.0 or later. If you did not enable local transactions when creating the table but need the feature later, submit a ticket to have it enabled.

• Update table configuration

  Modifies the configuration of a specified data table, such as time to live (TTL), max versions, max version offset, and Stream settings. You can also adjust the reserved read/write throughput for data tables in High-performance instances that use the.

• List table names

  Retrieves the names of all data tables in the current instance.

• Query table description

  Queries information about a specified data table, such as its schema and reserved read/write throughput details.

• Delete a data table

  Deletes a specified data table.

Create a data table

Perform the following steps to create a data table in the Tablestore console.

1. Go to the Instance Management page.

   1. Log on to the Tablestore console.

   2. In the top navigation bar, select a resource group and a region.

   3. On the Overview page, click the alias of an instance or click Instance Management in the Actions column of the instance.

2. On the Instance Details tab, click Create Table.

3. In the Create Table dialog box, configure the parameters as described in the following table.

   Parameter	Description
   Table name	The name of the data table, which must be unique within an instance. The name must be 1 to 255 bytes in length and can contain uppercase letters, lowercase letters, digits, and underscores (_). The name must start with a letter or an underscore (_).
   Primary key	One or more columns that uniquely identify a row in the table. Enter a primary key name, select a data type, and then click Add Primary Key Column to add another primary key column. You can define up to four primary key columns for a table. The first primary key column is the partition key. You cannot change the configuration or order of primary key columns after the table is created. Important Tablestore allows you to set one primary key column as an auto-increment primary key column. A table can have only one auto-increment primary key column, and the partition key cannot be an auto-increment column. If a primary key column is set to auto-increment, you do not need to specify its value when writing a row; Tablestore automatically generates a unique and strictly increasing value within the partition key. A primary key name must be 1 to 255 bytes in length and can contain uppercase letters, lowercase letters, digits, and underscores (_). The name must start with a letter or an underscore (_). The data type of a primary key can be STRING, INTEGER, or BINARY.
   Allow updates	Specifies whether to allow data to be written by calling the UpdateRow API operation. If this parameter is not set or is set to Yes, data can be written by calling UpdateRow. To use the time to live (TTL) feature of a search index, you must set this parameter to No. This prohibits writes that use the UpdateRow API operation.
   Encryption	Specifies whether to enable data encryption at rest. By default, this feature is disabled. To enable this feature, turn on the Encryption switch. Important Data encryption at rest cannot be disabled after it is enabled. Proceed with caution.
   Encryption type	The type of data encryption. This parameter is required only if you turn on the Encryption switch. Valid values: CMK of KMS: Tablestore BYOK-based Key: Tablestore Important Before you use the BYOK option, you must create a software key in the KMS console, and then create a custom role and configure its permissions. For more information, see Data encryption.
   Key ID	The ID of the key. This parameter is required only if Encryption Type is set to BYOK-based Key.
   Role ARN	The Alibaba Cloud Resource Name (ARN) of the role. This parameter is required only if Encryption Type is set to BYOK-based Key.

4. (Optional) In the Create Table dialog box, configure advanced settings or create a secondary index.

   Perform this step if you need to configure advanced settings for the data table, such as time to live (TTL), or create a secondary index.

   Advanced parameters

   To manage the retention period of data in the table, specify a time to live (TTL). To keep multiple versions of data for the same primary key, specify the maximum number of versions. For more information, see Data versions and TTL.

   For High-performance instances in CU mode, you can specify reserved read or write throughput for the data table to reduce costs. For more information, see Reserved read/write throughput.

   1. Turn on the Advanced Settings switch.

   2. Configure the advanced parameters as described in the following table.

      Parameter	Description
      Time to live	The data retention period, in seconds. When data exceeds this period, the system automatically deletes the expired data. The value must be an integer greater than or equal to 86400 (one day), or -1. A value of -1 specifies that the data never expires.
      Max versions	The maximum number of versions that can be retained for each attribute column. If the number of versions of data in an attribute column exceeds this value, the system automatically deletes older versions. The value must be a non-zero integer.
      Max version offset	The maximum allowed deviation between a specified data version and the current system time, in seconds. This value must be a positive integer. A write operation succeeds only if the version specified for each column is within the allowed offset from the write time. The valid version range for an attribute column is [max{WriteTime - MaxVersionOffset, WriteTime - TTL}, WriteTime + MaxVersionOffset).
      Reserved read throughput	This parameter is supported only for High-performance instances that use the . The reserved read or write throughput for the data table. The value must be an integer from 0 to 100,000. The unit is capacity unit (CU). If you set Reserved Read Throughput or Reserved Write Throughput to a value greater than 0, Tablestore allocates and reserves the corresponding resources for the data table. After the table is created, billing for the reserved throughput starts immediately. If you set Reserved Read Throughput or Reserved Write Throughput to 0, Tablestore does not allocate or reserve resources for the data table.
      Reserved write throughput
      Enable local transaction	The local transaction feature is disabled by default. To perform atomic read and write operations on one or more rows within the same partition, turn on the Enable Local Transaction switch.
      Enable row version support	Row version support is disabled by default. To use a global table, you must turn on the Enable Row Versioning switch. You cannot disable this setting after it is enabled. The following limitations apply when row version support is enabled: A single row can have a maximum of 256 columns. You cannot manually specify version numbers when you write data. Version numbers are automatically generated by the system. When you perform an update operation, the system must first read the current row version, which introduces a small amount of additional read load.
      Quick set for global table	When you use a global table, turn on the Quick Set Global Table Dependency switch. The system automatically modifies the related configurations for the global table. The configuration changes are as follows: Time To Live: -1 Max Versions: 1 Max Version Offset: 2147483647 Enable Row Version Support: Enabled

   Configure a secondary index

   When an application needs to query data based on different attributes, you can use these attributes as the primary key columns of a secondary index to enable fast queries. For more information, see secondary index.

   1. Turn on the Create a secondary index switch.

   2. Click Add, and then enter a name and select a data type for the predefined column.

      The name of a predefined column must be 1 to 255 bytes in length and can contain uppercase letters, lowercase letters, digits, and underscores (_). It must start with a letter or an underscore (_).

      The data type for a predefined column can be STRING, INTEGER, BINARY, FLOAT, or BOOLEAN.

   3. Click Add Secondary Index, enter an index name, select the index primary key, and optionally select predefined columns and an index type.

      Important

      The index name cannot be the same as the data table name. Both the index name and the data table name must be unique within the instance.

      An index name must be 1 to 255 bytes in length and can contain uppercase letters, lowercase letters, digits, and underscores (_). It must start with a letter or an underscore (_).

      • The Primary Key can consist of the data table's primary key columns and predefined columns. You can select multiple columns. The Pre-defined Column can be selected only from the data table's predefined columns. You can select multiple columns, but they cannot be the same as any of the index primary key columns.

      • The Index Type can be Global or Local.

        Important

        The first primary key column of a global secondary index can be any primary key column or predefined column. The first primary key column of a local secondary index must be the same as the first primary key column of the data table.

        A global secondary index asynchronously synchronizes data from the indexed columns and primary key columns of the data table to the index table. Synchronization latency is typically in the millisecond range. A local secondary index synchronously synchronizes data from the indexed columns and primary key columns of the data table to the index table. After data is written to the data table, it is immediately available for queries from the index table.

5. Click Create.

Manage data tables

Perform the following operations to manage your data tables as required.

Development and integration

You can use the following SDKs or the Tablestore CLI to perform data table operations.