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

This topic describes how to use Tablestore SDK for PHP 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

An 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

/**
 * 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. 
 * @param [] $request The request parameters. 
 * @return [] The response is empty. 
 * @throws OTSClientException The exception that is thrown when a parameter error occurs or 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

The following table describes the parameters that are included in request.

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. primary_key_schema: 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_column: This parameter is optional and specifies the predefined columns of the data table. The type of a predefined column can be String, Integer, Blob, 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 required and specifies the retention period of data in the data table. Unit: seconds. 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. A value of -1 specifies that the data never expires. 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_versions: This parameter is required and specifies the maximum number of versions that can be retained for the data in 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. deviation_cell_version_in_sec: This parameter is required and specifies the maximum difference between the current system time and the timestamp of the written data. Unit: seconds. 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.
index_metas (optional)	The list of indexes. You can configure the following parameters for each index: name: This parameter is required and specifies the name of the index. primary_key: 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: This parameter is required 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. index_update_mode: This parameter is optional and specifies the update mode of the index. Valid values: ASYNC_INDEX: asynchronous update mode. This is the default value. Note If you want to use the global secondary index feature, you must set the index_update_mode parameter to ASYNC_INDEX. SYNC_INDEX: synchronous update mode. Note If you want to use the local secondary index feature, you must set the index_update_mode parameter to SYNC_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.
stream_spec (optional)	The Stream configuration information about the data table. You can configure the following parameters to specify the Stream configuration information: enable_stream: This parameter is optional and specifies whether to enable the Stream feature. Default value: false. A value of false specifies that the Stream feature is disabled. expiration_time: This parameter is optional and specifies the validity period of incremental logs. Unit: hours. Maximum value: 168. A value of 168 specifies seven days. Note When the Stream feature is enabled, you must configure the expirationTime parameter.

Examples

Create a data table

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

$result = $client->createTable([
    'table_meta' => [
        // Specify the name of the data table. 
        'table_name' => '<TABLE_NAME>', 
        // Specify the primary key columns of the data table. The table contains the pk1 primary key column of the String type and the pk2 primary key column of the Integer type. The pk1 primary key column is the partition key. The pk2 primary key column is an auto-increment primary key column. 
        'primary_key_schema' => [
            ['pk1', PrimaryKeyTypeConst::CONST_STRING],
            ['pk2', PrimaryKeyTypeConst::CONST_INTEGER, PrimaryKeyOptionConst::CONST_PK_AUTO_INCR]
        ]
    ], 
    'table_options' => [
        // Specify the time to live (TTL) of data in the data table. A value of -1 specifies that data in the data table never expires. 
        'time_to_live' => -1, 
        // Specify the maximum number of versions that can be retained for data in each attribute column of the data table. In this example, only the latest version of data can be retained for each attribute column. 
        'max_versions' => 1,   
        // Specify the maximum difference between the current system time and the timestamp of the written data. In this example, the maximum difference is set to 86,400 seconds (one day). 
        'deviation_cell_version_in_sec' => 86400  
    ],
    'reserved_throughput' => [
        // Specify the reserved read or write throughput. You can set the reserved read or write throughput only to 0 for a data table in a capacity instance. You can set the reserved read or write throughput to a value other than 0 for a data table in a high-performance instance. 
        'capacity_unit' => [
            'read' => 0, 
            'write' => 0
        ]
    ]
]);

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:

$request = array (
    'table_meta' => array (
        // Specify the name of the data table. 
        'table_name' => '<TABLE_NAME>',
        // Specify the primary key columns of the data table. The data table contains the pk1 primary key column of the String type and the pk2 primary key column of the Integer type. 
        'primary_key_schema' => array (
            array('pk1', PrimaryKeyTypeConst::CONST_STRING),
            array('pk2', PrimaryKeyTypeConst::CONST_INTEGER)
        ),
        // Specify the predefined columns of the data table. The predefined columns of the data table are the defcol1 column of the String type and the defcol2 column of the Integer type. 
        'defined_column' => array(
            array('defcol1', DefinedColumnTypeConst::DCT_STRING),
            array('defcol2', DefinedColumnTypeConst::DCT_INTEGER)
        )
    ),
    'table_options' => [
        // Specify the TTL of data in the data table. A value of -1 specifies that data in the data table never expires. 
        'time_to_live' => -1, 
        // Specify the maximum number of versions that can be retained for data in each attribute column of the data table. In this example, only the latest version of data can be retained for each attribute column. 
        'max_versions' => 1,   
        // Specify the maximum difference between the current system time and the timestamp of the written data. In this example, the maximum difference is set to 86,400 seconds (one day). 
        'deviation_cell_version_in_sec' => 86400  
    ],
    'reserved_throughput' => array (
        // Specify the reserved read or write throughput. You can set the reserved read or write throughput only to 0 for a data table in a capacity instance. You can set the reserved read or write throughput to a value other than 0 for a data table in a high-performance instance. 
        'capacity_unit' => array (
            'read' => 0,
            'write' => 0
        )
    ),
    'index_metas' => array(
        array(
            // Specify the name of the index. 
            'name' => '<INDEX_NAME>',
            // Add primary key columns to the index. The primary key columns of the index are defcol1, pk1, and pk2.  
            'primary_key' => array('defcol1', 'pk1', 'pk2'),
            // Add predefined columns to the index. The predefined column of the index is defcol2. 
            'defined_column' => array('defcol2'),
            // 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
        ),
    )
);

// Call the method to create the table.  
$result = $client->createTable($request);

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:

$request = array (
    'table_meta' => array (
        // Specify the name of the data table. 
        'table_name' => '<TABLE_NAME>',
        // Specify the primary key columns of the data table. The data table contains the pk1 primary key column of the String type and the pk2 primary key column of the Integer type. 
        'primary_key_schema' => array (
            array('pk1', PrimaryKeyTypeConst::CONST_STRING),
            array('pk2', PrimaryKeyTypeConst::CONST_INTEGER)
        ),
        // Specify the predefined columns of the data table. The predefined columns of the data table are the defcol1 column of the String type and the defcol2 column of the Integer type. 
        'defined_column' => array(
            array('defcol1', DefinedColumnTypeConst::DCT_STRING),
            array('defcol2', DefinedColumnTypeConst::DCT_INTEGER)
        )
    ),
    'table_options' => [
        // Specify the TTL of data in the data table. A value of -1 specifies that data in the data table never expires. 
        'time_to_live' => -1, 
        // Specify the maximum number of versions that can be retained for data in each attribute column of the data table. In this example, only the latest version of data can be retained for each attribute column. 
        'max_versions' => 1,   
        // Specify the maximum difference between the current system time and the timestamp of the written data. In this example, the maximum difference is set to 86,400 seconds (one day). 
        'deviation_cell_version_in_sec' => 86400  
    ],
    'reserved_throughput' => array (
        // Specify the reserved read or write throughput. You can set the reserved read or write throughput only to 0 for a data table in a capacity instance. You can set the reserved read or write throughput to a value other than 0 for a data table in a high-performance instance. 
        'capacity_unit' => array (
            'read' => 0,
            'write' => 0
        )
    ),
    'index_metas' => array(
        array(
            // Specify the name of the index. 
            'name' => '<INDEX_NAME>',
            // Add primary key columns to the index. The primary key columns of the index are pk1, defcol1, and pk2. 
            'primary_key' => array('pk1', 'defcol1', 'pk2'),
            // Add predefined columns to the index. The predefined column of the index is defcol2. 
            'defined_column' => array('defcol2'),
            // Set the index type to local secondary index.  
            'index_type' => IndexTypeConst::LOCAL_INDEX,
            // Set the index update mode to synchronous update.  
            '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.
For information about data versions and 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 Table operations.
- Operations on data. For more information, see Basic operations on data.