主键列自增

注意事项

写入数据到带有自增主键列的表时，请务必返回并记录自增列的值，用于后续数据更新或者数据读取。

前提条件

已初始化Client。具体操作，请参见初始化OTSClient。

使用方法

1. 创建表时，将非分区键的主键列设置为自增列。

   只有整型的主键列才能设置为自增列，系统自动生成的自增列值为64位的有符号长整型。

2. 写入数据时，无需为自增列设置具体值，只需将自增列的值设置为占位符。

   如果需要获取写入数据后系统自动生成的自增列的值，将ReturnType设置为ReturnTypeConst::CONST_PK，可以在数据写入成功后返回自增列的值。

   读取数据时，需要完整的主键值。通过设置PutRow、UpdateRow或者BatchWriteRow中的ReturnType为ReturnTypeConst::CONST_PK可以获取完整的主键值。

   读取数据时，如果已记录完整的主键，您可以使用读取单行数据或者批量读取数据方式读取数据；如果未记录自增主键列的值，您可以使用范围读取数据方式按照第一个主键列确定范围读取数据。

   说明

   要更新已存在的行数据时，如果未记录自增主键列的值，请先通过GetRange接口获取要更新的行主键信息，然后再进行数据更新。

示例

主键自增列功能主要涉及创建表（CreateTable）和写数据（PutRow、UpdateRow和BatchWriteRow）两类接口。

1. 创建表

   创建表时，只需将自增的主键属性设置为AUTO_INCR。

   以下示例用于创建数据表时配置主键自增列。该表的主键为PK_1（String类型）、PK_2（Integer类型），其中PK_1主键列为分区键，PK_2主键列为自增列。

   function createTable($otsClient) 
   {
       $request = [
           'table_meta' => [
               'table_name' => 'table_name',       //设置数据表名称。
               'primary_key_schema' => [
                   ['PK_1', PrimaryKeyTypeConst::CONST_STRING],    //第一个主键列（又叫分区键）名称为PK_1, 类型为STRING。
                   ['PK_2', PrimaryKeyTypeConst::CONST_INTEGER, PrimaryKeyOptionConst::CONST_PK_AUTO_INCR]
                   //第二个主键列名称为PK_2, 类型为INTEGER, 并且设置为自增列。
               ]
           ],
           'reserved_throughput' => [
               'capacity_unit' => [         //预留读写吞吐量设置为0个读CU和0个写CU。
                   'read' => 0,
                   'write' => 0
               ]
           ],
           'table_options' => [
               'time_to_live' => -1,             //设置为数据永不过期。
               'max_versions' => 1,              //只保存一个版本。
               'deviation_cell_version_in_sec' => 86400   //数据有效版本偏差，单位秒。
           ]
       ];
       $otsClient->createTable($request);
   }                    

2. 写数据

   写入数据时，无需为自增列设置具体值，只需将自增列的值设置为占位符AUTO_INCR。

   function putRow($otsClient)
   {
       $row = [
           'table_name' => 'table_name',
           'primary_key' => [
               ['PK_1', 'Hangzhou'],                      //主键名和主键值，此处为list。
               ['PK_2', null, PrimaryKeyTypeConst::CONST_PK_AUTO_INCR]    //主键自增列，此处无需填入具体值，只需要一个占位符PrimaryKeyTypeConst::CONST_PK_AUTO_INCR，表格存储会自动生成此值。
           ],
           'attribute_columns' => [              //属性列，此处为list。
               ['name', 'John'],                  //[属性名, 属性值, 属性类型, 时间戳]，未设置时可以忽略。
               ['age', 20],
               ['address', 'Alibaba'],
               ['product', 'OTS'],
               ['married', false]
           ],
           'return_content' => [
               'return_type' => ReturnTypeConst::CONST_PK     //返回自增列的主键值需要设置return_type。
           ]
       ];
       $ret = $otsClient->putRow($row);
       print_r($ret);
   
       $primaryKey = $ret['primary_key'];   //此处获取到的primaryKey可以传递给GetRow、UpdateRow、DeleteRow等API使用。
       return $primaryKey;
   }