This topic describes how to create a Tablestore data table 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.
Method description
def create_table(self, table_meta, table_options, reserved_throughput, secondary_indexes=[], sse_spec)
Parameters
table_meta (required) TableMeta: the schema information of the table, including the following parameters.
Name | 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.
Name | 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. |
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. |
secondary_indexes (optional) List[SecondaryIndexMeta]: the list of secondary indexes. Each index includes 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. It can consist of a data table's primary key column and predefined columns. 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. |
index_type (optional) | SecondaryIndexType | The type of the index. Valid values: |
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.
sse_spec (optional) SSESpecification: the data encryption settings, including the following parameters.
Important You can enable and configure data encryption only when you create a data table. After the table is created, you cannot disable encryption. This feature is supported only in Python SDK version 6.4.0 and later.
Name | Type | Description |
enable (required) | boolean | Specifies whether to enable data encryption. The default value is False. |
key_type (optional) | SSEKeyType | The encryption type. Valid values of SSEKeyType: |
key_id (optional) | str | The ID of the customer master key (CMK). Specify this parameter only when key_type is SSE_BYOK. |
role_arn (optional) | str | The ARN of the RAM role. Specify this parameter only when key_type is SSE_BYOK. |
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)
Configure data encryption
Use the SSESpecification method to configure data encryption for the data table.
KMS secret key encryption
sse_specification = SSESpecification(enable=True, key_type=SSEKeyType.SSE_KMS_SERVICE, key_id=None,
role_arn=None)
client.create_table(table_meta, table_option, reserved_throughput, sse_spec=sse_specification)
BYOK encryption
Note Before you run the code, obtain the CMK ID and the ARN of the RAM role. For more information, see BYOK encryption.
key_id = "key-hzz6*****************"
role_arn = "acs:ram::1705************:role/tabletorebyok"
sse_specification = SSESpecification(enable=True, key_type=SSEKeyType.SSE_BYOK, key_id=key_id,
role_arn=role_arn)
client.create_table(table_meta, table_option, reserved_throughput, sse_spec=sse_specification)