All Products
Search
Document Center

Tablestore:Create a data table

Last Updated:Jul 07, 2025

This topic describes how to create a Tablestore data table by using Tablestore SDK for Python.

Usage notes

After you create a data table, wait until the data table is loaded before you perform operations on the data. Otherwise, the operations will fail. This process typically takes several seconds.

Prerequisites

A client is initialized. For more information, see Initialize a Tablestore client.

Method description

def create_table(self, table_meta, table_options, reserved_throughput, secondary_indexes=[])

Parameters

  • table_meta (required) TableMeta: the schema information of the table, including the following parameters.

    Parameter

    Type

    Description

    table_name (required)

    str

    The name of the data table.

    schema_of_primary_key (required)

    List[Tuple]

    The information about the primary key.

    • You can configure 1 to 4 primary key columns. By default, the columns are sorted in ascending order. The first primary key column serves as the partition key.

    • The data types of primary key columns include STRING, INTEGER, and BINARY. You can set the auto-increment primary key column to a primary key column that is not the parition key and whose type is INTEGER.

    defined_columns (optional)

    List[Tuple]

    The information about predefined columns.

    • Predefined columns are attribute columns that are predefined and can be used to create secondary indexes and search indexes.

    • The data types of predefined columns include STRING, INTEGER, BINARY, DOUBLE, and BOOLEAN.

  • table_options (required) TableOptions: the configuration information of the table, including the following parameters.

    Parameter

    Type

    Description

    time_to_live (optional)

    int

    The time to live (TTL) of data, in seconds. The default value is -1.

    • If you set this parameter to -1, the data never expires. Otherwise, the minimum value is 86400 (one day). Data whose retention period exceeds the TTL will be automatically deleted.

    • If you want to use search indexes or secondary indexes, you must set this parameter to -1 or set the allow_update parameter to False.

    max_version (optional)

    int

    The maximum number of versions. The default value is 1.

    • If you want to use search indexes or secondary indexes, you must set this parameter to 1.

    max_time_deviation (optional)

    int

    The maximum version offset, in seconds. The default value is 86400 (one day).

    • The difference between the current system time and the timestamp of written data must be within the maximum version offset range. Otherwise, the data write will fail.

    • The valid version range for attribute column data is [max(Data written time - Maximum version offset, Data written time - TTL), Data written time + Maximum version offset).

    allow_update (optional)

    bool

    Specifies whether to allow updates. The default value is True.

    • If you set this parameter to False, you cannot update data by using the update_row() method.

  • secondary_indexes (optional) List[SecondaryIndexMeta]: the list of secondary indexes. Each index includes the following parameters.

    Parameter

    Type

    Description

    index_name (required)

    str

    The name of the index.

    primary_key_names (required)

    List[str]

    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.

    • 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.

    defined_column_names (optional)

    List[str]

    The predefined columns of the index.

    • The predefined columns are from the predefined columns of the data table.

    index_type (optional)

    SecondaryIndexType

    The type of the index. Valid values:

    • GLOBAL_INDEX (default value): global secondary index.

    • LOCAL_INDEX: local secondary index.

  • reserved_throughput (required) ReservedThroughput: the reserved read and write throughput, in CU. The default value is 0. You can set this parameter to a non-zero value and the settings take effect only for data tables in high-performance instances in CU mode.

Sample code

The following sample code creates a table named test_table that contains one primary key column of the String type.

# Creating a data table requires at least one primary key column.
schema_of_primary_key = [('id', 'STRING')]
# Construct the schema information of the data table.
table_meta = TableMeta('test_table', schema_of_primary_key)

# Construct the configuration information of the data table.
table_options = TableOptions(time_to_live=-1, max_version=1, max_time_deviation=86400, allow_update=True)

# When you create a data table, you must specify the reserved read and write throughput, with a default value of 0 (you can set this parameter to a non-zero value and the settings take effect only for data tables in high-performance instances in CU mode).
reserved_throughput = ReservedThroughput(CapacityUnit(0,0))

try:
    # Initiate a request.
    client.create_table(table_meta, table_options, reserved_throughput)
    print("Create table succeeded.")
except Exception as e:
    print("Create table failed. %s" % e)

You can also refer to the following sample code to configure specific settings when you create a data table.

  • Add predefined columns

    defined_columns = [('name', 'STRING')]
    # Construct the schema information of the data table.
    table_meta = TableMeta('test_table', schema_of_primary_key, defined_columns)
  • Add secondary indexes

    # Construct the secondary index list.
    secondary_indexes = [
        # Specify the index name, index primary key columns, index predefined columns, and index type.
        SecondaryIndexMeta('test_table_index', ['id', 'name'], [], index_type= SecondaryIndexType.LOCAL_INDEX)
    ]
    # Initiate a request.
    client.create_table(table_meta, table_options, reserved_throughput, secondary_indexes)

References