为了让表格存储 Tablestore 用户更好的了解产品数据管理能力以及SDK使用，本文将结合代码讲述数据管理的功能与使用方式。本文仅讲述主表数据的管理使用，并非Tablestore全部的数据管理能力。涉及到二级索引、多元索引查询能力的内容，将会在以后的文章中单独介绍。样例代码链接地址见：Tablestore-Examples项目。

数据管理概览

Tablestore的数据以PrimaryKey作为唯一行标识，表数据的管理也是基于PrimaryKey做相应的增、删、改、查。对于Tablestore的主表数据管理，按照操作数量分为：单行操作、批量操作两类。按照操作类型又分为：写、读两类。单行数据的增、删、改操作都实现了RowChange接口，因此在批量操作中，可以一次请求同时对数据发起增、删、改的操作请求。

数据管理使用

单行操作

数据插入

数据行级别插入，需要提供完整的PrimaryKey标识行的唯一ID，然后配置行的属性值。
注意事项：

主键必须完整，并且与表属性主键名、主键类型一致，否侧会有参数错误；
如果该行数据存在，默认覆盖原数据。如果不想覆盖，可通过设置condition做校验，若存在则会抛错。

PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
    .addPrimaryKeyColumn(PK1, PrimaryKeyValue.fromLong(1L))
    .addPrimaryKeyColumn(PK2, PrimaryKeyValue.fromString("string"))
    .build();

RowPutChange rowChange = new RowPutChange(TABLE_NAME, primaryKey);
rowChange.addColumn("string", ColumnValue.fromString("string value"))
    .addColumn("long", ColumnValue.fromLong(1L))
    .addColumn("boolean", ColumnValue.fromBoolean(true))
    .addColumn("double", ColumnValue.fromDouble(1.1))
    .addColumn("binary", ColumnValue.fromBinary(new byte[]{1, 2, 3}));

PutRowRequest putRowRequest = new PutRowRequest(rowChange);

syncClient.putRow(putRowRequest);

数据插入-条件插入

条件写入是提供三种行级别条件检验，对写操作都支持，RowChange接口提供的API，主要包含如下行检验方式：

IGNORE // 不做检查，默认值
EXPECT_EXIST // 期望行存在，存在才会做写操作
EXPECT_NOT_EXIST // 期望行不存在，不存在才会做写操作

// 若条件校验失败，则会抛错：OTSConditionCheckFail
rowChange.setCondition(new Condition(RowExistenceExpectation.EXPECT_NOT_EXIST));

数据插入-自增列

支持自增列数据插入，前提创建表格时相应的主键列已设置成自增列。数据插入时，该列主键设置为特殊的列值。

PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
    .addPrimaryKeyColumn(PK1, PrimaryKeyValue.fromLong(1L))
    .addPrimaryKeyColumn(PK2, PrimaryKeyValue.fromString("string"))
    .addPrimaryKeyColumn(PK3, PrimaryKeyValue.AUTO_INCREMENT)    // 自增列的特殊列值
    .build();

RowPutChange rowChange = new RowPutChange(TABLE_NAME_INC, primaryKey);
rowChange.addColumn("string", ColumnValue.fromString("string value"));

rowChange.setReturnType(ReturnType.RT_PK);                         // 获取主键自增列实际插入的值

PutRowRequest putRowRequest = new PutRowRequest(rowChange);

PutRowResponse putRowResponse = syncClient.putRow(putRowRequest);

// 自增列的实际存储值只有在返回的Response中才能拿到
PrimaryKey returnPrimaryKey = putRowResponse.getRow().getPrimaryKey();

数据删除

基于给定的完整PrimaryKey删除相应行的数据，如果行不存在，删除操作也不会抛错。
注意事项：

主键必须完整，并且与表属性主键名、主键类型一致，否侧会有参数错误；

PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
    .addPrimaryKeyColumn(PK1, PrimaryKeyValue.fromLong(1L))
    .addPrimaryKeyColumn(PK2, PrimaryKeyValue.fromString("string"))
    .build();

RowDeleteChange rowChange = new RowDeleteChange(TABLE_NAME, primaryKey);
DeleteRowRequest getRowRequest = new DeleteRowRequest(rowChange);

syncClient.deleteRow(getRowRequest);

数据更新

数据更新对指定行做指定字段做更新操作，涵盖列的增、删、改。
注意事项：

主键必须完整，并且与表属性主键名、主键类型一致，否侧会有参数错误；
支持条件更新：
- 支持单列值过滤（SingleColumnValueCondition）
- 组合多列值过滤（CompositeColumnValueCondition）单列值的与、或、非组合
操作可以是：
- 删除指定列的指定版本
- 删除指定列的所有版本
- 增加新列
- 更新已存在列
- 指定列（整数列）做原子加：原子加更新时，如果想要获取增加后的值，需要设置ReturnType

PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
    .addPrimaryKeyColumn(PK1, PrimaryKeyValue.fromLong(1L))
    .addPrimaryKeyColumn(PK2, PrimaryKeyValue.fromString("string"))
    .build();

RowUpdateChange rowChange = new RowUpdateChange(TABLE_NAME, primaryKey);
rowChange
    .deleteColumns("binary")                                        // 删除指定列所有版本
    .deleteColumn("double", timestamp)                                // 删除指定列指定版本
    .put("string", ColumnValue.fromString("new string value"))        // 更新已存在列
    .put("newCol", ColumnValue.fromString("new col"))                 // 增加新列
    .increment(new Column("long", ColumnValue.fromLong(100L)));        // 原子加
        
rowChange.setReturnType(ReturnType.RT_AFTER_MODIFY);                // 获取属性列原子加修改后的值
UpdateRowRequest updateRowRequest = new UpdateRowRequest(rowChange);

UpdateRowResponse updateRowResponse = syncClient.updateRow(updateRowRequest);

数据更新-条件更新

Tablestore支持行级别的条件更有新，用户可以提供属性列值的条件校验实现条件更新。条件更新也是RowChange接口提供的API。
条件更新支持单列条件校验、组合属性列条件校验两种，满足条件时才会完成数据更新，不满足是会抛错误。

单属性列条件校验

Condition condition = new Condition(RowExistenceExpectation.EXPECT_EXIST); // 条件更新
condition.setColumnCondition(
        new SingleColumnValueCondition(
                "boolean",
                SingleColumnValueCondition.CompareOperator.EQUAL,
                ColumnValue.fromBoolean(true)));

rowChange.setCondition(condition);

组合属性列条件校验（多列属性的与、或、非组合）

CompositeColumnValueCondition colCondition = new CompositeColumnValueCondition(CompositeColumnValueCondition.LogicOperator.AND);

ColumnCondition subColCondition1 = new SingleColumnValueCondition(
        "boolean",
        SingleColumnValueCondition.CompareOperator.EQUAL,
        ColumnValue.fromBoolean(true));

ColumnCondition subColCondition2 = new SingleColumnValueCondition(
        "double",
        SingleColumnValueCondition.CompareOperator.GREATER_THAN,
        ColumnValue.fromLong(0L));

colCondition.addCondition(subColCondition1).addCondition(subColCondition2);
Condition condition = new Condition();
condition.setColumnCondition(colCondition);

rowChange.setCondition(condition);

数据查询

说明：基于给定的完整PrimaryKey读取该行行数据。如果数据不存在，则Response.getRow()为空。
注意事项：

主键必须完整，并且与表属性主键名、主键类型一致，否侧会有参数错误；
默认返回所有属性列，如果指定属性列仅返回属性列值；
如果指定属性列，但该行数据没有指定的列属性（有其他属性列），则会返回null，不表示该行一定不存在；
多版本表可以通过设置MaxVersion返回列多个版本的数据；

PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
    .addPrimaryKeyColumn(PK1, PrimaryKeyValue.fromLong(1L))
    .addPrimaryKeyColumn(PK2, PrimaryKeyValue.fromString("string"))
    .build();

SingleRowQueryCriteria criteria = new SingleRowQueryCriteria(TABLE_NAME, primaryKey);
criteria.setMaxVersions(1);

GetRowRequest getRowRequest = new GetRowRequest(criteria);

GetRowResponse getRowResponse = syncClient.getRow(getRowRequest);

批量操作

数据写-增删改

批量数据操作与单行操作都是基于RowChange实现的请求构建。因此一个BatchWriteRowRequest中，可以包含增、删、改三种不同的操作。同时，表名参数包含在各自的行信息中，所以可以实现多表数据的混合写入操作。用户可以自己尝试。
注意事项：

请求失败，所有的行操作都失败
请求成功，不表示每一行都成功，需要判断失败列表的长度是否为零。对于失败行，可重新构建请求做重试。
批量写（增删改）操作构建的请求有限制：行数<=200，总大小<=4M，超过限制会抛错

BatchWriteRowRequest batchWriteRowRequest = new BatchWriteRowRequest();

/**
 * Multi Put Row
 */
for (long i = 1L; i <= 10L; i++) {
    PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn(PK1, PrimaryKeyValue.fromLong(i))
        .addPrimaryKeyColumn(PK2, PrimaryKeyValue.fromString("string"))
        .build();

    RowPutChange rowChange = new RowPutChange(TABLE_NAME, primaryKey);
    rowChange.addColumn("long", ColumnValue.fromLong(i));

    batchWriteRowRequest.addRowChange(rowChange);
}

/**
 * Multi Update Row
 */
for (long i = 11L; i <= 20L; i++) {
    PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn(PK1, PrimaryKeyValue.fromLong(i))
        .addPrimaryKeyColumn(PK2, PrimaryKeyValue.fromString("string"))
        .build();

    RowUpdateChange rowChange = new RowUpdateChange(TABLE_NAME, primaryKey);
    rowChange.put("long", ColumnValue.fromLong(i));

    batchWriteRowRequest.addRowChange(rowChange);
}

/**
 * Multi Delete Row
 */
for (long i = 21L; i <= 30L; i++) {
    PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn(PK1, PrimaryKeyValue.fromLong(i))
        .addPrimaryKeyColumn(PK2, PrimaryKeyValue.fromString("string"))
        .build();

    RowDeleteChange rowChange = new RowDeleteChange(TABLE_NAME, primaryKey);

    batchWriteRowRequest.addRowChange(rowChange);
}

BatchWriteRowResponse batchWriteRowResponse = syncClient.batchWriteRow(batchWriteRowRequest);
int totalRowCount = batchWriteRowResponse.getRowStatus(TABLE_NAME).size();
int failedRowCount = batchWriteRowResponse.getFailedRows().size();

批量写-失败行重试

批量写操作成功后，并不表示批请求的所有行操作都成功。行级别的状态需要单独判断。返回失败行，对失败行重新构建BatchWriteRow请求，重新发起请求。

if (batchWriteRowResponse.getFailedRows().size() > 0 ) {
    BatchWriteRowRequest retryRequest = batchWriteRowRequest.createRequestForRetry(
        batchWriteRowResponse.getFailedRows());

    syncClient.batchWriteRow(retryRequest);
}

多行随机查询

批量读查询支持单表下，批量数据同时读的能力，用户构建请求时只需添加行的完整PrimaryKey即可。
注意事项：

批量读请求失败，每一行读都没有成功
批量读请求成功，并不能表示每一行请求都成功，需要判断失败列表的长度是否为零。

BatchGetRowRequest batchGetRowRequest = new BatchGetRowRequest();
MultiRowQueryCriteria criteria = new MultiRowQueryCriteria(TABLE_NAME);

for (long i = 1L; i <= 30L; i += 10) {
    PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn(PK1, PrimaryKeyValue.fromLong(i))
        .addPrimaryKeyColumn(PK2, PrimaryKeyValue.fromString("string"))
        .build();

    criteria.addRow(primaryKey);
}

criteria.setMaxVersions(1);
batchGetRowRequest.addMultiRowQueryCriteria(criteria);

BatchGetRowResponse batchGetRowResponse = syncClient.batchGetRow(batchGetRowRequest);
int totalRowCount = batchGetRowResponse.getBatchGetRowResult(TABLE_NAME).size();
int failedRowCount = batchGetRowResponse.getFailedRows().size();

范围查询

表中数据基于PrimaryKey有序排列，表是一个特殊的基于主键的联合索引。因此，数据范围查询遵循联合索引的最左匹配原则。即：范围查询时如果某一列提供了具体的范围值（非MIN、MAX），则下一列的范围限制就被忽略，因为下一列的范围约束是无效的。具体参考下图：

注意事项：

结果与条件不一致时，请参考最左匹配原则
范围左开右闭，及包含start，但不包含end
正序时，start必须小于end；倒序时：start必须大于end

GetRangeRequest getRangeRequest = new GetRangeRequest();

PrimaryKey start = PrimaryKeyBuilder.createPrimaryKeyBuilder()
    .addPrimaryKeyColumn(PK1, PrimaryKeyValue.fromLong(2))
    .addPrimaryKeyColumn(PK2, PrimaryKeyValue.fromString("5"))
    .build();

PrimaryKey end = PrimaryKeyBuilder.createPrimaryKeyBuilder()
    .addPrimaryKeyColumn(PK1, PrimaryKeyValue.fromLong(4))
    .addPrimaryKeyColumn(PK2, PrimaryKeyValue.fromString("4"))
    .build();

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria(TABLE_NAME);
criteria.setInclusiveStartPrimaryKey(start);
criteria.setExclusiveEndPrimaryKey(end);
criteria.setDirection(Direction.FORWARD);            // 设置顺序
criteria.setMaxVersions(1);                            // 返回版本个数
criteria.setLimit(20);                                // 每页返回行数限制

getRangeRequest.setRangeRowQueryCriteria(criteria);

GetRangeResponse getRangeResponse = syncClient.getRange(getRangeRequest);

范围查询-连续翻页

当范围条件数据单次请求未拿到全量数据时，需要用户基于NextStartPrimaryKey做连续翻页，从而遍历全部命中数据。如果GetRangeResponse.getNextStartPrimaryKey()非空，则一定还有数据。通过将获取的PrimaryKey设置到原请求中重新构建，然后再次发起请求。

PrimaryKey nextStartPrimaryKey = null;
do {
    GetRangeResponse getRangeResponse = syncClient.getRange(getRangeRequest);
    List<Row> pageRowList = getRangeResponse.getRows();

    nextStartPrimaryKey = getRangeResponse.getNextStartPrimaryKey();
    if (nextStartPrimaryKey != null) {                 // 判断存在下一页，重构请求
        criteria.setInclusiveStartPrimaryKey(nextStartPrimaryKey);
        getRangeRequest.setRangeRowQueryCriteria(criteria);
    }
} while (nextStartPrimaryKey != null);              // 持续翻页，直到没有下一页

范围查询-连续翻页迭代器

为了方便用户遍历全量数据，我们提供了迭代器接口。用户无需关心请求构建、结果判断等逻辑，只需将异步Client与请求体作为参数构建GetRangeIterator即可。
注意事项：

迭代器使用的异步Client，可以重现构建也可以通过同步Client转换；
迭代器内部自动发起请求，消费完一批后自动发起下一批请求；

AsyncClient asyncClient = (AsyncClient) syncClient.asAsyncClient();
GetRangeIterator getRangeIterator = new GetRangeIterator(asyncClient, getRangeRequest);

while (getRangeIterator.hasNext()) {
    Row row = getRangeIterator.next();
}

Tablestore 入门手册

本文结合Java SDK的接口调用代码，介绍了Tablestore在数据管理方面的基本功能与使用方式。代码已开源在Tablestore-Examples项目中，用户可以直接运行使用。基于样例代码与文章，新用户能更简单、更快速地上手Tablestore，欢迎新、老用户使用与建议。

通过对基础使用功能的持续输出，我们将整理出一套完整的入门手册（含可执行样例），敬请期待。

专家服务

如有疑问或者需要更好的在线支持，欢迎加入钉钉群：“表格存储公开交流群”。群内提供免费的在线专家服务，欢迎扫码加入，群号：23307953

Tablestore入门手册--数据管理