Create a table - Tablestore SDK for Python - Tablestore - Alibaba Cloud Documentation Center

Use Tablestore SDK for Python to create a table and optionally configure its schema, settings, secondary indexes, and data encryption.

Prerequisites

Install the Tablestore SDK for Python and initialize a client.

Function description

Call the create_table method to create a table.

def create_table(
    self,
    table_meta,
    table_options,
    reserved_throughput,
    secondary_indexes=None,
    sse_spec=None,
)

The following example creates the example_table table with id as its primary key column. Data in the table never expires, and only one version is retained for each attribute column.

table_meta = TableMeta(
    "example_table",
    [("id", "STRING")],
)
table_options = TableOptions(
    time_to_live=-1,
    max_version=1,
    max_time_deviation=86400,
    allow_update=True,
)
reserved_throughput = ReservedThroughput(CapacityUnit(0, 0))

client.create_table(table_meta, table_options, reserved_throughput)

Note

After you create a table, wait a few seconds for the table to load before you perform data operations.

Parameters

The create_table method contains the following parameters.

Name	Type	Description
table_meta (required)	`TableMeta`	The table schema.
table_options (required)	`TableOptions`	The table configurations.
reserved_throughput (required)	`ReservedThroughput`	The reserved throughput.
secondary_indexes (optional)	`List[SecondaryIndexMeta]`	The secondary indexes to create together with the table.
sse_spec (optional)	`SSESpecification`	The server-side encryption settings. Encryption can be enabled only when the table is created and cannot be disabled afterward. This feature requires Tablestore SDK for Python 6.4.0 or later.

Table schema

The table_meta parameter is of the TableMeta type and contains the following parameters.

Name	Type	Description
table_name (required)	`str`	The name of the table.
schema_of_primary_key (required)	`List[Tuple]`	The primary key schema. A table can have one to four primary key columns. The first primary key column is the partition key, and primary key columns are sorted in ascending order. Primary key columns support the `STRING`, `INTEGER`, and `BINARY` types. A non-partition primary key column of the `INTEGER` type can be configured as an auto-increment primary key column.
defined_columns (optional)	`List[Tuple]`	The predefined columns. Predefined columns support the `STRING`, `INTEGER`, `BINARY`, `DOUBLE`, and `BOOLEAN` types and can be used to create secondary indexes and search indexes.

Primary key column

Each tuple in table_meta.schema_of_primary_key[] configures one primary key column and contains the following elements.

Name	Type	Description
name (required)	`str`	The name of the primary key column.
type (required)	`str`	The type of the primary key column. Valid values are `STRING`, `INTEGER`, and `BINARY`.
option (optional)	`PrimaryKeyOption`	The primary key option. Set a non-partition primary key column of the `INTEGER` type to `PK_AUTO_INCR` to make it an auto-increment primary key column.

Predefined column

Each tuple in table_meta.defined_columns[] configures one predefined column and contains the following elements.

Name	Type	Description
name (required)	`str`	The name of the predefined column.
type (required)	`str`	The type of the predefined column. Valid values are `STRING`, `INTEGER`, `BINARY`, `DOUBLE`, and `BOOLEAN`.

Table configurations

The table_options parameter is of the TableOptions type and contains the following parameters.

Name	Type	Description
time_to_live (optional)	`int`	The time to live (TTL) of data in seconds. The default value is `-1`, which indicates that data never expires. If you specify another value, the minimum value is `86400`, which is one day. Expired data is automatically deleted. To use a search index or secondary index, set this parameter to `-1` or set `allow_update` to `False`.
max_version (optional)	`int`	The maximum number of versions to retain for each attribute column. The default value is `1`. To use a search index or secondary index, set this parameter to `1`.
max_time_deviation (optional)	`int`	The maximum version deviation in seconds. The default value is `86400`, which is one day. The difference between the timestamp of the data to write and the current system time must be within the maximum version deviation. The valid version range is `[max(data write time - maximum version deviation, data write time - TTL), data write time + maximum version deviation)`.
allow_update (optional)	`bool`	Specifies whether data can be updated by calling `update_row`. If you do not specify this parameter, the server allows updates by default. If you set this parameter to `False`, data cannot be updated by calling `update_row`.

Reserved throughput

The reserved_throughput parameter is of the ReservedThroughput type and contains the following parameter.

Name	Type	Description
capacity_unit (required)	`CapacityUnit`	The reserved throughput in capacity units (CUs). The default read and write CUs are both `0`. Only high-performance instances in CU mode support nonzero values.

Capacity units

The reserved_throughput.capacity_unit parameter is of the CapacityUnit type and contains the following parameters.

Name	Type	Description
read (optional)	`int`	The reserved read throughput in CUs. The default value is `0`.
write (optional)	`int`	The reserved write throughput in CUs. The default value is `0`.

Secondary index

Each element in secondary_indexes[] is of the SecondaryIndexMeta type and contains the following parameters.

Name	Type	Description
index_name (required)	`str`	The name of the index.
primary_key_names (required)	`List[str]`	The primary key columns of the index. You can use primary key columns and predefined columns of the table. For a local secondary index, the first primary key column of the index must be the same as that of the table.
defined_column_names (optional)	`List[str]`	The predefined columns included in the index. The columns must already be defined in the table.
index_type (optional)	`SecondaryIndexType`	The index type. Valid values are `GLOBAL_INDEX`, the default value for a global secondary index, and `LOCAL_INDEX`, for a local secondary index.

Server-side encryption settings

The sse_spec parameter is of the SSESpecification type and contains the following parameters.

Name	Type	Description
enable (optional)	`bool`	Specifies whether to enable data encryption. The default value is `False`.
key_type (optional)	`SSEKeyType`	The encryption type. Valid values are `SSE_KMS_SERVICE` for KMS-managed key encryption and `SSE_BYOK` for bring-your-own-key (BYOK) encryption. This parameter is required when encryption is enabled.
key_id (optional)	`str`	The customer master key ID. This parameter is required for BYOK encryption.
role_arn (optional)	`str`	The Alibaba Cloud Resource Name (ARN) of the RAM role. This parameter is required for BYOK encryption.

Examples

Configure the table schema and data versions

The following example adds the predefined column name and retains up to three versions for each attribute column.

table_meta = TableMeta(
    "example_table",
    [("id", "STRING")],
    [("name", "STRING")],
)
table_options = TableOptions(
    time_to_live=-1,
    max_version=3,
    max_time_deviation=86400,
    allow_update=True,
)
reserved_throughput = ReservedThroughput(CapacityUnit(0, 0))

client.create_table(table_meta, table_options, reserved_throughput)

Create a secondary index together with a table

The following example creates a local secondary index together with a table. The first primary key column of both the table and the secondary index is id.

table_meta = TableMeta(
    "example_table",
    [("id", "STRING"), ("device_id", "INTEGER")],
    [("status", "STRING")],
)
table_options = TableOptions(time_to_live=-1, max_version=1)
reserved_throughput = ReservedThroughput(CapacityUnit(0, 0))
secondary_indexes = [
    SecondaryIndexMeta(
        "example_local_index",
        ["id", "device_id"],
        ["status"],
        index_type=SecondaryIndexType.LOCAL_INDEX,
    )
]

client.create_table(
    table_meta,
    table_options,
    reserved_throughput,
    secondary_indexes=secondary_indexes,
)

Encrypt a table

The following examples use a KMS-managed key and a customer-managed key to encrypt a table.

Important

Encryption can be enabled only when the table is created and cannot be disabled afterward.

KMS-managed key

sse_spec = SSESpecification(
    enable=True,
    key_type=SSEKeyType.SSE_KMS_SERVICE,
)

client.create_table(
    table_meta,
    table_options,
    reserved_throughput,
    sse_spec=sse_spec,
)

BYOK encryption

Before you use BYOK encryption, obtain the customer master key ID and RAM role ARN. For more information, see Data encryption.

sse_spec = SSESpecification(
    enable=True,
    key_type=SSEKeyType.SSE_BYOK,
    key_id="key-example",
    role_arn="acs:ram::1234567890123456:role/example-role",
)

client.create_table(
    table_meta,
    table_options,
    reserved_throughput,
    sse_spec=sse_spec,
)