This topic describes how to create a data table by calling the CreateTable operation. When you call the CreateTable operation to create a data table, you must specify the schema information and configuration information about the data table. You can also configure the reserved read throughput and reserved write throughout based on your business requirements if the data table belongs to a high-performance instance. You can create one or more index tables when you create a data table.
Usage notes
It takes several seconds to load a data table after the data table is created. 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.
You must specify the primary key when you create a data table. A primary key consists of one to four primary key columns. Specify a name and data type for each primary key column.
Tablestore provides the auto-increment primary key column feature. This feature applies to system design scenarios that require auto-increment primary key columns, such as item IDs on e-commerce websites, user IDs on large websites, post IDs in forums, and message IDs in chat tools. 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 instances.
An OTSClient instance is initialized. For more information, see Initialization.
API operation
"""
Description: You can call this operation to create a data table based on the specified table schema information.
table_meta is an instance of the tablestore.metadata.TableMeta class. table_meta specifies the name of the data table and the schema of the primary key.
For more information, see the documentation of the TableMeta class. After you create a data table, it takes several seconds to load the partitions in the data table. You can perform operations on the data table only after the partitions are loaded.
table_options is an instance of the tablestore.metadata.TableOptions class. table_options contains the time_to_live, max_version, and max_time_deviation parameters.
reserved_throughput is an instance of the tablestore.metadata.ReservedThroughput class. reserved_throughput specifies the reserved read throughput and reserved write throughput.
secondary_indexes is an array that can contain one or more instances of the tablestore.metadata.SecondaryIndexMeta class. secondary_indexes specifies the global secondary index that you want to create.
Return value: none.
"""
def create_table(self, table_meta, table_options, reserved_throughput, secondary_indexes=[]):
Parameters
Configure the parameters in the code based on the parameter description in the following table and the "Request syntax" section of the CreateTable topic.
Parameter | Description |
table_meta | The schema information about the data table. The schema information contains the following parameters:
|
table_options | The configuration information about the data table. For more information, see Data versions and TTL. The configuration information contains the following parameters:
You can call the UpdateTable operation to modify the time_to_live and max_versions parameters of a data table. For more information, see UpdateTable. |
reserved_throughput | The reserved read throughput and reserved write throughout for the data table. You can set the reserved read throughput and reserved write throughout only to 0 for data tables in capacity instances. Reserved throughput does not apply to these instances. The default value 0 indicates that you are charged for all throughput on a pay-as-you-go basis. Unit: capacity unit (CU).
|
secondary_indexes | The schema information about an index table. The schema information contains the following parameters:
|
Examples
Create a data table without creating an index table
The following sample code provides an example on how to create a data table that contains two primary key columns. In this example, the time_to_live parameter is set to 31536000 (one year), the max_versions parameter is set to 3, the max_time_deviation parameter is set to 86400 (one day), and the reserved_throughput parameter is set to (0,0)
.
# Create a schema for primary key columns, including the number, names, and types of primary key columns.
# The first primary key column is named pk0 and requires an INTEGER value. The first primary key column is also the partition key.
# The second primary key column is named pk1 and requires an INTEGER value. The data type is set to INTEGER in this example. 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, the max_versions 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 method 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.
except Exception:
print("create table failed.")
For more information about the sample code, see CreateTable at GitHub.
Create a data table and a global secondary index
The following sample code provides an example on how to create a global secondary index when you create a data table.
# Create a schema for primary key columns, including the number, names, and types of 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 indicates that the data never expires. Set the max_versions 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 index name, primary key columns, and attribute columns of the secondary index. Do not specify the index_type parameter. By default, a global secondary index is created if you do not specify this parameter.
secondary_indexes = [
SecondaryIndexMeta('index1', ['i', 's'], ['bool', 'b', 'd']),
]
# Call the create_table method 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 local secondary index when you create a data table.
# Create a schema for primary key columns, including the number, names, and types of 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 indicates that the data never expires. Set the max_versions 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 index name, primary key columns, index key columns, and index type of the secondary index. Set the index_type parameter to IT_LOCAL_INDEX, which indicates 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 method 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 how to read data from and write data to a data table, see Basic operations on data.
For information about how to delete a data table that you no longer need, see Delete tables.