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

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 schema information and configuration information for the data table. If the data table belongs to a high-performance instance, you can configure the reserved read throughput and the reserved write throughput based on your business requirements. You can create one or more index tables when you create a data table.

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.
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.
In system design scenarios that require a unique identifier for each object, such as item IDs on e-commerce websites, user IDs on large websites, post IDs in forums, and message IDs in chat tools, 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

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

API operation

/**
 * Create a data table. Specify the number, names, sequence, and types of primary key columns, reserved read and write throughput, time to live (TTL), and Stream options. 
 * @api
 * @param [] $request The request parameters. 
 * @return [] The response is empty. If the CreateTable operation is successful, no message is returned. An empty array is returned to be consistent with other operations. 
 * @throws OTSClientException The exception that is returned when a parameter error occurs or when the Tablestore server returns a verification error. 
 * @throws OTSServerException The exception that is thrown when the Tablestore server returns an error. 
 */
public function createTable(array $request);

Parameters

Request information

Request parameters

Parameter	Description
table_meta	The schema information about the data table. The schema information includes the following parameters: table_name: the name of the data table. primary_key_schema: the schema of the primary key for the table. For more information, see Primary keys and attributes. Note You do not need to specify the schema for attribute columns. Different rows in a Tablestore table can have different attribute columns. You can specify the names of attribute columns when you write data to a data table. Each item consists of the name, type (PrimaryKeyType), and configurations (PrimaryKeyOption, which is optional) of the primary key column. You can use `PrimaryKeyTypeConst::CONST_INTEGER` to specify INTEGER as the type of a primary key column, `PrimaryKeyTypeConst::CONST_STRING` to specify STRING (UTF-8 encoded string) as the type of a primary key column, and `PrimaryKeyTypeConst::CONST_BINARY` to specify BINARY as the type of a primary key column. You can use `PrimaryKeyOptionConst::CONST_PK_AUTO_INCR` to set the PrimaryKeyOption parameter to PK_AUTO_INCR. PK_AUTO_INCR specifies an auto-increment primary key column. For more information, see Configure an auto-increment primary key column. The primary key of a data table can contain one to four primary key columns. Primary key columns are sorted in the order in which they are added. For example, PRIMARY KEY (A, B, C) and PRIMARY KEY (A, C, B) have different primary key schemas. Tablestore sorts rows based on the values of all primary key columns. The first primary key column is the partition key. Data that has the same partition key value are stored in the same partition. We recommend that you set the size of data that has the same partition key to a value that is less than or equal to 10 GB. Otherwise, a single partition may be excessively large to split. We recommend that you evenly distribute read and write requests to different partition keys for load balancing. defined_column: the predefined columns of the data table and the data types of the predefined columns. Primary key columns cannot be specified as predefined columns. You can use predefined columns as the index columns or attribute columns for index tables.
table_options	The configuration information about the data table. For more information, see Data versions and TTL. The configuration information includes the following parameters: time_to_live: the period during which data in the table can be retained. This period is the validity period of data. If the retention period exceeds the value of the time_to_live parameter, Tablestore automatically deletes expired data. The minimum value of the time_to_live parameter is 86400, which is equal to one day. A value of -1 specifies that data never expires. If you set the time_to_live parameter to -1 for the data table, the data in the data table never expires. After the data table is created, you can call the UpdateTable operation to modify the value of the time_to_live parameter. Unit: seconds. Note If you want to create an index table for the data table, the time_to_live parameter must meet one of the following conditions: The time_to_live parameter of the data table is set to -1, which specifies that data in the data table never expires. The time_to_live parameter of the data table is set to a value other than -1, and update operations on the data table are prohibited. max_versions: the maximum number of data versions that can be retained for a single attribute column. If the number of versions of data in an attribute column exceeds the value of the max_versions parameter, the system automatically deletes data of earlier versions. When you create a data table, you can specify the maximum number of versions that can be retained for the data in an attribute column. After the data table is created, you can call the UpdateTable operation to modify the value of the max_versions parameter for the data table. Note If you want to create an index table for the data table, you must set the max_versions parameter to 1. deviation_cell_version_in_sec: the max version offset, which is the maximum difference between the current system time and the timestamp of the written data. The difference between the version number and the time at which the data is written must be less than or equal to the value of the deviation_cell_version_in_sec parameter. Otherwise, an error occurs when data is written. The valid version range of data in an attribute column is calculated by using the following formula: Valid version range = [max{Data written time - Max version offset, Data written time - TTL value}, Data written time + Max version offset). If you do not configure the deviation_cell_version_in_sec parameter, when you create a data table, Tablestore uses the default value of 86400. After the data table is created, you can call the UpdateTable operation to modify the value of the deviation_cell_version_in_sec parameter. Unit: seconds. allow_update: specifies whether to allow the UpdateRow operation. The default value is true, which specifies that the UpdateRow operation is allowed. If you set the allow_update parameter to false, the UpdateRow operation is prohibited.
reserved_throughput	The reserved read throughput and reserved write throughput of the data table. You can set the reserved read throughput and reserved write throughput only to 0 for data tables in capacity instances. Reserved throughput does not apply to capacity instances. The default value 0 specifies that you are charged for all throughput on a pay-as-you-go basis. Unit: capacity unit (CU). If you set the reserved read throughput or reserved write throughput to a value that is greater than 0 for a data table, Tablestore reserves the related resources for the data table. After you create the data table, you are charged for the reserved throughput resources. You are charged for additional throughput on a pay-as-you-go basis. For more information, see Billing overview. If you set the reserved read throughput or reserved write throughput to 0, Tablestore does not reserve resources for the data table.
stream_spec	(Optional) The Stream configurations. enable_stream: specifies whether to enable Stream for the data table. expiration_time: the expiration time of the Stream data of the table. Unit: hours. Earlier modification records are deleted. You can configure this parameter only if you set the enable_stream parameter to true.
index_metas	The schema information about the index table. Each index_meta includes the following parameters: name: the name of the index table. primary_key: the primary key of the index table. The primary key is a combination of all primary key columns and a random number of predefined columns of the data table. defined_column: the attribute columns of the index table. The attribute columns are a combination of predefined columns of the data table. index_update_mode: the update mode of the index table. Valid values: `IndexUpdateModeConst::ASYNC_INDEX` and `IndexUpdateModeConst::SYNC_INDEX`. If you do not configure the index_update_mode parameter or set the index_update_mode parameter to `IndexUpdateModeConst::ASYNC_INDEX`, the asynchronous update mode is used. To use a global secondary index, you must set the index_update_mode parameter to `IndexUpdateModeConst::ASYNC_INDEX`. If you set the index_update_mode parameter to `IndexUpdateModeConst::SYNC_INDEX`, the synchronous update mode is used. To use a local secondary index, you must set the index_update_mode parameter to `IndexUpdateModeConst::SYNC_INDEX`. index_type: the type of the index table. Valid values: `IndexTypeConst::GLOBAL_INDEX` and `IndexTypeConst::LOCAL_INDEX`. If you do not configure the index_type parameter or set the index_type parameter to `IndexTypeConst::GLOBAL_INDEX`, a global secondary index is created. Tablestore automatically synchronizes data from the indexed columns and primary key columns of the data table to the columns of the index table that you want to create in asynchronous mode. The synchronization latency is within a few milliseconds. If you set the index_type parameter to `IndexTypeConst::LOCAL_INDEX`, a local secondary index is created. Tablestore automatically synchronizes data from the indexed columns and primary key columns of the data table to the columns of the index table that you want to create in synchronous mode. After data is written to the data table, you can immediately query the data in the index table.

Request syntax

$result = $client->createTable([
    'table_meta' => [                  // Specify the schema information about the data table. This parameter is required. 
        'table_name' => '<string>', 
        'primary_key_schema' => [
            ['<string>', <PrimaryKeyType>], 
            ['<string>', <PrimaryKeyType>],
            ['<string>', <PrimaryKeyType>, <PrimaryKeyOption>]
        ]
    ], 
    'reserved_throughput' => [         // Specify the reserved read and write throughput of the data table. This parameter is required. 
        'capacity_unit' => [
            'read' => <integer>, 
            'write' => <integer>
        ]
    ],
    'table_options' => [              // Specify the configuration information about the data table. This parameter is required. 
        'time_to_live' => <integer>,   
        'max_versions' => <integer>,    
        'deviation_cell_version_in_sec' => <integer>  
    ],
    'stream_spec' => [
        'enable_stream' => true || false,
        'expiration_time' => <integer>
    ]
]);

Response information

Response parameters

The response is empty. If an error occurs, the system returns an exception.

Response syntax

[]

Examples

Create a data table without creating an index table

The following sample code provides an example on how to create a data table without creating an index table for the data table. In this example, the data table consists of the following primary key columns: the PK0 primary key column of the Integer type, the PK1 primary key column of the String type, and the PK2 primary key column of the Binary type. Up to two versions of data can be retained for each attribute column in the data table and data in the data table never expires.

$result = $client->createTable([
    'table_meta' => [
        // Specify the name of the data table. 
        'table_name' => 'SampleTable', 
        // Add primary key columns to the data table. 
        'primary_key_schema' => [
            ['PK0', PrimaryKeyTypeConst::CONST_INTEGER], 
            ['PK1', PrimaryKeyTypeConst::CONST_STRING],
            ['PK2', PrimaryKeyTypeConst::CONST_BINARY]
        ]
    ], 
    'reserved_throughput' => [
        // Specify the reserved read throughput and reserved write throughput. You can set the reserved read throughput or reserved write throughput only to 0 for data tables in a capacity instance. You can set the reserved read throughput or reserved write throughput to a value other than 0 for data tables in a high-performance instance. 
        'capacity_unit' => [
            'read' => 0, 
            'write' => 0
        ]
    ],
    'table_options' => [
        // Specify the validity period of data. A value of -1 specifies that the data never expires. Unit: seconds. You must set the time_to_live parameter to -1 for a data table for which you want to create an index table. 
        'time_to_live' => -1, 
        // Specify the maximum number of data versions that can be retained for each attribute column. A value of 1 specifies that only the latest version of data is retained for each attribute column. You must set the max_versions parameter to 1 for a data table for which you want to create an index table.   
        'max_versions' => 2,   
        // Configure the deviation_cell_version_in_sec parameter, which specifies the maximum difference between the current system time and the time when data is written.  
        'deviation_cell_version_in_sec' => 86400  
    ],
    'stream_spec' => [
        // Enable Stream.  
        'enable_stream' => true,
        // Specify the expiration time of Stream data.  
        'expiration_time' => 24
    ]
]);

Create a data table and global secondary indexes

The following sample code provides an example on how to create a data table and two global secondary indexes for the data table at the same time. In this example, the data table consists of the following primary key columns: the PK0 primary key column of the Integer type and the PK1 primary key column of the String type. The following predefined columns are specified for the data table: the col1 column of the String type and the col2 column of the Integer type. Up to two versions of data can be retained for each attribute column in the data table and data in the data table never expires. The global secondary index named indexName1 consists of the col1, PK0, and PK1 primary key columns and the col2 attribute column. The global secondary index named indexName2 consists of the PK1 and PK0 primary key columns and the col1 and col2 attribute columns.

$request = array (
    'table_meta' => array (
        // Specify the name of the data table. 
        'table_name' => 'SampleTable',
        // Add primary key columns to the data table. 
        'primary_key_schema' => array (
            array('PK0', PrimaryKeyTypeConst::CONST_INTEGER),
            array('PK1', PrimaryKeyTypeConst::CONST_STRING)
        ),
        // Add attribute columns to the data table.  
        'defined_column' => array(
            array('col1', DefinedColumnTypeConst::DCT_STRING),
            array('col2', DefinedColumnTypeConst::DCT_INTEGER)
        )
    ),
    'reserved_throughput' => array (
        // Specify the reserved read throughput and reserved write throughput. You can set the reserved read throughput or reserved write throughput only to 0 for data tables in a capacity instance. You can set the reserved read throughput or reserved write throughput to a value other than 0 for data tables in a high-performance instance. 
        'capacity_unit' => array (
            'read' => 0,
            'write' => 0
        )
    ),
   'table_options' => [
        // Specify the validity period of data. A value of -1 specifies that the data never expires. Unit: seconds. You must set the time_to_live parameter to -1 for a data table for which you want to create an index table. 
        'time_to_live' => -1, 
        // Specify the maximum number of data versions that can be retained for each attribute column. A value of 1 specifies that only the latest version of data is retained for each attribute column. You must set the max_versions parameter to 1 for a data table for which you want to create an index table.   
        'max_versions' => 1,   
        // Configure the deviation_cell_version_in_sec parameter, which specifies the maximum difference between the current system time and the time when data is written.  
        'deviation_cell_version_in_sec' => 86400  
    ],
    'index_metas' => array(
        array(
            // Specify the name of the index table. 
            'name' => 'indexName1',
            // Specify the index columns of the index table. The index columns are a combination of all primary key columns and a random number of predefined columns of the data table.  
            'primary_key' => array('col1'),
            // Specify the attribute columns of the index table. The attribute columns are a combination of predefined columns of the data table. 
            'defined_column' => array('col2'),
            // Set the index type to global secondary index.  
            'index_type' => IndexTypeConst::GLOBAL_INDEX,
            // Set the index update mode to asynchronous update.  
            'index_update_mode' => IndexUpdateModeConst::ASYNC_INDEX
        ),
        array(
            'name' => 'indexName2',
            'primary_key' => array('PK1'),
            'defined_column' => array('col1', 'col2')
        )
    )
);
// Call the method to create the table.  
$result = $client->createTable($request);

Create a data table and local secondary indexes

The following sample code provides an example on how to create a data table and two local secondary indexes for the data table at the same time. In this example, the data table consists of the following primary key columns: the PK0 primary key column of the Integer type and the PK1 primary key column of the String type. The following predefined columns are specified for the data table: the col1 column of the String type and the col2 column of the Integer type. Up to two versions of data can be retained for each attribute column in the data table and data in the data table never expires. The local secondary index named indexName3 consists of the PK0, col1, and PK2 primary key columns and the col2 attribute column. The local secondary index named indexName4 consists of the PK0, col2, and PK1 primary key columns and the col1 attribute column.

$request = array (
    'table_meta' => array (
        // Specify the name of the data table. 
        'table_name' => 'SampleTable', 
        // Add primary key columns to the data table. 
        'primary_key_schema' => array (
            array('PK0', PrimaryKeyTypeConst::CONST_INTEGER),
            array('PK1', PrimaryKeyTypeConst::CONST_STRING)
        ),
        // Add attribute columns to the data table.  
        'defined_column' => array(
            array('col1', DefinedColumnTypeConst::DCT_STRING),
            array('col2', DefinedColumnTypeConst::DCT_INTEGER)
        )
    ),
    // Specify the reserved read throughput and reserved write throughput. You can set the reserved read throughput or reserved write throughput only to 0 for data tables in a capacity instance. You can set the reserved read throughput or reserved write throughput to a value other than 0 for data tables in a high-performance instance. 
    'reserved_throughput' => array (
        'capacity_unit' => array (
            'read' => 0,
            'write' => 0
        )
    ),
    'table_options' => array(
        // Specify the validity period of data. A value of -1 specifies that the data never expires. Unit: seconds. You must set the time_to_live parameter to -1 for a data table for which you want to create an index table. 
        'time_to_live' => -1,   
        // Specify the maximum number of data versions that can be retained for each attribute column. A value of 1 specifies that only the latest version of data is retained for each attribute column. You must set the max_versions parameter to 1 for a data table for which you want to create an index table.   
        'max_versions' => 1,  
        // Configure the deviation_cell_version_in_sec parameter, which specifies the maximum difference between the current system time and the time when data is written.  
        'deviation_cell_version_in_sec' => 86400  
    ),
    'index_metas' => array(
        array(
             // Specify the name of the index table. 
            'name' => 'indexName3',
            // Specify the index columns of the index table. The index columns are a combination of all primary key columns and a random number of predefined columns of the data table.  
            'primary_key' => array('PK0', 'col1'),
            // Specify the attribute columns of the index table. The attribute columns are a combination of predefined columns of the data table. 
            'defined_column' => array('col2'),
            // Set the index type to local secondary index.  
            'index_type' => IndexTypeConst::LOCAL_INDEX,
            // Set the index update mode to asynchronous update.  
            'index_update_mode' => IndexUpdateModeConst::SYNC_INDEX
        ),
        array(
            'name' => 'indexName4',
            'primary_key' => array('PK0', 'col2'),
            'defined_column' => array('col1'),
            'index_type' => IndexTypeConst::LOCAL_INDEX,
            'index_update_mode' => IndexUpdateModeConst::SYNC_INDEX
        )
    )
);
// Call the method to create the table.  
$result = $client->createTable($request);

References

For information about the API operation that you can call to create a data table, see CreateTable.
You can call API operations to read and write data in a table. For more information, see Basic operations on data.
You can update a table to modify the information about the table, such as the TTL and max versions. For more information, see Update data tables.
After you enable the local transaction feature for a data table, you can create a local transaction and perform read and write operations on the data in the local transaction. For more information, see Configure local transaction.
You can query the names of tables to view all existing tables in an instance. For more information, see List the names of tables.
You can query the description of a table to view the configuration information about the table, such as the max versions and TTL. For more information, see Query the description of a table.
You can delete a data table that you no longer require. For more information, see Delete tables.