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

如果需要了解表格存储各场景的应用案例,请参见快速玩转Tablestore入门与实战

前提条件

  • 已初始化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);