Operations on data tables

Usage notes

• You can create up to 64 data tables in an instance.

• After you create a data table, you cannot immediately perform read and write operations on the data table. In most cases, you can perform read and write operations on a data table about 1 minute after the data table is created.

• 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 when you create a data table, the local transaction settings do not take effect.

Features

• Create a data table

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

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

  • You can specify the configuration information about a data table based on your business requirements. The following table describes the configuration items.

    Configuration item	Description

    Configuration item	Description
    Configure an auto-increment primary key column	When you create a data table, you can set a primary key column that is not the partition key to an auto-increment primary key column. When you write data to a data table that contains an auto-increment primary key column, Tablestore automatically generates values for the auto-increment primary key column.
    Data versions and TTL	You can use data versions and time to live (TTL) to manage data in an efficient manner and minimize storage usage and storage costs.
    Allow Updates	By default, you can call the UpdateRow operation to update the data in a data table. You can also set the Allow Updates parameter to No for a data table after you create the data table. Important However, if you want to use the TTL feature of a search index that is created for the data table, you must prohibit the UpdateRow operation on the data table.
    Reserved read and write throughput	You can specify the reserved read throughput or reserved write throughput for a data table if the data table resides in a high-performance instance.
    Secondary index	Tablestore provides the local secondary index and global secondary index features to meet different requirements on read consistency during data queries. You can create one or more secondary indexes when you create a data table. Note When you create a data table, you can define some columns that are not primary key columns and their data types. When you use the secondary index feature, you can use the predefined columns as the index columns or attribute columns of an index table. You can also add or remove predefined columns after the data table is created.
    Data encryption	Tablestore provides the data encryption feature to encrypt data when the data is written to a data table. This ensures the security of table data. When you create a data table, you can configure table encryption.
    Local transactions	After you enable the local transaction feature for a data table, you can create a local transaction based on a specific partition key value and perform read and write operations on data within the local transaction. Important Only Tablestore SDK for Java V5.11.0 and later support the local transaction feature. If you do not enable the local transaction feature when you create a data table, you must submit a ticket to apply for the use of the feature.

• Update the configurations of a table

  You can update the TTL, max versions, max version offset, and Stream configurations of a data table. You can also update the reserved read and write throughput of a data table in a high-performance instance.

• Query the names of tables

  You can query the names of all data tables in an instance.

• Query information about a table

  You can query the schema, reserved read throughput, and reserved write throughput of a data table.

• Delete a data table

  You can delete a data table.

Create a data table

To create a data table in the Tablestore console, perform the following steps:

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 name of the instance that you want to manage or click Manage Instance 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. The following table describes the parameters.

   Parameter	Description

   Parameter	Description
   Table Name	The name of the data table, which is used to identify a data table in an instance. The name must be 1 to 255 bytes in length and can contain letters, digits, and underscores (_). The name must start with a letter or an underscore (_).
   Primary Key	The primary key column. All primary key columns are used to identify a record in a table. Enter a name for the primary key column and select a data type. Click Add Primary Key Column to add a primary key column. You can add one to four primary key columns. The first primary key column is the partition key. After you create a data table, you cannot modify the configurations and order of the primary key columns. Important In Tablestore, only one primary key column can be specified as an auto-increment primary key column for each data table. You cannot specify a partition key as an auto-increment primary key column. After you specify a primary key column as an auto-increment primary key column, Tablestore automatically generates a value for the auto-increment primary key column when you write a row of data. The values of auto-increment primary key columns are incremental and unique within the rows that share the same partition key. Naming conventions for primary key columns: The name must be 1 to 255 bytes in length and can contain letters, digits, and underscores (_). The name must start with a letter or an underscore (_). The STRING, INTEGER, and BINARY data types are supported for primary key columns.
   Allow Updates	Specifies whether to allow the UpdateRow operation. The default value is Yes, which specifies that the UpdateRow operation is allowed. If you want to use the TTL feature of search indexes that are created for the data table, you must set this parameter to No. For more information, see Specify the TTL of a search index.
   Encryption	Specifies whether to enable data encryption. By default, this feature is disabled. You can enable this feature by turning on Encryption. Important After the feature is enabled, the feature cannot be disabled. Proceed with caution.
   Encryption Type	The encryption type of data. This parameter is required only if you turn on Encryption. Valid values: CMK of KMS: Tablestore automatically creates a customer master key (CMK) in Key Management Service (KMS) to encrypt and decrypt data. BYOK-based Key: Tablestore encrypts and decrypts data based on the Bring Your Own Key (BYOK)-based key. Important Before you use BYOK-based encryption, you must create a software-protected key in the KMS console, create a Resource Access Management (RAM) role, and then grant permissions to the RAM role. For more information, see BYOK-based encryption.
   Key ID	The ID of the key. This parameter is required only if you set the Encryption Type parameter to BYOK-based Key.
   ARN	The Alibaba Cloud Resource Name (ARN) of the RAM role. This parameter is required only if you set the Encryption Type parameter to BYOK-based Key.

4. (Optional) In the Create Table dialog box, turn on Advanced Settings or Create Secondary Index.

   To configure advanced settings such as TTL, turn on Advanced Settings. To create a secondary index, turn on Create Secondary Index.

   Configure advanced settings

   Configure a secondary index

   To manage the retention period of data in a data table, you can specify the Time to Live parameter. To manage multiple versions of data that has the same primary key value, you can specify the Max Versions parameter. For more information, see Data versions and TTL.

   To reduce the costs of a high-performance instance in CU mode, you can specify the reserved read and write throughput for data tables. For more information, see Reserved read and write throughput.

   1. Turn on Advanced Settings.

   2. Configure the advanced parameters. The following table describes the parameters.

      Parameter	Description
      Time To Live	The retention period of data in the data table. If the retention period exceeds the TTL value, Tablestore automatically deletes expired data. Unit: seconds. The minimum value is 86,400 seconds, which is one day. A value of -1 specifies that the data never expires.
      Max Versions	The maximum number of versions that can be retained for data in each attribute column of the data table. If the number of versions of data in an attribute column exceeds the value of this parameter, the system deletes the data of earlier versions. The value of this parameter must be a positive integer.
      Valid Version Offset	The maximum difference between the current system time and the specified data version. Unit: seconds. The value of the Max Version Offset parameter is a positive integer that can be greater than the number of seconds that have elapsed since January 1, 1970, 00:00:00 UTC. The difference between the version number and the time at which the data is written must be no more than the value of the Max Version Offset 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).
      Reserved Read Throughput	The two parameters are not supported for capacity instances. The reserved read or write throughput for the data table. The value is of the INTEGER type. Valid values: 0 to 100000. Unit: capacity unit (CU). If you set the Reserved Read Throughput or Reserved Write Throughput parameter to a value greater than 0, Tablestore allocates and reserves related resources for the data table. After you create the data table, you are charged for the reserved throughput resources. If you set the Reserved Read Throughput or Reserved Write Throughput parameter to 0, Tablestore does not allocate or reserve related resources for the data table.
      Reserved Write Throughput

   If an application needs to use different attribute columns as query conditions to query data, you can specify these attribute columns as the primary key columns of a secondary index to speed up the query. For more information, see Secondary index.

   1. Turn on Create Secondary Index.

   2. Click the + Add button next to the Pre-defined Column field. Enter the name of the predefined column and select a data type from the drop-down list.

      Naming conventions for predefined columns: The name must be 1 to 255 bytes in length and can contain letters, digits, and underscores (_). The name must start with a letter or an underscore (_).

      Predefined columns support the STRING, INTEGER, BINARY, FLOAT, and BOOLEAN data types.

   3. Click Add Global Secondary Index. You must configure the Index Name and Primary Key parameters. You can configure the Pre-defined Column and Index Type parameters based on your business requirements.

      Important

      The index name must be different from the data table name. The index name and the data table name must be unique in the instance.

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

      • You can specify one or more primary key columns or predefined columns of the data table for the Primary Key parameter. You can specify one or more predefined columns of the data table for the Pre-defined Column parameter. However, you cannot specify the same predefined column as a primary key column and a predefined column of the secondary index.

      • You can set the Index Type parameter to Global or Local.

        Important

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

        When you use the global secondary index feature, Tablestore automatically synchronizes data from the indexed columns and primary key columns of a data table to the columns of an index table in asynchronous mode. The synchronization latency can be as low as milliseconds. When you use the local secondary index feature, Tablestore automatically synchronizes data from the indexed columns and primary key columns of a data table to the columns of an index table in synchronous mode. You can query data from the index table immediately after the data is written to the data table.

5. Click Create.

Manage data tables

You can perform operations to manage data tables based on your business requirements.

Development integration

The following table describes the operations that you can perform on data tables by using the Tablestore CLI and Tablestore SDKs.