SDK 提供了 CreateTable、ListTable、DeleteTable、UpdateTable、DescribeTable 和 ComputeSplitsBySize 等表级别的操作接口。

创建表(CreateTable)

API说明

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

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

接口

     /**
     * 创建表,并设定主键的个数、名称、顺序和类型,以及预留读写吞吐量,TTL,stream选项。
     * API说明:https://help.aliyun.com/document_detail/27312.html
     * @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
            ]
        ]);

列出表名称(ListTable)

获取当前实例下已创建的所有表的表名。

接口

    /**
     * 获取该实例下所有的表名。
     * API说明:https://help.aliyun.com/document_detail/27313.html
     * @api
     * @param [] $request 请求参数,为空。
     * @return [] 请求返回 
     * @throws OTSClientException 当参数检查出错或服务端返回校验出错时
     * @throws OTSServerException 当OTS服务端返回错误时
     */
    public function listTable(array $request);

请求格式

$result = $client->listTable([]);

请求格式说明

目前请求为空。

结果格式

    [
        '<string>',
        '<string>',
        '<string>'
    ]

结果格式说明

结果是一个string的list. 每一项是一个表名。

示例

获取实例下的所有表名。

	$result = $otsClient->listTable([]);

更新表(UpdateTable)

表格存储支持更新表的预留读/写吞吐量(ReservedThroughput)、配置信息(TableOptions)以及 stream配置(StreamSpecification)

关于 ReservedThroughput、TableOptions 以及 StreamSpecification,在本章开始的“创建表”部分已经有过介绍。ReservedThroughput 的调整有时间间隔限制,目前为 1 分钟。

接口

    /**
     * 更新一个表,包括这个表的预留读写吞吐量,配置信息,stream配置。
     * 这个API可以用来上调或者下调表的预留读写吞吐量。
     * API说明:https://help.aliyun.com/document_detail/27315.html
     * @api
     * @param [] $request 请求参数
     * @return [] 请求返回 
     * @throws OTSClientException 当参数检查出错或服务端返回校验出错时
     * @throws OTSServerException 当OTS服务端返回错误时
     */
    public function updateTable(array $request);

请求格式


$result = $client->updateTable([
    'table_name' => '<string>',         // REQUIRED
    '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>
    ]
]);

请求格式说明
  • 和 CreateTable的区别只有tableMeta. 除了TableMeta以外都是可以更新的,而且含义和CreateTable保持一致。同时除了table_name外,都是可选的。
  • table_name 表名(必须设置)。
  • 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 数据的过期时间,较早的修改记录将会被删除,单位小时
结果格式
[
    'capacity_unit_details' => [
        'capacity_unit' => [
            'read' => <integer>,
            'write' => <integer>
        ],
        'last_increase_time' => <integer>,
        'last_decrease_time' => <integer>
    ],
    'table_options' => [
        'time_to_live' => <integer>,
        'max_versions' => <integer>,
        'deviation_cell_version_in_sec => <integer>
    ],
    'stream_details' => [
        'enable_stream' => true || false,
        'stream_id' => '<string>',
        'expiration_time' => <integer>,
        'last_enable_time' => <integer>
    ]
]

结果格式说明
  • capacity_unit_details 表的预留读/写吞吐量配置,与计费相关。
    • capacity_unit 当预留读/写吞吐量大于 0 时,会按照预留量和持续时间进行计费,超出预留的部分进行按量计费。默认预留读写吞吐量为 0,即完全按量计费,如果要设置为大于 0 的值,请仔细阅读表格存储的计费相关文档,以免产生未期望的费用。容量型实例的预留读/写吞吐量只能设置为 0,不允许预留。
      • read 预留读吞吐量
      • write 预留写吞吐量
    • last_increase_time 最近一次上调该表的预留读/写吞吐量设置的时间,使用 UTC 秒数表示。
    • last_decrease_time 最近一次下调该表的预留读/写吞吐量设置的时间,使用 UTC 秒数表示。
  • table_options TableOptions 包含表的 TTL、MaxVersions 和 MaxTimeDeviation 配置。和请求一致。
  • stream_details 表的stream信息。
    • enable_stream 该表是否打开stream
    • stream_id 该表的stream的id
    • expiration_time 该表的stream的过期时间,较早的修改记录将会被删除,单位小时
    • last_enable_time 该stream的打开的时间
示例

更新表的 CU 值为读 1,写 2。

    $result = $client->updateTable([
        'table_name' => 'SampleTable',
        'reserved_throughput' => [         
            'capacity_unit' => [
                'read' => 1,            // 可以单独更新读或者写
                'write' => 2
            ]
        ]
    ]);

更新表的TTL为一天(86400),保留版本2, 最大偏差10s.

    $result = $client->updateTable([
        'table_name' => 'SampleTable',
        'table_options' => [ 
            'time_to_live' => 86400,   
            'max_versions' => 2,    
            'deviation_cell_version_in_sec' => 10  
        ]
    ]);

打开表的Stream, 并设置过期时间24小时。

    $result = $client->updateTable([
        'table_name' => 'SampleTable',
        'stream_spec' => [
            'enable_stream' => true,
            'expiration_time' => 24
        ]
    ]);

查询表描述信息(DescribeTable)

DescribeTable 接口可以查询表的结构信息(TableMeta)、配置信息(TableOptions)、预留读/写吞吐量的情况(ReservedThroughputDetails),stream设置信息(StreamDetails)。 TableMeta 和 TableOptions 在“建表”一节已经有过介绍,ReservedThroughputDetails 除了包含表的预留吞吐量的值外,还包括最近一次上调或者下调的时间。 StreamDetails 包含了stream的详细信息。

接口
    /**
     * 获取一个表的信息,包括主键设计以及预留读写吞吐量信息。
     * API说明:https://help.aliyun.com/document_detail/27316.html
     * @api
     * @param [] $request 请求参数
     * @return [] 请求返回 
     * @throws OTSClientException 当参数检查出错或服务端返回校验出错时
     * @throws OTSServerException 当OTS服务端返回错误时
     */
    public function describeTable(array $request); 
请求格式
$result = $client->describeTable([
     'table_name' => '<string>', // REQUIRED
]);
请求格式说明
  • table_name 表名。
结果格式
[
    'table_meta' => [
        'table_name' => '<string>',
        'primary_key_schema' => [
            ['<string>', <PrimaryKeyType>],
            ['<string>', <PrimaryKeyType>, <PrimaryKeyOption>]
        ]
    ],
    'capacity_unit_details' => [
        'capacity_unit' => [
            'read' => <integer>,
            'write' => <integer>
        ],
        'last_increase_time' => <integer>,
        'last_decrease_time' => <integer>
    ],
    'table_options' => [
        'time_to_live' => <integer>,
        'max_versions' => <integer>,
        'deviation_cell_version_in_sec => <integer>
    ],
    'stream_details' => [
        'enable_stream' => true || false,
        'stream_id' => '<string>',
        'expiration_time' => <integer>,
        'last_enable_time' => <integer>
    ]
]

结果格式说明
  • table_meta TableMeta 包含表名和表的主键定义,和创建表时的定义是一样的。
  • capacity_unit_details 表的预留读/写吞吐量配置,与计费相关。
    • capacity_unit 当预留读/写吞吐量大于 0 时,会按照预留量和持续时间进行计费,超出预留的部分进行按量计费。默认预留读写吞吐量为 0,即完全按量计费,如果要设置为大于 0 的值,请仔细阅读表格存储的计费相关文档,以免产生未期望的费用。容量型实例的预留读/写吞吐量只能设置为 0,不允许预留。
      • read 预留读吞吐量
      • write 预留写吞吐量
    • last_increase_time 最近一次上调该表的预留读/写吞吐量设置的时间,使用 UTC 秒数表示。
    • last_decrease_time 最近一次下调该表的预留读/写吞吐量设置的时间,使用 UTC 秒数表示。
  • 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_details 表的stream信息。
    • enable_stream 该表是否打开stream
    • stream_id 该表的stream的id
    • expiration_time 该表的stream的过期时间,较早的修改记录将会被删除,单位小时
    • last_enable_time 该stream的打开的时间
示例

获取表的描述信息。

    $result = $client->describeTable([
         'table_name' => 'mySampleTable',
    ]);
    var_dump($result);

删除表(DeleteTable)

删除本实例下指定的表。

接口
     /**
     * 根据表名删除一个表。
     * API说明:https://help.aliyun.com/document_detail/27314.html
     * @api
     * @param [] $request 请求参数
     * @return [] 返回为空。DeleteTable成功时不返回任何信息,这里返回一个空的array,与其他API保持一致。
     * @throws OTSClientException 当参数检查出错或服务端返回校验出错时
     * @throws OTSServerException 当OTS服务端返回错误时
     */
    public function deleteTable(array $request);
请求格式
$result = $client->deleteTable([
     'table_name' => '<string>', // REQUIRED
]);
请求格式说明

table_name 表名。

结果格式
    []
结果格式说明

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

示例

删除表。

$result = $otsClient->deleteTable([
    'table_name' => 'MyTable'
]);

指定大小计算分片(ComputeSplitsBySize)

将全表数据逻辑上划分成接近指定大小的若干分片,返回这些分片之间的分割点以及分片所在机器的提示。一般用于计算引擎规划并发度等执行计划。

接口
    /**
     * 将全表的数据在逻辑上划分成接近指定大小的若干分片,返回这些分片之间的分割点以及分片所在机器的提示。
     * 一般用于计算引擎规划并发度等执行计划。
     * API说明:https://help.aliyun.com/document_detail/53813.html
     * @api
     * @param [] $request 请求参数。
     * @return [] 请求返回
     * @throws OTSClientException 当参数检查出错或服务端返回校验出错时
     * @throws OTSServerException 当OTS服务端返回错误时
     */
    public function computeSplitPointsBySize(array $request)
请求格式

$result = $client->ComputeSplitsBySize([
    'table_name' => '<string>', // REQUIRED
    'split_size' => <integer>   // REQUIRED
]);

请求格式说明
  • table_name 表名。
  • split_size 每个分片的近似大小,以百兆为单位。
结果格式
[
    'consumed' => [
        'capacity_unit' => [
            'read' => <integer>,
            'write' => <integer>
        ]
    ],
    'primary_key_schema' => [
        ['<string>', <PrimaryKeyType>],
        ['<string>', <PrimaryKeyType>, <PrimaryKeyOption>]
    ]
    'splits' => [
        [ 
            'lower_bound' => [
                ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>],
                ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
            ],
            'upper_bound' => [
                ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>],
                ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
            ],
            'location' => '<string>'
        ],
        // ...
    ]
]
结果格式说明
  • consumed 本次操作消耗服务能力单元的值。
    • capacity_unit 使用的读写单元量
      • read 读吞吐量
      • write 写吞吐量
  • primary_key_schema 表的主键定义,与建表时给出的 Schema 相同。
  • splits 分片之间的分割点。
    • lower_bound 主键的区间最小值。注:可以传递给getRange使用。
      • 每一项的顺序是 主键名,主键值PrimaryKeyValue, 主键类型PrimaryKeyType
      • PrimaryKeyType可以是INTEGER,STRING(UTF-8编码字符串),BINARY,INF_MIN(-inf), INF_MAX(inf)五种,分别用PrimaryKeyTypeConst::CONST_INTEGER,PrimaryKeyTypeConst::CONST_STRING,PrimaryKeyTypeConst::CONST_BINARY,PrimaryKeyTypeConst::CONST_INF_MIN,PrimaryKeyTypeConst::CONST_INF_MAX表示。
    • upper_bound 主键的区间最大值。格式同上。
    • location 分割点所在机器的提示。可以为空
示例

指定大小计算分片

    $result = $client->ComputeSplitsBySize([
        'table_name' => 'MyTable', 
        'split_size' => 1
    ]);
    foreach($result['splits'] as $split) {
        print_r($split['location']);    
        print_r($split['lower_bound']);    
        print_r($split['upper_bound']);    
    }