表格存储提供了PutRow、GetRow、UpdateRow和DeleteRow等单行操作的接口。

如需了解表格存储各场景的应用案例,请参见适用场景

前提条件

  • 已初始化Client,详情请参见初始化
  • 已创建数据表并写入数据。

插入一行数据(PutRow)

PutRow接口用于新写入一行数据。如果该行已存在,则先删除原行数据(原行的所有列以及所有版本的数据),再写入新行数据。

  • 接口
        /**
         * 写入一行数据。如果该行已经存在,则覆盖原有数据。返回该操作消耗的CU。
          * @api
         * @param [] $request 请求参数。
         * @return [] 请求返回。 
         * @throws OTSClientException 当参数检查出错或服务端返回校验出错时抛出异常。
         * @throws OTSServerException 当OTS服务端返回错误时抛出异常。
         */
        public function putRow(array $request); 
                
  • 请求参数
    参数 说明
    table_name 数据表名称。
    condition 使用条件更新,可以设置原行的存在性条件或者原行中某列的列值条件,详情请参见条件更新
    • row_existence:行存在性条件。
      说明
      • RowExistenceExpectationConst::CONST_IGNORE表示无论此行是否存在均会插入新数据,如果之前行已存在,则写入数据时会覆盖原有数据。
      • RowExistenceExpectationConst::CONST_EXPECT_EXIST表示只有此行存在时才会插入新数据,写入数据时会覆盖原有数据。
      • RowExistenceExpectationConst::CONST_EXPECT_NOT_EXIST表示只有此行不存在时才会插入数据。
    • column_condition:列条件。
    primary_key 行的主键。
    说明
    • 设置的主键个数和类型必须和数据表的主键个数和类型一致。
    • 当主键为自增列时,只需将自增列的值设置为占位符,详情请参见主键列自增
    • 数据表可包含1个~4个主键列。主键列是有顺序的,与用户添加的顺序相同,例如PRIMARY KEY(A, B, C)与PRIMARY KEY(A, C, B)是不同的两个主键结构。表格存储会按照主键的大小为行排序,具体参见表格存储数据模型和查询操作
    • 每一项的顺序是主键名、主键值PrimaryKeyValue、主键类型PrimaryKeyType(可选)。
    • PrimaryKeyValue可以是整数、二进制和字符串。
    • PrimaryKeyType可以是INTEGER、STRING(UTF-8编码字符串)、BINARY、PK_AUTO_INCR(主键列自增)四种,分别用PrimaryKeyTypeConst::CONST_INTEGER,PrimaryKeyTypeConst::CONST_STRING,PrimaryKeyTypeConst::CONST_BINARY,PrimaryKeyTypeConst::CONST_PK_AUTO_INCR表示,对于INTEGER和STRING,可以省略,其它类型不可省略。
    attribute_columns 行的属性列。
    • 每一项的顺序是属性名、属性值ColumnValue、属性类型ColumnType(可选)、时间戳(可选)。
    • ColumnType可以是INTEGER、STRING(UTF-8编码字符串)、BINARY、BOOLEAN、DOUBLE五种,分别用ColumnTypeConst::CONST_INTEGER、ColumnTypeConst::CONST_STRING、ColumnTypeConst::CONST_BINARY、ColumnTypeConst::CONST_BOOLEAN、ColumnTypeConst::CONST_DOUBLE表示,其中BINARY不可省略,其他类型都可以省略,或者设置为null。
    • 时间戳即数据的版本号,详情请参见数据版本和生命周期

      数据的版本号可以由系统自动生成或者自定义,如果不设置此参数,则默认由系统自动生成。

      • 当由系统自动生成数据的版本号时,系统默认将当前时间的毫秒单位时间戳(从1970-01-01 00:00:00 UTC计算起的毫秒数)作为数据的版本号。
      • 当自定义数据的版本号时,版本号需要为64位的毫秒单位时间戳且在有效版本范围内。
    return_content 表示返回类型。

    return_type:设置为ReturnTypeConst::CONST_PK,表示返回主键值,主要用于主键列自增场景。

  • 请求格式
    $result = $client->putRow([
        'table_name' => '<string>', //设置数据表名称。
        'condition' => [
            'row_existence' => <RowExistence>,   
            'column_condition' => <ColumnCondition>
        ],
        'primary_key' => [                              //设置主键。
            ['<string>', <PrimaryKeyValue>], 
            ['<string>', <PrimaryKeyValue>],
            ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
        ],  
        'attribute_columns' => [         //设置属性列。
                ['<string>', <ColumnValue>], 
                ['<string>', <ColumnValue>, <ColumnType>],
                ['<string>', <ColumnValue>, <ColumnType>, <integer>]
        ],
        'return_content' => [
            'return_type' => <ReturnType>
        ]
    ]);         
  • 响应参数
    参数 说明
    consumed 本次操作消耗服务能力单元的值。
    capacity_unit表示使用的读写能力单元。
    • read:读吞吐量
    • write:写吞吐量
    primary_key 主键的值,和请求时一致。
    说明 当在请求中设置return_type为ReturnTypeConst::CONST_PK时,会返回完整的主键,主要用于主键列自增。
    attribute_columns 属性列的值,和请求时一致,目前为空。
  • 响应格式
    [
        'consumed' => [
            'capacity_unit' => [
                'read' => <integer>,
                'write' => <integer>
            ]
        ],
        'primary_key' => [ 
            ['<string>', <PrimaryKeyValue>], 
            ['<string>', <PrimaryKeyValue>],
            ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
        ],  
        'attribute_columns' => []
    ]        
  • 示例1

    写入10列属性列,每列写入1个版本,由系统自动生成数据的版本号(时间戳)。

    $attr = array();
    for($i = 0; $i < 10; $i++) {
        $attr[] = ['Col'. $i, $i]; 
    }
    $request = [
        'table_name' => 'MyTable',
        'condition' => RowExistenceExpectationConst::CONST_IGNORE, //condition可以为IGNORE、EXPECT_EXIST和EXPECT_NOT_EXIST。
        'primary_key' => [ //设置主键。
            ['PK0', 123],
            ['PK1', 'abc']
        ],
        'attribute_columns' => $attr
    ];
    $response = $otsClient->putRow ($request);
                
  • 示例2

    写入10列属性列,每列写入3个版本,自定义数据的版本号(时间戳)。

    $attr = array();
    $timestamp = getMicroTime();
    for($i = 0; $i < 10; $i++) {
        for($j = 0; $j < 3; $j++) {
            $attr[] = ['Col'. $i, $j, null, $timestamp+$j];
        }
    }
    $request = [
        'table_name' => 'MyTable',
        'condition' => RowExistenceExpectationConst::CONST_IGNORE, //condition可以为IGNORE、EXPECT_EXIST和EXPECT_NOT_EXIST。
        'primary_key' => [ //设置主键。
            ['PK0', 123],
            ['PK1', 'abc']
        ],
        'attribute_columns' => $attr
    ];
    $response = $otsClient->putRow ($request);
                
  • 示例3

    期望原行不存在时,写入10列属性列,每列写入3个版本,自定义数据的版本号(时间戳)。

    $attr = array();
    $timestamp = getMicroTime();
    for($i = 0; $i < 10; $i++) {
        for($j = 0; $j < 3; $j++) {
            $attr[] = ['Col'. $i, $j, null, $timestamp+$j];
        }
    }
    $request = [
        'table_name' => 'MyTable',
        'condition' => RowExistenceExpectationConst::CONST_EXPECT_NOT_EXIST, //设置期望原行不存在时,写入数据。
        'primary_key' => [ //设置主键。
            ['PK0', 123],
            ['PK1', 'abc']
        ],
        'attribute_columns' => $attr
    ];
    $response = $otsClient->putRow ($request);
                
  • 示例4

    期望原行存在且Col0列的值大于100时,写入10列属性列,每列写入3个版本,自定义数据的版本号(时间戳)。

    $attr = array();
    $timestamp = getMicroTime();
    for($i = 0; $i < 10; $i++) {
        for($j = 0; $j < 3; $j++) {
            $attr[] = ['Col'. $i, $j, null, $timestamp+$j];
        }
    }
    $request = [
        'table_name' => 'MyTable',
        'condition' => [
            'row_existence' => RowExistenceExpectationConst::CONST_EXPECT_EXIST,//期望原行存在。
            'column_condition' => [                  //使用条件更新,满足条件则更新。
                'column_name' => 'Col0',
                'value' => 100,
                'comparator' => ComparatorTypeConst::CONST_GREATER_THAN
            ]
        ,
        'primary_key' => [ //设置主键。
            ['PK0', 123],
            ['PK1', 'abc']
        ],
        'attribute_columns' => $attr
    ];
    $response = $otsClient->putRow ($request);
                

读取一行数据(GetRow)

GetRow接口用于读取一行数据。

读取的结果可能有如下两种:
  • 如果该行存在,则返回该行的各主键列以及属性列。
  • 如果该行不存在,则返回中不包含行,并且不会报错。
  • 接口
        /**
         * 读取一行数据。
         * @api
         * @param [] $request 请求参数。
         * @return [] 请求返回。 
         * @throws OTSClientException 当参数检查出错或服务端返回校验出错时抛出异常。
         * @throws OTSServerException 当OTS服务端返回错误时抛出异常。
         */
        public function getRow(array $request);
                
  • 请求参数
    参数 说明
    table_name 数据表名称。
    primary_key 行的主键。
    说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。
    max_versions 最多读取的版本数。
    说明 max_versions与time_range必须至少设置一个。
    • 如果仅设置max_versions,则返回所有版本中从新到旧最多指定数量版本的数据。
    • 如果仅设置time_range,则返回该范围内所有数据或指定版本数据。
    • 如果同时设置max_versions和time_range,则返回版本号范围内从新到旧最多指定数量版本的数据。
    time_range 读取版本号范围或特定版本号的数据。详情请参见TimeRange
    说明 max_versions与time_range必须至少设置一个。
    • 如果仅设置max_versions,则返回所有版本中从新到旧最多指定数量版本的数据。
    • 如果仅设置time_range,则返回该范围内所有数据或指定版本数据。
    • 如果同时设置max_versions和time_range,则返回版本号范围内从新到旧最多指定数量版本的数据。
    • 如果查询一个范围的数据,则需要设置start_time和end_time。start_time和end_time分别表示起始时间戳和结束时间戳,范围为前闭后开区间,即[start_time, end_time)。
    • 如果查询特定版本号的数据,则需要设置specific_time。specific_time表示特定的时间戳。

    specific_time和[start_time, end_time)中只需要设置一个。

    时间戳的单位为毫秒,最小值为0,最大值为INT64.MAX。

    columns_to_get 读取的列集合,列名可以是主键列或属性列。

    如果不设置返回的列名,则返回整行数据。

    说明
    • 查询一行数据时,默认返回此行所有列的数据。如果需要只返回特定行,可以通过设置columns_to_get参数限制。如果将col0和col1加入到columns_to_get中,则只返回col0和col1列的值。
    • 当columns_to_get和column_filter同时使用时,执行顺序是先获取columns_to_get指定的列,再在返回的列中进行条件过滤。
    start_column 读取的起始列,主要用于宽行读,返回的结果中包含当前起始列。

    列的顺序按照列名的字典序排序。例如一张表有“a”,”b”,”c”三列,读取时设置start_column为“b”,则会从”b”列开始读,返回”b”,”c”两列。

    详情请参见宽行读取

    end_column 读取时的结束列,主要用于宽行读,返回的结果中不包含当前结束列。

    列的顺序按照列名的字典序排序。例如一张表有”a”,”b”,”c”三列,读取时指定end_column为“b”,则读到”b”列时会结束,返回”a”列。

    token 宽行读取时下一次读取的起始位置,暂不可用。
    column_filter 使用过滤器,在服务端对读取结果再进行一次过滤,只返回符合过滤器中条件的数据行,详情请参见过滤器
    说明 当columns_to_get和column_filter同时使用时,执行顺序是先获取columns_to_get指定的列,再在返回的列中进行条件过滤。
  • 请求格式
    $result = $client->getRow([
        'table_name' => '<string>',                     //设置数据表名称。
        'primary_key' => [                              //设置主键。
            ['<string>', <PrimaryKeyValue>], 
            ['<string>', <PrimaryKeyValue>],
            ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
        ], 
        'max_versions' => <integer>,
        'time_range' => [
            'start_time' => <integer>,
            'end_time' => <integer>,
            'specific_time' => <integer>
        ],
        'start_column' => '<string>',
        'end_column' => '<string>',
        'token' => '<string>',
        'columns_to_get' => [
            '<string>',
            '<string>',
            //...   
        ],
        'column_filter' =>  <ColumnCondition>
    ]);
                
  • 响应参数
    参数 说明
    consumed 本次操作消耗服务能力单元的值。
    capacity_unit表示使用的读写能力单元。
    • read:读吞吐量
    • write:写吞吐量
    primary_key 主键的值,和请求时一致。
    说明 如果该行不存在,则primary_key为空列表[]。
    attribute_columns 属性列的值。
    说明 如果该行不存在,则attribute_columns为空列表[]。
    • 每一项的顺序是属性名、属性值ColumnValue、属性类型ColumnType、时间戳。

      时间戳为64位整数,用于表示属性列数据的多个不同的版本。

    • 返回结果中的属性会按照属性名的字典序升序,属性的多个版本按时间戳降序。
    • 其顺序不保证与请求中的columns_to_get一致。
    next_token 宽行读取时下一次读取的位置,暂不可用。
  • 结果格式
    [
        'consumed' => [
            'capacity_unit' => [
                'read' => <integer>,
                'write' => <integer>
            ]
        ],
        'primary_key' => [ 
            ['<string>', <PrimaryKeyValue>], 
            ['<string>', <PrimaryKeyValue>],
            ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
        ],  
        'attribute_columns' => [
                ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                ['<string>', <ColumnValue>, <ColumnType>, <integer>]
        ],
        'next_token' => '<string>'
    ]
                
  • 示例1

    读取一行,设置读取最新版本的数据和读取的列。

    $request = [
        'table_name' => 'MyTable',
        'primary_key' => [ //设置主键。
            ['PK0', 123],
            ['PK1', 'abc']
        ],
        'max_versions' => 1,                     //设置读取最新版本。
        'columns_to_get' => ['Col0']             //设置读取的列。
    ];
    $response = $otsClient->getRow ($request);
                
  • 示例2

    在读取一行数据时使用过滤器。

    $request = [
        'table_name' => 'MyTable',
        'primary_key' => [ //设置主键。
            ['PK0', 123],
            ['PK1', 'abc']
        ],
        'max_versions' => 1,                     //设置读取最新版本。
        'column_filter' => [                     //设置过滤器,当Col0列的值为0时,返回该行。
            'column_name' => 'Col0',
            'value' => 0,
            'comparator' => ComparatorTypeConst::CONST_EQUAL,
            'pass_if_missing' => false          //如果Col0列不存在,则不返回该行。
        ]
    ];
    $response = $otsClient->getRow ($request);
                

更新一行数据(UpdateRow)

UpdateRow接口用于更新一行数据,可以增加和删除一行中的属性列,删除属性列指定版本的数据,或者更新已存在的属性列的值。如果更新的行不存在,则新增一行数据。
说明 当UpdateRow请求中只包含删除指定的列且该行不存在时,则该请求不会新增一行数据。
  • 接口
        /**
         * 更新一行数据。
         * @api
         * @param [] $request 请求参数。
         * @return [] 请求返回。
         * @throws OTSClientException 当参数检查出错或服务端返回校验出错时抛出异常。
         * @throws OTSServerException 当OTS服务端返回错误时抛出异常。
         */
        public function updateRow(array $request);
                
  • 请求参数
    参数 说明
    table_name 数据表名称。
    condition 使用条件更新,可以设置原行的存在性条件或者原行中某列的列值条件,详情请参见条件更新
    primary_key 行的主键。
    说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。
    update_of_attribute_columns 更新的属性列。
    • 增加或更新数据时,需要设置属性名、属性值、属性类型(可选)、时间戳(可选)。

      时间戳即数据的版本号,可以由系统自动生成或者自定义,如果不设置此参数,则默认由系统自动生成。详情请参见数据版本和生命周期

      • 当由系统自动生成数据的版本号时,系统默认将当前时间的毫秒单位时间戳(从1970-01-01 00:00:00 UTC计算起的毫秒数)作为数据的版本号。
      • 当自定义数据的版本号时,版本号需要为64位的毫秒单位时间戳且在有效版本范围内。
    • 删除属性列特定版本的数据时,只需要设置属性名和时间戳。

      时间戳是64位整数,单位为毫秒,表示某个特定版本的数据。

    • 删除属性列时,只需要设置属性名。
      说明 删除一行的全部属性列不等同于删除该行,如果需要删除该行,请使用DeleteRow操作。
    return_content 表示返回类型。

    return_type:目前只需要设置为ReturnTypeConst::CONST_PK,表示返回主键值,主要用于主键列自增场景。

  • 请求格式
    $result = $client->updateRow([
        'table_name' => '<string>', //设置数据表名称。
        'condition' => [
            'row_existence' => <RowExistence>,
            'column_condition' => <ColumnCondition>
        ],
        'primary_key' => [                              //设置主键。
            ['<string>', <PrimaryKeyValue>], 
            ['<string>', <PrimaryKeyValue>],
            ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
        ], 
        'update_of_attribute_columns' => [         //设置更新的属性列。
            'PUT' => [
                ['<string>', <ColumnValue>], 
                ['<string>', <ColumnValue>, <ColumnType>],
                ['<string>', <ColumnValue>, <ColumnType>, <integer>]
            ],
            'DELETE' => [
                ['<string>', <integer>], 
                ['<string>', <integer>], 
                ['<string>', <integer>], 
                ['<string>', <integer>]
            ],
            'DELETE_ALL' => [
                '<string>',
                '<string>',
                '<string>',
                '<string>'
            ],        
        ],
        'return_content' => [
            'return_type' => <ReturnType>
        ]
    ]);
                
  • 响应参数
    参数 说明
    consumed 本次操作消耗服务能力单元的值。
    capacity_unit表示使用的读写能力单元。
    • read:读吞吐量
    • write:写吞吐量
    primary_key 主键的值,和请求时一致。
    说明 当在请求中设置return_type为ReturnTypeConst::CONST_PK时,会返回完整的主键,主要用于主键列自增。
    attribute_columns 属性列的值,和请求时一致,目前为空。
  • 结果格式
    [
        'consumed' => [
            'capacity_unit' => [
                'read' => <integer>,
                'write' => <integer>
            ]
        ],
        'primary_key' => [ 
            ['<string>', <PrimaryKeyValue>], 
            ['<string>', <PrimaryKeyValue>],
            ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
        ],  
        'attribute_columns' => []
    ]
                
  • 示例1

    更新一些列,删除某列的某一版本,删除某列。

    $request = [
        'table_name' => 'MyTable',
        'condition' => RowExistenceExpectationConst::CONST_IGNORE,
        'primary_key' => [ //设置主键。
            ['PK0', 123],
            ['PK1', 'abc']
        ],
        'update_of_attribute_columns' => [
            'PUT' => [                       //更新一些列。
                ['Col0', 100],
                ['Col1', 'Hello'],
                ['Col2', 'a binary', ColumnTypeConst::CONST_BINARY],
                ['Col3', 100, null, 1526418378526]
            ],
            'DELETE' => [                    //删除某列的某一版本。
                ['Col10', 1526418378526]
            ],
            'DELETE_ALL' => [
                'Col11'                      //删除某一列。
            ]
        ]
    ];
    $response = $otsClient->updateRow($request);
                
  • 示例2

    设置更新的条件。

    $request = [
        'table_name' => 'MyTable',
        'primary_key' => [ //设置主键。
            ['PK0', 123],
            ['PK1', 'abc']
        ],
        'condition' => [
            'row_existence' => RowExistenceExpectationConst::CONST_EXPECT_EXIST, //期望原行存在。
            'column_filter' => [                                                 //当Col0列的值大于100时更新数据。
                'column_name' => 'Col0',
                'value' => 100,
                'comparator' => ComparatorTypeConst::CONST_GREATER_THAN
            ]
        ],    
        'update_of_attribute_columns' => [
            'PUT' => [                       //更新一些列。
                ['Col0', 100],
                ['Col1', 'Hello'],
                ['Col2', 'a binary', ColumnTypeConst::CONST_BINARY],
                ['Col3', 100, null, 1526418378526]
            ],
            'DELETE' => [                    //删除某列的某一版本。
                ['Col10', 1526418378526]
            ],
            'DELETE_ALL' => [
                'Col11'                      //删除某一列。
            ]
        ]
    ];         

删除一行数据(DeleteRow)

DeleteRow接口用于删除一行数据。如果删除的行不存在,则不会发生任何变化。

  • 接口
        /**
         * 删除一行数据。
         * @api
         * @param [] $request 请求参数。
         * @return [] 请求返回。 
         * @throws OTSClientException 当参数检查出错或服务端返回校验出错时抛出异常。
         * @throws OTSServerException 当OTS服务端返回错误时抛出异常。
         */
        public function deleteRow(array $request);
                
  • 请求参数
    参数 说明
    table_name 数据表名称。
    condition 使用条件更新,可以设置原行的存在性条件或者原行中某列的列值条件,详情请参见条件更新
    primary_key 行的主键。
    说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。
    return_content 表示返回类型。

    return_type:目前只需要设置为ReturnTypeConst::CONST_PK,表示返回主键值,主要用于主键列自增场景。

  • 请求格式
    $result = $client->deleteRow([
        'table_name' => '<string>', //设置数据表名称。
        'condition' => [
            'row_existence' => <RowExistence>,
            'column_condition' => <ColumnCondition>
        ],
        'primary_key' => [                              //设置主键。
            ['<string>', <PrimaryKeyValue>], 
            ['<string>', <PrimaryKeyValue>],
            ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
        ],
        'return_content' => [
            'return_type' => <ReturnType>
        ]
    ]);
                
  • 响应参数
    参数 说明
    consumed 本次操作消耗服务能力单元的值。
    capacity_unit表示使用的读写能力单元。
    • read:读吞吐量
    • write:写吞吐量
    primary_key 主键的值,和请求时一致。
    说明 当在请求中设置return_type为ReturnTypeConst::CONST_PK时,会返回完整的主键,主要用于主键列自增。
    attribute_columns 属性列的值,和请求时一致,目前为空。
  • 结果格式
    [
        'consumed' => [
            'capacity_unit' => [
                'read' => <integer>,
                'write' => <integer>
            ]
        ],
        'primary_key' => [
            ['<string>', <PrimaryKeyValue>], 
            ['<string>', <PrimaryKeyValue>],
            ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
        ],
        'attribute_columns' => []
    ]
                
  • 示例1

    删除一行数据。

    $request = [
        'table_name' => 'MyTable',
        'condition' => RowExistenceExpectationConst::CONST_IGNORE,
        'primary_key' => [ //设置主键。
            ['PK0', 123],
            ['PK1', 'abc']
        ],
        'return_content' => [
            'return_type' => ReturnTypeConst::CONST_PK     //使用主键列自增时,可以设置return_type返回主键。
        ]
    ];
    $response = $otsClient->deleteRow($request);
                
  • 示例2

    设置删除条件。

    $request = [
        'table_name' => 'MyTable',
        'condition' => [
            'row_existence' => RowExistenceExpectationConst::CONST_EXPECT_EXIST, //期望原行存在。
            'column_filter' => [          //当Col0列的值大于100时删除数据。
                'column_name' => 'Col0',
                'value' => 100,
                'comparator' => ComparatorTypeConst::CONST_GREATER_THAN
            ],
        ],
        'primary_key' => [ //设置主键。
            ['PK0', 123],
            ['PK1', 'abc']
        ]
    ];
    $response = $otsClient->deleteRow ($request);