单行数据操作_Java SDK_SDK 参考

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

插入一行数据（PutRow）

PutRow 接口用于插入一行数据，如果原来该行已经存在，会覆盖原来的一行。

PutRow 写入时支持条件更新（Conditional Update），可以设置原行的存在性条件或者原行中某列的列值条件，条件更新一章对此有专门介绍。

示例 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

期望原行不存在时写入。

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 时写入。

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 接口用于读取一行数据，有以下参数：

PrimaryKey：必须设置，为要读取的行的主键。
ColumnsToGet：要读取的列的集合，若不设置，则读取所有列。
MaxVersions：最多读取多少个版本。MaxVersions 与 TimeRange 必须至少设置一个。
TimeRange: 要读取的版本号的范围。MaxVersions 与 TimeRange 必须至少设置一个。
Filter：过滤器。过滤器在服务端对读取的结果再进行一次过滤。

示例 1

读取一行，设置读取最新版本，设置 ColumnsToGet。

        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 接口支持条件更新（Conditional Update），可以设置原行的存在性条件或者原行中某列的列值条件，条件更新一章对此有专门介绍。

示例 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 接口支持条件更新（Conditional Update），可以设置原行的存在性条件或者原行中某列的列值条件，条件更新一章对此有专门介绍。

示例 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));
        }