主键列自增功能是表格存储新推出的一个功能,PHP SDK 4.0.0 版本开始支持。

主键列自增功能是指若用户指定某一列主键为自增列,在其写入数据时,表格存储会自动为用户在这一列产生一个新的值,且这个值为同一个分区键下该列的最大值。主要用于系统设计中需要使用主键列自增功能的场景,例如电商网站的商品 ID、大型网站的用户 ID、论坛帖子的 ID、聊天工具的消息 ID 等。

特点

  • 表格存储目前支持多个主键,第一个主键为分区键,分区键上不允许使用主键列自增功能。
  • 除了分区键外,其余主键中的任意一个都可以被设置为递增列。
  • 由于是在分区键基础上递增,所以主键列自增是分区键级别的自增。
  • 对于每张表,目前只允许设置一个主键列为自增列。
  • 自动生成地自增列为 64 位的有符号长整型。

接口

主键自增列功能主要涉及两类接口,创建表和写数据。

  • 创建表

    创建表时,只需将需要自增的主键属性设置为 PrimaryKeyOptionConst::CONST_PK_AUTO_INCR。

    相关接口:CreateTable。

    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);
    }
    
    • 第一个主键是分区键,不能设置为自增列。
    • 只有整数类型的列才可以设置为自增列。
    • 每张表只能设置一个主键自增列。
  • 写数据

    写入数据时,只需将自增列的值为设置为占位符 PrimaryKeyTypeConst::CONST_PK_AUTO_INCR。

    相关接口:PutRow/UpdateRow/BatchWriteRow。

    function putRow($otsClient)
    {
        $row = [
            'table_name' => 'table_name',
            'primary_key' => [
                ['PK_1', 'Hangzhou'],                      // 主键名,主键值, 注意是个list
                ['PK_2', null, PrimaryKeyTypeConst::CONST_PK_AUTO_INCR]    // 主键递增列,这个值是TableStore产生的,用户在这里不需要填入真实值,只需要一个占位符: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;
    }
    
    
    • 写入数据时,主键自增列不需要填值,只需填充占位符即可。
    • 如果用户想获取向表格存储写入数据后自动生成的主键值,可以将 ReturnType 设置为 ReturnTypeConst::CONST_PK,这样就能在写入成功后返回主键值。