Use Tablestore SDK for Python to create a data table - Tablestore

This topic describes how to use Tablestore SDK for Python to create a data table by using parameters and sample code. When you create a data table, you must specify the schema information and configuration information about the data table. You can specify the reserved read and write throughput for a data table in a high-performance instance.

Usage notes

After you create a data table, a few seconds are required to load the data table. During this period, all read and write operations on the data table fail. Perform operations on the data table after the data table is loaded.
In scenarios that require an auto-increment primary key column, such as item IDs on e-commerce websites and post IDs in forums, you can specify an auto-increment primary key column when you create a data table. For more information, see Configure an auto-increment primary key column.

Prerequisites

A Tablestore instance is created in the Tablestore console. For more information, see Create an instance.
An OTSClient instance is initialized. For more information, see Initialize an OTSClient instance.

API operation

"""
Description: Create a data table based on the specified table schema. 
After you create a data table, several seconds are required to load the partitions in the data table. You can perform operations on the data table only after the partitions are loaded. 
Return value: none. 
"""
def create_table(self, table_meta, table_options, reserved_throughput, secondary_indexes=[])

Parameters

Parameter	Description
table_meta (required)	The schema information about the data table. You can configure the following parameters to specify the schema information: table_name: This parameter is required and specifies the name of the data table. schema_of_primary_key: This parameter is required and specifies the schema of the primary key for the data table. For more information, see Core components. The type of a primary key column can be String, Integer, or Binary. You can specify one to four primary key columns. Tablestore generates the primary key in the order in which the primary key columns are specified. By default, the rows in a data table are sorted in descending order by primary key. The first primary key column is the partition key. defined_columns: This parameter is optional and specifies the predefined columns of the data table. The type of a predefined column can be String, Integer, Binary, Double, or Boolean. Note Predefined columns are non-primary key columns that can be used as primary key columns or predefined columns of a secondary index that is created for the data table to accelerate data queries. You do not need to specify the schema of attribute columns when you create a data table. You can specify different numbers of attribute columns and different attribute column names for each row when you write data to a data table.
table_options (required)	The configuration information about the data table. You can configure the following parameters to specify the configuration information: time_to_live: This parameter is optional and specifies the retention period of data in the data table. Unit: seconds. If the retention period of data exceeds the value of the time_to_live parameter, the data expires. Tablestore automatically deletes the expired data. Default value: -1. A value of -1 specifies that data in the data table never expires. You can set this parameter to a value that is greater than or equal to 86400 or -1. A value of 86400 specifies one day. Important If you want to create a search index or secondary index for the data table, you must set this parameter to -1 or set the allow_update parameter to false. max_version: This parameter is optional and specifies the maximum number of versions that can be retained for the data in each attribute column. Default value: 1. A value of 1 specifies that only the latest version of data is retained for each attribute column. Important If you want to create a search index or secondary index for the data table, you must set this parameter to 1. max_time_deviation: This parameter is optional and specifies the maximum difference between the current system time and the timestamp of the written data. Unit: seconds. Default value: 86400. The valid version range of data in an attribute column is a left-closed, right-open interval, which is calculated by using the following formula: Valid version range = `[max{Data write time - Max version offset, Data write time - TTL value}, Data write time + Max version offset)`. allow_update: This parameter is optional and specifies whether to allow update operations on the data table. Default value: true. Important If you want to use the time to live (TTL) feature of the search index that is created for the data table, you must set this parameter to false. If you want to update data in the data table, you can call the PutRow operation to write data to the data table.
secondary_indexes (optional)	The list of indexes. You can configure the following parameters for each index: index_name: This parameter is required and specifies the name of the index. primary_key_names: This parameter is required and specifies 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 for which the index is created. Important 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: This parameter is optional and specifies the predefined columns of the index. The predefined columns of an index are a combination of predefined columns of the data table for which the index is created. index_type: This parameter is optional and specifies the type of the index. Valid values: GLOBAL_INDEX: global secondary index. This is the default value. LOCAL_INDEX: local secondary index.
reserved_throughput (required)	The reserved read and write throughput. Unit: capacity unit (CU). Default value: 0. Important You can set the reserved read or write throughput to a value other than 0 only for a data table in a high-performance instance.

Examples

Create a data table

The following sample code provides an example on how to create a data table:

# Create a schema for the primary key columns of the data table, including the number, names, and types of the primary key columns. 
# The first primary key column is named pk0 and is of the Integer type. The first primary key column is the partition key. 
# The second primary key column is named pk1 and is of the Integer type. In this example, the data type is set to Integer. You can also set the data type to String or Binary. 
schema_of_primary_key = [('pk0', 'INTEGER'), ('pk1', 'INTEGER')]

# Create a tableMeta instance based on the name of the data table and the schema of the primary key columns. 
table_meta = TableMeta('<table_name>', schema_of_primary_key)

# Create a TableOptions instance. Set the time_to_live parameter to 31536000 to automatically delete expired data. Then, set the max_version parameter to 3 and the max_time_deviation parameter to 86400 (one day). 
table_options = TableOptions(31536000, 3, 86400)

# Set the reserved read throughput and reserved write throughput to 0. 
reserved_throughput = ReservedThroughput(CapacityUnit(0, 0))

# Call the create_table operation of the client. If no exception is thrown, the data table is created. 
try:
    ots_client.create_table(table_meta, table_options, reserved_throughput)
    print("create table succeeded.")
# If an exception is thrown, the data table fails to be created. Handle the exception. 
except Exception:
    print("create table failed.")

Create a data table and a secondary index

Create a data table and a global secondary index

The following sample code provides an example on how to create a data table and a global secondary index for the data table at the same time:

# Create a schema for the primary key columns of the data table, including the number, names, and types of the primary key columns. 
schema_of_primary_key = [('gid', 'INTEGER'), ('uid', 'STRING')]

# Specify the predefined columns of the data table. 
defined_columns = [('i', 'INTEGER'), ('bool', 'BOOLEAN'), ('d', 'DOUBLE'), ('s', 'STRING'), ('b', 'BINARY')]

# Create a tableMeta instance based on the name of the data table and the schema of the primary key columns. 
table_meta = TableMeta('<table_name>', schema_of_primary_key, defined_columns)

# Create a TableOptions instance. Set the time_to_live parameter to -1, which specifies that the data does not expire. Then, set the max_version parameter to 1. 
table_option = TableOptions(-1, 1)

# Set the reserved read throughput and reserved write throughput to 0. 
reserved_throughput = ReservedThroughput(CapacityUnit(0, 0))

# Specify the name, primary key columns, and attribute columns of the secondary index. By default, a global secondary index is created. 
secondary_indexes = [
    SecondaryIndexMeta('index1', ['i', 's'], ['bool', 'b', 'd']),
]

# Call the create_table operation of the client. If no exception is thrown, the data table is created. 
ots_client.create_table(table_meta, table_option, reserved_throughput, secondary_indexes)

Create a data table and a local secondary index

The following sample code provides an example on how to create a data table and a local secondary index for the data table at the same time:

# Create a schema for the primary key columns of the data table, including the number, names, and types of the primary key columns. 
schema_of_primary_key = [('gid', 'INTEGER'), ('uid', 'STRING')]

# Specify the predefined columns of the data table. 
defined_columns = [('i', 'INTEGER'), ('bool', 'BOOLEAN'), ('d', 'DOUBLE'), ('s', 'STRING'), ('b', 'BINARY')]

# Create a tableMeta instance based on the name of the data table and the schema of the primary key columns. 
table_meta = TableMeta('<table_name>', schema_of_primary_key, defined_columns)

# Create a TableOptions instance. Set the time_to_live parameter to -1, which specifies that the data does not expire. Then, set the max_version parameter to 1. 
table_option = TableOptions(-1, 1)

# Set the reserved read throughput and reserved write throughput to 0. 
reserved_throughput = ReservedThroughput(CapacityUnit(0, 0))

# Specify the name, primary key columns, index columns, and index type of the secondary index. Set the index_type parameter to LOCAL_INDEX, which specifies that a local secondary index is created. 
secondary_indexes = [
    SecondaryIndexMeta('index1', ['gid', 's'], ['bool', 'b', 'd'],index_type= SecondaryIndexType.LOCAL_INDEX),
]

# Call the create_table operation of the client. If no exception is thrown, the data table is created. 
ots_client.create_table(table_meta, table_option, reserved_throughput, secondary_indexes)

References

For information about the API operation that you can call to create a data table, see CreateTable.
For information about data versions and time to live (TTL), secondary indexes, and reserved read and write throughput, see Data versions and TTL, Overview, and What is reserved read and write throughput?.
After you create a data table, you can perform the following operations:
- Operations on the table. For more information, see Operations on tables.
- Operations on data. For more information, see Basic operations on data.