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

说明 组成表的基本单位为行，行由主键和属性组成。其中主键是必须的，且每一行的主键列的名称和类型相同；属性不是必须的，且每一行的属性可以不同。更多信息，请参见模型介绍。

接口

单行数据操作包括PutRow、GetRow、UpdateRow和DeleteRow接口，详细说明请参见下表。

接口 说明
GetRow 读取一行数据。
PutRow 新写入一行数据。如果该行已存在，则先删除旧行数据，再写入新行数据。
UpdateRow 更新一行数据。可以增加、删除一行中的属性列，或者更新已存在的属性列的值。

如果更新的行不存在，则新增一行数据。但是当UpdateRow请求中只包含删除指定的列且该行不存在时，则该请求不会新增一行数据。
DeleteRow 删除一行数据。

如果删除的行不存在，则不会发生任何变化。

使用

您可以使用如下语言的SDK实现单行数据操作。

插入一行数据（PutRow）

PutRow接口用于新写入一行数据。如果该行已存在，则先删除原行数据（原行的所有列以及所有版本的数据），再写入新行数据。

PutRow操作消耗的读CU和写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 使用条件更新，可以设置原行的存在性条件或者原行中某列的列值条件。更多信息，请参见条件更新。
    说明
    • 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接口用于读取一行数据。

GetRow操作不消耗写CU，消耗的读CU为读取的行主键的数据大小与实际读取的属性列数据大小之和，按4 KB向上取整。如果操作指定的行不存在，则消耗1单位读CU。

读取的结果可能有如下两种：
  • 如果该行存在，则返回该行的各主键列以及属性列。
  • 如果该行不存在，则返回中不包含行，并且不会报错。
  • 参数
    参数 说明
    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);
}
  • 示例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）

UpdateRow接口用于更新一行数据，可以增加和删除一行中的属性列，删除属性列指定版本的数据，或者更新已存在的属性列的值。如果更新的行不存在，则新增一行数据。
说明 当UpdateRow请求中只包含删除指定的列且该行不存在时，则该请求不会新增一行数据。
UpdateRow操作消耗的读CU和写CU说明如下：
  • 消耗的写CU为修改的行主键数据大小与属性列数据大小之和除以4 KB向上取整。

    操作中包含的需要删除的属性列，只有属性列的列名计入属性列数据大小。

  • 如果指定条件检查不为IGNORE，则消耗行主键数据大小除以4 KB向上取整的读CU。
  • 如果操作不满足指定的行存在性检查条件，则操作失败并消耗1单位写CU和1单位读CU。
  • 参数
    参数 说明
    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接口用于删除一行数据。如果删除的行不存在，则不会发生任何变化。

DeleteRow操作消耗的读CU和写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));
}