单行数据操作

前提条件

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

• 参数

  参数	说明
  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));
  }