单行数据操作 - 表格存储 Tablestore

表格存储提供了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);