表格存储提供了PutRow、GetRow、UpdateRow和DeleteRow等单行操作的接口。
如需了解表格存储各场景的应用案例,请参见适用场景。
前提条件
- 已初始化OTSClient,详情请参见初始化。
- 已创建数据表并写入数据。
插入一行数据(PutRow)
PutRow接口用于新写入一行数据。如果该行已存在,则先删除原行数据(原行的所有列以及所有版本的数据),再写入新行数据。
- 参数
参数 说明 tableName 数据表名称。 primaryKey 行的主键。 说明- 设置的主键个数和类型必须和数据表的主键个数和类型一致。
- 当主键为自增列时,只需将自增列的值设置为占位符,详情请参见主键列自增。
condition 使用条件更新,可以设置原行的存在性条件或者原行中某列的列值条件,详情请参见条件更新。 说明- RowExistenceExpectation.IGNORE表示无论此行是否存在均会插入新数据,如果之前行已存在,则写入数据时会覆盖原有数据。
- RowExistenceExpectation.EXPECT_EXIST表示只有此行存在时才会插入新数据,写入数据时会覆盖原有数据。
- RowExistenceExpectation.EXPECT_NOT_EXIST表示只有此行不存在时才会插入数据。
column 行的属性列。 - 每一项的顺序是属性名、属性值ColumnValue、属性类型ColumnType(可选)、时间戳(可选)。
- ColumnType可以是INTEGER、STRING(UTF-8编码字符串)、BINARY、BOOLEAN、DOUBLE五种,分别用ColumnType.INTEGER、ColumnType.STRING、ColumnType.BINARY、ColumnType.BOOLEAN、ColumnType.DOUBLE表示,其中BINARY不可省略,其他类型都可以省略。
- 时间戳即数据的版本号,详情请参见数据版本和生命周期。
数据的版本号可以由系统自动生成或者自定义,如果不设置此参数,则默认由系统自动生成。
- 当由系统自动生成数据的版本号时,系统默认将当前时间的毫秒单位时间戳(从1970-01-01 00:00:00 UTC计算起的毫秒数)作为数据的版本号。
- 当自定义数据的版本号时,版本号需要为64位的毫秒单位时间戳且在有效版本范围内。
- 示例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接口用于读取一行数据。
读取的结果可能有如下两种:
- 如果该行存在,则返回该行的各主键列以及属性列。
- 如果该行不存在,则返回中不包含行,并且不会报错。
- 参数
参数 说明 tableName 数据表名称。 primaryKey 行的主键。 说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。columnsToGet 读取的列集合,列名可以是主键列或属性列。 如果不设置返回的列名,则返回整行数据。
说明- 查询一行数据时,默认返回此行所有列的数据。如果需要只返回特定列,可以通过设置columnsToGet参数限制。如果将col0和col1加入到columnsToGet中,则只返回col0和col1列的值。
- 当columnsToGet和filter同时使用时,执行顺序是先获取columnsToGet指定的列,再在返回的列中进行条件过滤。
maxVersions 最多读取的版本数。 说明 maxVersions与timeRange必须至少设置一个。- 如果仅设置maxVersions,则返回所有版本中从新到旧最多指定数量版本的数据。
- 如果仅设置timeRange,则返回该范围内所有数据或指定版本数据。
- 如果同时设置maxVersions和timeRange,则返回版本号范围内从新到旧最多指定数量版本的数据。
timeRange 读取版本号范围或特定版本号的数据。详情请参见TimeRange。 说明 maxVersions与timeRange必须至少设置一个。- 如果仅设置maxVersions,则返回所有版本中从新到旧最多指定数量版本的数据。
- 如果仅设置timeRange,则返回该范围内所有数据或指定版本数据。
- 如果同时设置maxVersions和timeRange,则返回版本号范围内从新到旧最多指定数量版本的数据。
- 查询一个范围的数据,则需要设置start和end。start和end分别表示起始时间戳和结束时间戳,范围为前闭后开区间。
- 如果查询特定版本号的数据,则需要设置timestamp。timestamp表示特定的时间戳。
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); }
更新一行数据(UpdateRow)
UpdateRow接口用于更新一行数据,可以增加和删除一行中的属性列,删除属性列指定版本的数据,或者更新已存在的属性列的值。如果更新的行不存在,则新增一行数据。
说明 当UpdateRow请求中只包含删除指定的列且该行不存在时,则该请求不会新增一行数据。
- 参数
参数 说明 tableName 数据表名称。 primaryKey 行的主键。 说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。condition 使用条件更新,可以设置原行的存在性条件或者原行中某列的列值条件,详情请参见条件更新。 column 更新的属性列。 - 增加或更新数据时,需要设置属性名、属性值、属性类型(可选)、时间戳(可选)。
时间戳即数据的版本号,可以由系统自动生成或者自定义,如果不设置此参数,则默认由系统自动生成。详情请参见数据版本和生命周期。
- 当由系统自动生成数据的版本号时,系统默认将当前时间的毫秒单位时间戳(从1970-01-01 00:00:00 UTC计算起的毫秒数)作为数据的版本号。
- 当自定义数据的版本号时,版本号需要为64位的毫秒单位时间戳且在有效版本范围内。
- 删除属性列特定版本的数据时,只需要设置属性名和时间戳。
时间戳是64位整数,单位为毫秒,表示某个特定版本的数据。
- 删除属性列时,只需要设置属性名。
说明 删除一行的全部属性列不等同于删除该行,如果需要删除该行,请使用DeleteRow操作。
- 增加或更新数据时,需要设置属性名、属性值、属性类型(可选)、时间戳(可选)。
- 示例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接口用于删除一行数据。如果删除的行不存在,则不会发生任何变化。
- 参数
参数 说明 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)); }
在文档使用中是否遇到以下问题
更多建议
匿名提交