This topic describes how to create a data table by calling the CreateTable operation. When you call the CreateTable operation, you must specify the schema information and configuration information of the data table. You can set reserved read throughput and reserved write throughput for data tables in high-performance instances based on your business requirements. You can create one or more index tables when you create a data table.

Note
  • After a data table is created, it takes several seconds to load the data table. During this period, read and write operations performed on the table may 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 can contain one to four primary key columns. Each primary key column has a name and a data type.

Prerequisites

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

API operations

/**
 * Create a table. Specify the number, names, sequence, and types of primary key columns, reserved read and write throughput, 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 the Tablestore server returns a verification error. 
 * @throws OTSServerException The exception that is returned when the Tablestore server returns an error. 
 */
public function createTable(array $request);           

Parameters

  • Request parameters
    ParameterDescription
    table_metaThe schema information about the data table. The schema information contains the following items:
    • 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 the attribute columns.
      • Each item consists of the name, type (PrimaryKeyType), and configurations (PrimaryKeyOption, which is optional) of the primary key column.

        PrimaryKeyType can be set to PrimaryKeyTypeConst::CONST_INTEGER, PrimaryKeyTypeConst::CONST_STRING, or PrimaryKeyTypeConst::CONST_BINARY, which separately indicate the INTEGER, STRING (UTF-8 encoded string), and BINARY types.

        PrimaryKeyOption can be set to PrimaryKeyOptionConst::CONST_PK_AUTO_INCR, which indicates the auto-increment primary key column. For more information, see Configure an auto-increment primary key column.

      • The primary key of a data table consists of 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 is stored in the same partition. Therefore, we recommend that the size of data with the same partition key be smaller than or equal to 10 GB. Otherwise, a single partition may be too large to split. We recommend that you evenly distribute requests to read and write data 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_optionsThe configuration information about the data table. For more information, see Data versions and TTL.

    The configuration information contains the following items:

    • 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 time_to_live value, Tablestore automatically deletes expired data.

      The minimum time_to_live value is 86400, which is equal to one day. A value of -1 indicates that data never expires.

      When you create a data table, you can set time_to_live to -1. This way, the data in the table never expires. After the table is created, you can call the UpdateTable operation to change the time_to_live value.

      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 requirements:
      • The time_to_live parameter of the data table is set to -1, which means 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 versions of data that can be retained for a single attribute column. If the number of versions of data in attribute columns exceeds the value of this parameter, the system 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 max_versions value for the data table.

      Note If you want to create an index table for the data table, you must set max_versions 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 deviation_cell_version_in_sec. Otherwise, an error occurs when the 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).

      When you create a data table, Tablestore uses the default value of 86400 if you do not specify a max version offset. After the data table is created, you can call the UpdateTable operation to modify the deviation_cell_version_in_sec value.

      Unit: seconds.

    • allow_update: specifies whether to allow the UpdateRow operation. The default value is true, which indicates that the UpdateRow operation is allowed. If you set allow_update to false, the UpdateRow operation is prohibited.
    reserved_throughputThe reserved read throughput and reserved write throughput of the data table.

    You can set the reserved read throughput or reserved write throughput 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 billed 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 resources for the data table. After you create the data table, Tablestore charges you for the reserved throughput. You are charged for additional throughput based on the pay-as-you-go billing method. 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) 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 specify this parameter only when you set enable_stream to true.

    index_metasThe schema information about the index table. Each index_meta includes the following items:
    • name: the name of the index table.
    • primary_key: the primary key of the index table, which 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 index_update_mode is not specified or is set to IndexUpdateModeConst::ASYNC_INDEX, the asynchronous mode is used to update the index.

        If you use the global secondary index feature, you must set the index update mode to IndexUpdateModeConst::ASYNC_INDEX.

      • If index_update_mode is set to IndexUpdateModeConst::SYNC_INDEX, the synchronous mode is used to update the index.

        If you use the local secondary index feature, you must set the index update mode to IndexUpdateModeConst::SYNC_INDEX.

    • index_type: the type of the index table. Valid values: IndexTypeConst::GLOBAL_INDEX and IndexTypeConst::LOCAL_INDEX.
      • If index_type is not specified or is set to IndexTypeConst::GLOBAL_INDEX, the global secondary index feature is used.

        When you use the global secondary index feature, Tablestore automatically synchronizes the data from the indexed columns and primary key columns of a data table to the columns of an index table in asynchronous mode. The synchronization latency is within a few milliseconds.

      • If index_type is set to IndexTypeConst::LOCAL_INDEX, the local secondary index feature is used.

        When you use the local secondary index feature, Tablestore automatically synchronizes data from the indexed columns and primary key columns of a data table to the columns of an index table in synchronous mode. You can immediately query data from the index table after the data is written to the data table.

  • Request format
    $result = $client->createTable([
        'table_meta' => [                  // Specify the schema information about the 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 table. This parameter is required. 
            'capacity_unit' => [
                'read' => <integer>, 
                'write' => <integer>
            ]
        ],
        'table_options' => [              // Specify the configuration information about the 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 parameters

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

  • Result format
    []      

Examples

  • Create a data table without creating an index table for the data table

    The following code provides an example on how to create a table that contains three primary key columns. In this example, the reserved read and write throughput is set to 0, TTL is set to -1, max_versions is set to 2, and Stream is enabled.

    // Specify the schema for the primary key columns, which includes 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 the partition key. 
    // The second primary key column is named pk1 and requires a STRING value. 
    // The third primary key column is named pk2 and requires a BINARY value. 
    $result = $client->createTable([
        'table_meta' => [
            'table_name' => 'SampleTable', 
            'primary_key_schema' => [
                ['PK0', PrimaryKeyTypeConst::CONST_INTEGER], 
                ['PK1', PrimaryKeyTypeConst::CONST_STRING],
                ['PK2', PrimaryKeyTypeConst::CONST_BINARY]
            ]
        ], 
        'reserved_throughput' => [
            'capacity_unit' => [
                'read' => 0, 
                'write' => 0
            ]
        ],
        'table_options' => [
            'time_to_live' => -1,   
            'max_versions' => 2,    
            'deviation_cell_version_in_sec' => 86400  
        ],
        'stream_spec' => [
            'enable_stream' => true,
            'expiration_time' => 24
        ]
    ]);       
  • Create a data table and a global secondary index for the data table
    $request = array (
        'table_meta' => array (
            'table_name' => 'SampleTable', // Specify the name of the data table. 
            'primary_key_schema' => array (
                array('PK0', PrimaryKeyTypeConst::CONST_INTEGER),
                array('PK1', PrimaryKeyTypeConst::CONST_STRING)
            ),
            'defined_column' => array(
                array('col1', DefinedColumnTypeConst::DCT_STRING),
                array('col2', DefinedColumnTypeConst::DCT_INTEGER)
            )
        ),
    
        'reserved_throughput' => array (
            'capacity_unit' => array (
                'read' => 0, // Set both the reserved read throughput and reserved write throughput to 0. 
                'write' => 0
            )
        ),
        'table_options' => array(
            'time_to_live' => -1,   // Set time_to_live to -1, which indicates that the data never expires. You must set time_to_live to -1 for a data table for which you want to create an index table. 
            'max_versions' => 1,    // Specify the maximum number of versions that can be retained for each attribute column. A value of 1 indicates that only the latest version is retained for each attribute column. You must set max_versions to 1 for a data table for which you want to create an index table. 
            'deviation_cell_version_in_sec' => 86400   // Specify the max version offset of data. Unit: seconds. 
        ),
        'index_metas' => array(
            array(
                'name' => 'indexName1',
                'primary_key' => array('col1'),
                'defined_column' => array('col2'),
                'index_type' => IndexTypeConst::GLOBAL_INDEX,
                'index_update_mode' => IndexUpdateModeConst::ASYNC_INDEX
            ),
            array(
                'name' => 'indexName2',
                'primary_key' => array('PK1'),
                'defined_column' => array('col1', 'col2')
            )
        )
    );
    $this->otsClient->createTable($request);
  • Create a data table and a local secondary index for the data table
    $request = array (
        'table_meta' => array (
            'table_name' => 'SampleTable', // Specify the name of the data table. 
            'primary_key_schema' => array (
                array('PK0', PrimaryKeyTypeConst::CONST_INTEGER),
                array('PK1', PrimaryKeyTypeConst::CONST_STRING)
            ),
            'defined_column' => array(
                array('col1', DefinedColumnTypeConst::DCT_STRING),
                array('col2', DefinedColumnTypeConst::DCT_INTEGER)
            )
        ),
    
        'reserved_throughput' => array (
            'capacity_unit' => array (
                'read' => 0, // Set both the reserved read throughput and reserved write throughput to 0. 
                'write' => 0
            )
        ),
        'table_options' => array(
            'time_to_live' => -1,   // Set time_to_live to -1, which indicates that the data never expires. You must set time_to_live to -1 for a data table for which you want to create an index table. 
            'max_versions' => 1,    // Specify the maximum number of versions that can be retained for each attribute column. A value of 1 indicates that only the latest version is retained for each attribute column. You must set max_versions to 1 for a data table for which you want to create an index table. 
            'deviation_cell_version_in_sec' => 86400   // Specify the max version offset of data. Unit: seconds. 
        ),
        'index_metas' => array(
            array(
                'name' => 'indexName3',
                'primary_key' => array('PK0', 'col1'),
                'defined_column' => array('col2'),
                'index_type' => IndexTypeConst::LOCAL_INDEX,
                '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
            )
        )
    );
    $this->otsClient->createTable($request);