表格存储提供了PutRow、GetRow、UpdateRow和DeleteRow等单行操作的接口。
接口
单行数据操作包括PutRow、GetRow、UpdateRow和DeleteRow接口,详细说明请参见下表。
接口 | 说明 |
---|---|
GetRow | 读取一行数据。 |
PutRow | 新写入一行数据。如果该行已存在,则先删除旧行数据,再写入新行数据。 |
UpdateRow | 更新一行数据。可以增加、删除一行中的属性列,或者更新已存在的属性列的值。
如果更新的行不存在,则新增一行数据。但是当UpdateRow请求中只包含删除指定的列且该行不存在时,则该请求不会新增一行数据。 |
DeleteRow | 删除一行数据。
如果删除的行不存在,则不会发生任何变化。 |
使用
您可以使用如下语言的SDK实现单行数据操作。
插入一行数据(PutRow)
PutRow接口用于新写入一行数据。如果该行已存在,则先删除原行数据(原行的所有列以及所有版本的数据),再写入新行数据。
CU消耗说明
- 消耗的写CU为修改的行主键数据大小与属性列数据大小之和除以4 KB向上取整。
- 如果指定条件检查不为IGNORE,则消耗行主键数据大小除以4 KB向上取整的读CU。
- 如果操作不满足指定的行存在性检查条件,则操作失败并消耗1单位写CU和1单位读CU。
操作结果说明
- 如果操作成功,表格存储会返回操作消耗的服务能力单元(CU)。
说明 写入操作会根据指定的condition情况消耗一定的读CU。通过在单行写入请求中设置condition字段可以指定写入操作执行时,是否对行的存在性进行检查。condition有如下三种类型:
condition 说明 IGNORE 不做任何存在性检查。 EXPECT_EXIST 期望行存在。 - 如果该行存在,则操作成功。
- 如果该行不存在,则操作失败。
EXPECT_NOT_EXIST 期望行不存在。 - 如果该行不存在,则操作成功。
- 如果该行存在,则操作失败。
说明 condition为EXPECT_NOT_EXIST的DeleteRow、UpdateRow操作是无意义的,即删除一个不存在的行是无意义的。如果需要更新不存在的行可以使用PutRow操作。 - 如果操作发生错误,例如参数检查失败、单行数据量过多、行存在性检查失败等,表格存储会返回错误码。
参数
参数 | 说明 |
---|---|
tableName | 数据表名称。 |
primaryKey | 行的主键。
说明
|
condition | 使用条件更新,可以设置原行的存在性条件或者原行中某列的列值条件。更多信息,请参见条件更新。
说明
|
column | 行的属性列。
|
示例
- 示例1
写入10列属性列,每列写入1个版本,由系统自动生成数据的版本号(时间戳)。
private static void putRow(SyncClient client, String pkValue) { //构造主键。 PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder(); primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue)); PrimaryKey primaryKey = primaryKeyBuilder.build(); //设置数据表名称。 RowPutChange rowPutChange = new RowPutChange(TABLE_NAME, primaryKey); //加入一些属性列。 for (int i = 0; i < 10; i++) { rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(i))); } client.putRow(new PutRowRequest(rowPutChange)); }
- 示例2
写入10列属性列,每列写入3个版本,自定义数据的版本号(时间戳)。
private static void putRow(SyncClient client, String pkValue) { //构造主键。 PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder(); primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue)); PrimaryKey primaryKey = primaryKeyBuilder.build(); //设置数据表名称。 RowPutChange rowPutChange = new RowPutChange(TABLE_NAME, primaryKey); //加入一些属性列。 long ts = System.currentTimeMillis(); for (int i = 0; i < 10; i++) { for (int j = 0; j < 3; j++) { rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(j), ts + j)); } } client.putRow(new PutRowRequest(rowPutChange)); }
- 示例3
期望原行不存在时,写入10列属性列,每列写入3个版本,自定义数据的版本号(时间戳)。
private static void putRow(SyncClient client, String pkValue) { //构造主键。 PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder(); primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue)); PrimaryKey primaryKey = primaryKeyBuilder.build(); //设置数据表名称。 RowPutChange rowPutChange = new RowPutChange(TABLE_NAME, primaryKey); //设置条件更新,行条件检查为期望原行不存在。 rowPutChange.setCondition(new Condition(RowExistenceExpectation.EXPECT_NOT_EXIST)); //加入一些属性列。 long ts = System.currentTimeMillis(); for (int i = 0; i < 10; i++) { for (int j = 0; j < 3; j++) { rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(j), ts + j)); } } client.putRow(new PutRowRequest(rowPutChange)); }
- 示例4
期望原行存在且Col0列的值大于100时,写入10列属性列,每列写入3个版本,自定义数据的版本号(时间戳)。
private static void putRow(SyncClient client, String pkValue) { //构造主键。 PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder(); primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue)); PrimaryKey primaryKey = primaryKeyBuilder.build(); //设置数据表名称。 RowPutChange rowPutChange = new RowPutChange(TABLE_NAME, primaryKey); //设置条件更新,期望原行存在且Col0列的值大于100时写入数据。 Condition condition = new Condition(RowExistenceExpectation.EXPECT_EXIST); condition.setColumnCondition(new SingleColumnValueCondition("Col0", SingleColumnValueCondition.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100))); rowPutChange.setCondition(condition); //加入一些属性列。 long ts = System.currentTimeMillis(); for (int i = 0; i < 10; i++) { for (int j = 0; j < 3; j++) { rowPutChange.addColumn(new Column("Col" + i, ColumnValue.fromLong(j), ts + j)); } } client.putRow(new PutRowRequest(rowPutChange)); }
读取一行数据(GetRow)
GetRow接口用于读取一行数据。
CU消耗说明
GetRow操作不消耗写CU,消耗的读CU为读取的行主键的数据大小与实际读取的属性列数据大小之和,按4 KB向上取整。如果操作指定的行不存在,则消耗1单位读CU。
操作结果说明
- 如果该行存在,则返回该行的各主键列以及属性列。
- 如果该行不存在,则返回中不包含行,并且不会报错。
参数
参数 | 说明 |
---|---|
tableName | 数据表名称。 |
primaryKey | 行的主键。
说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。
|
columnsToGet | 读取的列集合,列名可以是主键列或属性列。
如果不设置返回的列名,则返回整行数据。 说明
|
maxVersions | 最多读取的版本数。
说明 maxVersions与timeRange必须至少设置一个。
|
timeRange | 读取版本号范围或特定版本号的数据。更多信息,请参见TimeRange。
说明 maxVersions与timeRange必须至少设置一个。
timestamp和[start, end)中只需要设置一个。 时间戳的单位为毫秒,最小值为0,最大值为Long.MAX_VALUE。 |
filter | 使用过滤器,在服务端对读取结果再进行一次过滤,只返回符合过滤器中条件的数据行。更多信息,请参见过滤器。
说明 当columnsToGet和filter同时使用时,执行顺序是先获取columnsToGet指定的列,再在返回的列中进行条件过滤。
|
示例
- 示例1
读取一行,设置读取最新版本的数据和读取的列。
private static void getRow(SyncClient client, String pkValue) { //构造主键。 PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder(); primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue)); PrimaryKey primaryKey = primaryKeyBuilder.build(); //读取一行数据,设置数据表名称。 SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(TABLE_NAME, primaryKey); //设置读取最新版本。 criteria.setMaxVersions(1); GetRowResponse getRowResponse = client.getRow(new GetRowRequest(criteria)); Row row = getRowResponse.getRow(); System.out.println("读取完毕,结果为: "); System.out.println(row); //设置读取某些列。 criteria.addColumnsToGet("Col0"); getRowResponse = client.getRow(new GetRowRequest(criteria)); row = getRowResponse.getRow(); System.out.println("读取完毕,结果为:"); System.out.println(row); }
- 示例2
在读取一行数据时使用过滤器。
private static void getRow(SyncClient client, String pkValue) { //构造主键。 PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder(); primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue)); PrimaryKey primaryKey = primaryKeyBuilder.build(); //读取一行数据,设置数据表名称。 SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(TABLE_NAME, primaryKey); //设置读取最新版本。 criteria.setMaxVersions(1); //设置过滤器,当Col0列的值为0时,返回该行。 SingleColumnValueFilter singleColumnValueFilter = new SingleColumnValueFilter("Col0", SingleColumnValueFilter.CompareOperator.EQUAL, ColumnValue.fromLong(0)); //如果Col0列不存在,则不返回该行。 singleColumnValueFilter.setPassIfMissing(false); criteria.setFilter(singleColumnValueFilter); GetRowResponse getRowResponse = client.getRow(new GetRowRequest(criteria)); Row row = getRowResponse.getRow(); System.out.println("读取完毕,结果为: "); System.out.println(row); }
- 示例3
读取一行中Col1列的数据,并对该列的数据执行正则过滤。
private static void getRow(SyncClient client, String pkValue) { SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(tableName); //构造主键。 PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder() .addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue)) .build(); criteria.setPrimaryKey(primaryKey); // 设置读取最新版本。 criteria.setMaxVersions(1); // 设置过滤器,当cast<int>(regex(Col1)) > 100时,返回该行。 RegexRule regexRule = new RegexRule("t1:([0-9]+),", VariantType.Type.VT_INTEGER); SingleColumnValueRegexFilter filter = new SingleColumnValueRegexFilter("Col1", regexRule,SingleColumnValueFilter.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100)); criteria.setFilter(filter); GetRowResponse getRowResponse = client.getRow(new GetRowRequest(criteria)); Row row = getRowResponse.getRow(); System.out.println("读取完毕,结果为: "); System.out.println(row); }
更新一行数据(UpdateRow)
CU消耗说明
- 消耗的写CU为修改的行主键数据大小与属性列数据大小之和除以4 KB向上取整。
操作中包含的需要删除的属性列,只有属性列的列名计入属性列数据大小。
- 如果指定条件检查不为IGNORE,则消耗行主键数据大小除以4 KB向上取整的读CU。
- 如果操作不满足指定的行存在性检查条件,则操作失败并消耗1单位写CU和1单位读CU。
参数
参数 | 说明 |
---|---|
tableName | 数据表名称。 |
primaryKey | 行的主键。
说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。
|
condition | 使用条件更新,可以设置原行的存在性条件或者原行中某列的列值条件。更多信息,请参见条件更新。 |
column | 更新的属性列。
|
示例
- 示例1
更新一些列,删除某列的某一版本数据,删除某列。
private static void updateRow(SyncClient client, String pkValue) { //构造主键。 PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder(); primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue)); PrimaryKey primaryKey = primaryKeyBuilder.build(); //设置数据表名称。 RowUpdateChange rowUpdateChange = new RowUpdateChange(TABLE_NAME, primaryKey); //更新一些列。 for (int i = 0; i < 10; i++) { rowUpdateChange.put(new Column("Col" + i, ColumnValue.fromLong(i))); } //删除某列的某一版本。 rowUpdateChange.deleteColumn("Col10", 1465373223000L); //删除某一列。 rowUpdateChange.deleteColumns("Col11"); client.updateRow(new UpdateRowRequest(rowUpdateChange)); }
- 示例2
设置更新的条件。
private static void updateRow(SyncClient client, String pkValue) { //构造主键。 PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder(); primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue)); PrimaryKey primaryKey = primaryKeyBuilder.build(); //设置数据表名称。 RowUpdateChange rowUpdateChange = new RowUpdateChange(TABLE_NAME, primaryKey); //设置条件更新,期望原行存在且Col0列的值大于100时更新数据。 Condition condition = new Condition(RowExistenceExpectation.EXPECT_EXIST); condition.setColumnCondition(new SingleColumnValueCondition("Col0", SingleColumnValueCondition.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100))); rowUpdateChange.setCondition(condition); //更新一些列。 for (int i = 0; i < 10; i++) { rowUpdateChange.put(new Column("Col" + i, ColumnValue.fromLong(i))); } //删除某列的某一版本。 rowUpdateChange.deleteColumn("Col10", 1465373223000L); //删除某一列。 rowUpdateChange.deleteColumns("Col11"); client.updateRow(new UpdateRowRequest(rowUpdateChange)); }
删除一行数据(DeleteRow)
DeleteRow接口用于删除一行数据。如果删除的行不存在,则不会发生任何变化。
CU消耗说明
- 消耗的写CU为删除的行主键数据大小除以4 KB向上取整。
- 如果指定条件检查不为IGNORE,则消耗行主键数据大小除以4 KB向上取整的读CU。
- 如果操作不满足指定的行存在性检查条件,则操作失败并消耗1单位写CU。
参数
参数 | 说明 |
---|---|
tableName | 数据表名称。 |
primaryKey | 行的主键。
说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。
|
condition | 支持使用条件更新,可以设置原行的存在性条件或者原行中某列的列值条件。更多信息,请参见条件更新。 |
示例
- 示例1
删除一行数据。
private static void deleteRow(SyncClient client, String pkValue) { //构造主键。 PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder(); primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue)); PrimaryKey primaryKey = primaryKeyBuilder.build(); //设置数据表名称。 RowDeleteChange rowDeleteChange = new RowDeleteChange(TABLE_NAME, primaryKey); client.deleteRow(new DeleteRowRequest(rowDeleteChange)); }
- 示例2
设置删除条件。
private static void deleteRow(SyncClient client, String pkValue) { //构造主键。 PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder(); primaryKeyBuilder.addPrimaryKeyColumn(PRIMARY_KEY_NAME, PrimaryKeyValue.fromString(pkValue)); PrimaryKey primaryKey = primaryKeyBuilder.build(); //设置数据表名称。 RowDeleteChange rowDeleteChange = new RowDeleteChange(TABLE_NAME, primaryKey); //设置条件更新,期望原行存在且Col0列的值大于100时删除该行。 Condition condition = new Condition(RowExistenceExpectation.EXPECT_EXIST); condition.setColumnCondition(new SingleColumnValueCondition("Col0", SingleColumnValueCondition.CompareOperator.GREATER_THAN, ColumnValue.fromLong(100))); rowDeleteChange.setCondition(condition); client.deleteRow(new DeleteRowRequest(rowDeleteChange)); }