CreateTable

API接口:CreateTable

表格存储建表时需要指定表的结构信息(TableMeta)和配置信息(TableOptions),也可指定表的预留读/写吞吐量(ReservedThroughput)。

建表后服务端需要将表的分片加载到某个节点上,因此需要等待几秒钟才能对表进行读写,否则会抛出异常。注:本SDK遇到这种情况读写会自动重试。

接口

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

请求格式

$result = $client->createTable([
    'table_meta' => [                  // REQUIRED
        'table_name' => '<string>', 
        'primary_key_schema' => [
            ['<string>', <PrimaryKeyType>], 
            ['<string>', <PrimaryKeyType>],
            ['<string>', <PrimaryKeyType>, <PrimaryKeyOption>]
        ]
    ], 
    'reserved_throughput' => [         // REQUIRED
        'capacity_unit' => [
            'read' => <integer>, 
            'write' => <integer>
        ]
    ],
    'table_options' => [              // REQUIRED
        'time_to_live' => <integer>,   
        'max_versions' => <integer>,    
        'deviation_cell_version_in_sec' => <integer>  
    ],
    'stream_spec' => [
        'enable_stream' => true || false,
        'expiration_time' => <integer>
    ]
]);            

请求格式说明

  • table_meta TableMeta 包含表名和表的主键定义,(必须设置)。
    • table_name 表名。
    • primary_key_schema 表的主键定义。
      • 表的主键可包含多个主键列。主键列是有顺序的,与用户添加的顺序相同。比如 PRIMARY KEY (A, B, C) 与 PRIMARY KEY (A, C, B) 是不同的两个主键结构。表格存储会按照整个主键的大小对行进行排序。

        具体请参见表格存储数据模型和查询操作

      • 第一列主键列的值作为分片键。分片键相同的数据肯定会在同一个分片内,所以相同分片键下最好不要超过 10 G 以上数据,否则会导致单分片过大(无法分裂)。另一方面,数据和读/写访问最好在不同的分片键上均匀分布,有利于负载均衡,在设计表结构时需要注意这一点。
      • 用户建表时只需要定义表的主键,属性列不需要定义。每行的数据列都可以不同,属性列的列名在写入时指定。因此,表格存储非常适合存储半结构化的数据,在业务发展过程中可以动态添加新的数据列。
      • 每一项的顺序是 主键名,主键类型PrimaryKeyType,主键设置(可选)PrimaryKeyOption。
      • PrimaryKeyType可以是INTEGER,STRING(UTF-8编码字符串),BINARY三种,分别用PrimaryKeyTypeConst::CONST_INTEGER,PrimaryKeyTypeConst::CONST_STRING,PrimaryKeyTypeConst::CONST_BINARY表示。
      • PrimaryKeyOption可以是PK_AUTO_INCR(自增列,详见主键列自增),分别用PrimaryKeyOptionConst::CONST_PK_AUTO_INCR表示。
  • reserved_throughput 表的预留读/写吞吐量配置,与计费相关,(必须设置)。
    • capacity_unit 当预留读/写吞吐量大于 0 时,会按照预留量和持续时间进行计费,超出预留的部分进行按量计费。默认预留读写吞吐量为 0,即完全按量计费,如果要设置为大于 0 的值,请仔细阅读表格存储的计费相关文档,以免产生未期望的费用。容量型实例的预留读/写吞吐量只能设置为 0,不允许预留。
      • read 预留读吞吐量
      • write 预留写吞吐量
  • table_options TableOptions 包含表的 TTL、MaxVersions 和 MaxTimeDeviation 配置,(必须设置)。
    • time_to_live TimeToLive,数据存活时间,单位秒。
      • 表格存储的新版 API 支持数据自动过期。如果期望永不过期,TTL 可设置为 -1。
      • 数据是否过期是根据“数据的时间戳“、“当前时间”、“表的 TTL”三者进行判断的。当“当前时间”减去“数据的时间戳”大于“表的 TTL”时,数据会过期并被表格存储服务器端清理。有关数据的时间戳的更多信息,请参见前言
      • 当设置 TTL 后,由于判断过期涉及数据的时间戳,如果用户指定时间戳写入,且指定的时间戳严重偏离当前时间,那么可能导致未预料的数据过期行为。比如指定的数据时间戳很小,可能导致数据一写入就被过期回收了。当指定的数据时间戳很大时,又可能导致期望过期的数据过期不掉。因此在使用 TTL 功能时需要注意写入时是否指定了时间戳,以及指定的时间戳是否合理。
    • max_versions 每个属性列保留的最大版本数。
      • 表格存储的新版 API 支持多版本的数据模型,前言一章对此已经做了一些介绍。MaxVersions 即用来指定每个属性列最多保存多少个版本的数据,如果写入的版本数超过 MaxVersions,服务端只会保留版本号最大的 MaxVersions 个版本。
    • deviation_cell_version_in_sec 指定版本写入数据时所指定的版本与系统当前时间偏差允许的最大值,单位为秒。
      • 表格存储支持多版本,默认情况下系统会为新写入的数据生成一个版本号,是写入时间的毫秒单位时间戳,数据自动过期功能需要根据这个时间戳判断数据是否过期。另一方面,用户可以指定写入数据的时间戳,因此如果用户写入的时间戳非常小,与当前时间偏差已经超过了表上设置的 TTL 时间,写入的数据会立即过期。出于保护的目的,在表上增加了 MaxTimeDeviation 设置,限制写入数据的时间戳与系统当前时间的偏差,该值的单位为秒,可在建表时指定,也可通过 UpdateTable 接口修改。
  • stream_spec Stream相关设置,(可选配置)。
    • enable_stream Stream 是否打开
    • expiration_time Stream 数据的过期时间,较早的修改记录将会被删除,单位小时

结果格式

    []      

结果格式说明

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

示例

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

        //创建主键列的schema,包括PK的个数,名称和类型
        //第一个PK列为整数,名称是pk0,这个同时也是分片列
        //第二个PK列为字符串,名称是pk1
        //第三个PK列为二进制,名称是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
            ]
        ]);