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

Note
  • After a table is created, it takes several seconds to load the table. During this period, the read and write operations performed on the table may fail. Perform operations on a table after the table is loaded.
  • You must specify the primary key when you create a 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 console. For more information, see Create instances.
  • OTSClient is initialized. For more information, see Initialization.

Operations

/**
 * Create a table. Set 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 succeeds, 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
    Parameter Description
    table_meta The schema information of the table, which includes the following items:
    • table_name: the name of the table.
    • primary_key_schema: the schema of the primary key for the table. For more information, see Primary keys and attributes.
      Note Attribute columns do not need to be defined. Different rows in Tablestore can have different attribute columns. The names of attribute columns can be specified when data is written.
      • Each item consists of the name, type (PrimaryKeyType), and configurations (PrimaryKeyOption, which is optional) of the primary key columns.

        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 column. For more information, see Configure an auto-increment primary key column.

      • The primary key of a 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 serves as the partition key. Data with the same partition key value is stored in the same partition. Therefore, we recommend that you assign no more than 10 GB of data with the same partition key value. Otherwise, a single partition may be too large to split. We recommend that you set a well-designed primary key so that read and write operations can be evenly distributed to different partitions to facilitate load balancing.
    • defined_column: the predefined columns of the table and the data types of the predefined column values. Primary key columns cannot be set to predefined columns. You can use predefined columns as the indexed columns or attribute columns for index tables.
    table_options The configurations of the table. For more information, see Max versions and TTL.

    The configurations include the following items:

    • time_to_live: the period for which data in the table can be retained. This period is the validity period of data. When the retention period exceeds the time_to_live value, Tablestore automatically deletes expired data.

      The minimum time_to_live value is 86,400 (one day). A value of -1 indicates that data never expires.

      When you create a table, you can set timeToLive to -1 if you expect that data never expires. After the table is created, you can call the UpdateTable operation to modify the time_to_live value.

      Unit: seconds.

      Note You must set time_to_live to -1 if you want to create index tables for the base table.
    • max_versions: the maximum number of versions of data that can be retained for a single attribute column. When the number of versions of data in attribute columns exceeds the max versions value, Tablestore automatically deletes data of earlier versions.

      When you create a table, you can customize the maximum number of versions that can be retained for the data in an attribute column. After the table is created, you can call the UpdateTable operation to modify the max_versions value for the table.

      Note You must set max_versions to 1 if you want to create index tables for the base table.
    • deviation_cell_version_in_sec: the max version offset, which is the maximum difference between the timestamp of the written data and the current system time. The difference between the version number and the data written time must be within the value of deviation_cell_version_in_sec. Otherwise, an error occurs when the data is written. Unit: seconds.

      The valid version range of data in an attribute column is calculated based on the formula: Valid version range = [Data written time - Max version offset, Data written time + Max version offset).

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

      Unit: seconds.

    reserved_throughput The reserved read and write throughput of the table.

    For capacity instances, the reserved read and write throughput can be set only to 0. Reserved throughput does not apply to these instances.

    The default value 0 indicates that all throughput is billed on a pay-as-you-go basis.

    Unit: CU.

    • When reserved read throughput or reserved write throughput is set to a value greater than 0, Tablestore allocates and reserves related resources for the table. After the table is created, Tablestore charges reserved throughput resources. Additional throughput is billed on a pay-as-you-go basis. For more information, see Billing overview.
    • When reserved read throughput or reserved write throughput is set to 0, Tablestore does not allocate or reserve related resources for the table.
    stream_spec Stream configurations (optional).
    • enable_stream: indicates whether Stream is enabled for the table.
    • expiration_time: the expiration time of the Stream data of the table. Unit: hour. Earlier modification records are deleted.

      This parameter can be set only when the enable_stream parameter is set to true.

    index_metas The schema information of the index tables. 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 primary key columns and predefined columns of the base table.
    • defined_column: the indexed attribute column, which is a combination of predefined columns of the base table.
    • index_update_mode: the update mode of the index table. Only IUM_ASYNC_INDEX is supported.
    • index_type: the type of the index table. Only IT_GLOBAL_INDEX is supported.
  • Request format
    $result = $client->createTable([
        'table_meta' => [                  // Set the schema information of the table. This parameter is required.
            'table_name' => '<string>', 
            'primary_key_schema' => [
                ['<string>', <PrimaryKeyType>], 
                ['<string>', <PrimaryKeyType>],
                ['<string>', <PrimaryKeyType>, <PrimaryKeyOption>]
            ]
        ], 
        'reserved_throughput' => [         // Set the reserved read and write throughput of the table. This parameter is required.
            'capacity_unit' => [
                'read' => <integer>, 
                'write' => <integer>
            ]
        ],
        'table_options' => [              // Set the configuration information of 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.

  • Response format
    []      

Examples

  • Create a base table without creating an index table

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

    //Create a 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 also 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 an index table when you create the base table
    $request = array (
        'table_meta' => array (
            'table_name' => self::$tableName, // The name of the base table is testGlobalTableName.
            '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 the base table that has index tables.
            'max_versions' => 1,    // Specify the maximum number of versions that can be retained for each column. A value of 1 indicates that only the latest version is retained for each column. You must set max_versions to 1 for the base table that has index tables.
            'deviation_cell_version_in_sec' => 86400   // Set the max version offset of data. Unit: seconds.
        ),
        'index_metas' => array(
            array(
                'name' => self::$indexName1,
                'primary_key' => array('col1'),
                'defined_column' => array('col2')
            ),
            array(
                'name' => self::$indexName2,
                'primary_key' => array('PK1'),
                'defined_column' => array('col1', 'col2')
            )
        )
    );
    $this->otsClient->createTable($request);