使用CreateTable接口创建数据表时,需要指定数据表的结构信息和配置信息,高性能实例中的数据表还可以根据需要设置预留读/写吞吐量。创建数据表的同时支持创建一个或者多个索引表。

说明
  • 创建数据表后需要几秒钟进行加载,在此期间对该数据表的读/写数据操作均会失败。请等待数据表加载完毕后再进行数据操作。
  • 创建数据表时必须指定数据表的主键。主键包含1个~4个主键列,每一个主键列都有名称和类型。

前提条件

  • 已通过控制台创建实例。具体操作,请参见创建实例
  • 已初始化Client。具体操作,请参见初始化

接口

/**
 * 创建数据表,并设置主键的个数、名称、顺序和类型,以及预留读写吞吐量、TTL和stream选项。
 * @api
 * @param [] $request 请求参数。
 * @return [] 返回为空。CreateTable成功时不返回任何信息,此处返回一个空的array,与其他API保持一致。
 * @throws OTSClientException 当参数检查出错或服务端返回校验出错时抛出异常。
 * @throws OTSServerException 当OTS服务端返回错误时抛出异常。
 */
public function createTable(array $request);           

参数

  • 请求参数
    参数说明
    table_meta数据表的结构信息,包括如下内容:
    • table_name:数据表名称。
    • primary_key_schema:数据表的主键定义。更多信息,请参见主键和属性
      说明 属性列不需要定义。表格存储每行的数据列都可以不同,属性列的列名在写入时指定。
      • 每一项的顺序是主键名,主键类型PrimaryKeyType,主键设置PrimaryKeyOption(可选)。

        PrimaryKeyType可以是INTEGER、STRING(UTF-8编码字符串)、BINARY三种,分别用PrimaryKeyTypeConst::CONST_INTEGERPrimaryKeyTypeConst::CONST_STRINGPrimaryKeyTypeConst::CONST_BINARY表示。

        PrimaryKeyOption可以是PK_AUTO_INCR(自增列),用PrimaryKeyOptionConst::CONST_PK_AUTO_INCR表示。更多信息,请参见主键列自增

      • 表格存储可包含1个~4个主键列。主键列是有顺序的,与用户添加的顺序相同,例如PRIMARY KEY(A, B, C)与PRIMARY KEY(A, C, B)是不同的两个主键结构。表格存储会按照主键的大小为行排序,具体参见表格存储数据模型和查询操作
      • 第一列主键作为分区键。分区键相同的数据会存放在同一个分区内,所以相同分区键的数据下尽量不要超过10 GB,否则会导致单分区过大,无法分裂。另外,数据的读/写访问最好在不同的分区键上均匀分布,有利于负载均衡。
    • defined_column:预先定义一些非主键列以及其类型,可以作为索引表的属性列或索引列。
    table_options数据表的配置信息。更多信息,请参见数据版本和生命周期

    配置信息包括如下内容:

    • time_to_live:数据生命周期,即数据的过期时间。当数据的保存时间超过设置的数据生命周期时,系统会自动清理超过数据生命周期的数据。

      数据生命周期至少为86400秒(一天)或-1(数据永不过期)。

      创建数据表时,如果希望数据永不过期,可以设置数据生命周期为-1;创建数据表后,可以通过UpdateTable接口动态修改数据生命周期。

      单位为秒。

      说明 如果需要使用索引,则数据生命周期必须满足如下条件中的任意一个。
      • 数据表的数据生命周期为-1(数据永不过期)。
      • 数据表的数据生命周期不为-1时,数据表为禁止更新状态。
    • max_versions:最大版本数,即属性列能够保留数据的最大版本个数。当属性列数据的版本个数超过设置的最大版本数时,系统会自动删除较早版本的数据。

      创建数据表时,可以自定义属性列的最大版本数;创建数据表后,可以通过UpdateTable接口动态修改数据表的最大版本数。

      说明 如果需要使用索引,则最大版本数必须设置为1。
    • deviation_cell_version_in_sec:有效版本偏差,即写入数据的时间戳与系统当前时间的偏差允许最大值。只有当写入数据所有列的版本号与写入时时间的差值在数据有效版本偏差范围内,数据才能成功写入。

      属性列的有效版本范围为[max{数据写入时间-有效版本偏差,数据写入时间-数据生命周期},数据写入时间+有效版本偏差)

      创建数据表时,如果未设置有效版本偏差,系统会使用默认值86400;创建数据表后,可以通过UpdateTable接口动态修改有效版本偏差。

      单位为秒。

    • allow_update:是否允许UpdateRow相关更新写入操作。默认值为true,表示允许UpdateRow相关更新写入操作;当设置allow_update为false时,表示禁止UpdateRow相关更新写入操作。
    reserved_throughput为数据表配置预留读吞吐量或预留写吞吐量。

    容量型实例中的数据表的预留读/写吞吐量只能设置为0,不允许预留。

    默认值为0,即完全按量计费。

    单位为CU。

    • 当预留读吞吐量或预留写吞吐量大于0时,表格存储会根据配置为数据表预留相应资源,且数据表创建成功后,将会立即按照预留吞吐量开始计费,超出预留的部分进行按量计费。更多信息,请参见计费概述
    • 当预留读吞吐量或预留写吞吐量设置为0时,表格存储不会为数据表预留相应资源。
    stream_specStream相关设置(可选配置)。
    • enable_stream:数据表是否打开Stream。
    • expiration_time:Stream数据的过期时间,较早的修改记录将会被删除,单位为小时。

      只有当设置enable_stream为true时才能设置此参数。

    index_metas索引表的结构信息,每个index_meta都包括如下内容:
    • name:索引表名称。
    • primary_key:索引表的索引列,索引列为数据表主键和预定义列的任意组合。
    • defined_column:索引表的属性列,索引表属性列为数据表的预定义列的组合。
    • index_update_mode:索引表更新模式。可选值包括IndexUpdateModeConst::ASYNC_INDEXIndexUpdateModeConst::SYNC_INDEX
      • 当不设置index_update_mode或者设置index_update_mode为IndexUpdateModeConst::ASYNC_INDEX时,表示异步更新。

        使用全局二级索引时,索引更新模式必须设置为异步更新(IndexUpdateModeConst::ASYNC_INDEX)。

      • 当设置index_update_mode为IndexUpdateModeConst::SYNC_INDEX时,表示同步更新。

        使用本地二级索引时,索引更新模式必须设置为同步更新(IndexUpdateModeConst::SYNC_INDEX)。

    • index_type:索引表类型。可选值包括IndexTypeConst::GLOBAL_INDEXIndexTypeConst::LOCAL_INDEX
      • 当不设置index_type或者设置index_type为IndexTypeConst::GLOBAL_INDEX时,表示使用全局二级索引。

        使用全局索引时,表格存储以异步方式将数据表中被索引的列和主键列的数据自动同步到索引表中,正常情况下同步延迟达到毫秒级别。

      • 当设置index_type为IndexTypeConst::LOCAL_INDEX时,表示使用本地二级索引。

        使用本地二级索引时,表格存储以同步方式将数据表中被索引的列和主键列的数据自动同步到索引表中,当数据写入数据表后,即可从索引表中查询到数据。

  • 请求格式
    $result = $client->createTable([
        'table_meta' => [                  //设置数据表结构信息,必须配置。
            'table_name' => '<string>', 
            'primary_key_schema' => [
                ['<string>', <PrimaryKeyType>], 
                ['<string>', <PrimaryKeyType>],
                ['<string>', <PrimaryKeyType>, <PrimaryKeyOption>]
            ]
        ], 
        'reserved_throughput' => [         //设置预留读写吞吐量,必须配置。
            'capacity_unit' => [
                'read' => <integer>, 
                'write' => <integer>
            ]
        ],
        'table_options' => [              //设置数据表配置信息,必须配置。
            'time_to_live' => <integer>,   
            'max_versions' => <integer>,    
            'deviation_cell_version_in_sec' => <integer>  
        ],
        'stream_spec' => [
            'enable_stream' => true || false,
            'expiration_time' => <integer>
        ]
    ]);            
  • 响应参数

    返回为空,出错时会抛出异常。

  • 结果格式
    []      

示例

  • 创建数据表时不带索引

    创建一个有3个主键列,预留读/写吞吐量为(0, 0)的数据表,TTL永不过期,存储两个版本的数据,同时打开Stream。

    //创建主键列的schema,包括主键的个数、名称和类型。
    //第一个主键列为整数,名称是pk0,此主键列也是分区键。
    //第二个主键列为字符串,名称是pk1。
    //第三个主键列为二进制,名称是pk2。
    $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
        ]
    ]);       
  • 创建数据表时带索引且索引为全局二级索引
    $request = array (
        'table_meta' => array (
            'table_name' => 'SampleTable', //数据表名称。
            '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, //设置预留读写吞吐量为0个读CU和0个写CU。
                'write' => 0
            )
        ),
        'table_options' => array(
            'time_to_live' => -1,   //数据的过期时间,单位为秒,-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
            'max_versions' => 1,    //保存的最大版本数,1表示每列上最多保存一个版本即保存最新的版本。带索引表的数据表最大版本数必须设置为1。
            'deviation_cell_version_in_sec' => 86400  //数据有效版本偏差,单位为秒。
        ),
        '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);
  • 创建数据表时带索引且索引为本地二级索引
    $request = array (
        'table_meta' => array (
            'table_name' => 'SampleTable', //数据表名称。
            '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, //设置预留读写吞吐量为0个读CU和0个写CU。
                'write' => 0
            )
        ),
        'table_options' => array(
            'time_to_live' => -1,   //数据的过期时间,单位为秒,-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
            'max_versions' => 1,    //保存的最大版本数,1表示每列上最多保存一个版本即保存最新的版本。带索引表的数据表最大版本数必须设置为1。
            'deviation_cell_version_in_sec' => 86400  //数据有效版本偏差,单位为秒。
        ),
        '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);