表格存储：读取数据

查询方式

表格存储提供的数据读取接口包括GetRow、BatchGetRow和GetRange。读取数据时，请根据实际查询场景使用相应查询方式读取数据。

前提条件

• 已初始化OTSClient。具体操作，请参见初始化OTSClient。

• 已创建数据表并写入数据。

读取单行数据

调用GetRow接口读取一行数据。读取的结果可能有如下两种：

参数

示例

读取数据时，您可以指定要读取的数据版本、要读取的列、过滤器、正则过滤等。

private static void getRow(SyncClient client, String pkValue) {
    //构造主键。
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", 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);
} 

private static void getRow(SyncClient client, String pkValue) {
    //构造主键。
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", 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);
}

private static void getRow(SyncClient client, String pkValue) {
    //设置数据表名称。
    SingleRowQueryCriteria criteria = new SingleRowQueryCriteria("<TABLE_NAME>");
 
    //构造主键。
    PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(pkValue))
        .build();
    criteria.setPrimaryKey(primaryKey);
 
    // 设置读取最新版本。
    criteria.setMaxVersions(1);
 
    // 设置过滤器，当cast<int>(regex(Col1)) > 100时，返回该行。
    RegexRule regexRule = new RegexRule("t1:([0-9]+),", RegexRule.CastType.VT_INTEGER);
    SingleColumnValueRegexFilter filter =  new SingleColumnValueRegexFilter("Col1",
        regexRule,SingleColumnValueRegexFilter.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);
}

批量读取数据

调用BatchGetRow接口一次请求读取多行数据，也支持一次对多张表进行读取。BatchGetRow由多个GetRow子操作组成。构造子操作的过程与使用GetRow接口时相同。

BatchGetRow的各个子操作独立执行，表格存储会分别返回各个子操作的执行结果。

注意事项

• 批量读取的所有行采用相同的参数条件，例如ColumnsToGet=[colA]，则要读取的所有行都只读取colA列。

• 由于批量读取可能存在部分行失败的情况，失败行的错误信息在返回的BatchGetRowResponse中，但并不抛出异常。因此调用BatchGetRow接口时，需要检查返回值，可通过BatchGetRowResponse的isAllSucceed方法判断是否所有行都获取成功；通过BatchGetRowResponse的getFailedRows方法获取失败行的信息。

• BatchGetRow操作单次支持读取的最大行数为100行。

参数

更多信息，请参见读取单行数据参数。

示例

以下示例用于读取10行，设置版本条件、要读取的列、过滤器等。

private static void batchGetRow(SyncClient client) {
    //设置数据表名称。
    MultiRowQueryCriteria multiRowQueryCriteria = new MultiRowQueryCriteria("<TABLE_NAME>");
    //加入10个要读取的行。
    for (int i = 0; i < 10; i++) {
        PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
        primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("pk" + i));
        PrimaryKey primaryKey = primaryKeyBuilder.build();
        multiRowQueryCriteria.addRow(primaryKey);
    }
    //添加条件。
    multiRowQueryCriteria.setMaxVersions(1);
    multiRowQueryCriteria.addColumnsToGet("Col0");
    multiRowQueryCriteria.addColumnsToGet("Col1");
    SingleColumnValueFilter singleColumnValueFilter = new SingleColumnValueFilter("Col0",
            SingleColumnValueFilter.CompareOperator.EQUAL, ColumnValue.fromLong(0));
    singleColumnValueFilter.setPassIfMissing(false);
    multiRowQueryCriteria.setFilter(singleColumnValueFilter);

    BatchGetRowRequest batchGetRowRequest = new BatchGetRowRequest();
    //BatchGetRow支持读取多个表的数据，一个multiRowQueryCriteria对应一个表的查询条件，可以添加多个multiRowQueryCriteria。
    batchGetRowRequest.addMultiRowQueryCriteria(multiRowQueryCriteria);

    BatchGetRowResponse batchGetRowResponse = client.batchGetRow(batchGetRowRequest);

    System.out.println("是否全部成功：" + batchGetRowResponse.isAllSucceed());
    System.out.println("读取完毕，结果为: ");
    for (BatchGetRowResponse.RowResult rowResult : batchGetRowResponse.getSucceedRows()) {
        System.out.println(rowResult.getRow());
    }
    if (!batchGetRowResponse.isAllSucceed()) {
        for (BatchGetRowResponse.RowResult rowResult : batchGetRowResponse.getFailedRows()) {
            System.out.println("失败的行：" + batchGetRowRequest.getPrimaryKey(rowResult.getTableName(), rowResult.getIndex()));
            System.out.println("失败原因：" + rowResult.getError());
        }

        /**
         * 可以通过createRequestForRetry方法再构造一个请求对失败的行进行重试。此处只给出构造重试请求的部分。
         * 推荐的重试方法是使用SDK的自定义重试策略功能，支持对batch操作的部分行错误进行重试。设置重试策略后，调用接口处无需增加重试代码。
         */
        BatchGetRowRequest retryRequest = batchGetRowRequest.createRequestForRetry(batchGetRowResponse.getFailedRows());
    }
}

详细代码请参见BatchGetRow@GitHub。

范围读取数据

调用GetRange接口读取一个范围内的数据。

GetRange操作支持按照确定范围进行正序读取和逆序读取，可以设置要读取的行数。如果范围较大，已扫描的行数或者数据量超过一定限制，会停止扫描，并返回已获取的行和下一个主键信息。您可以根据返回的下一个主键信息，继续发起请求，获取范围内剩余的行。

注意事项

GetRange操作遵循最左匹配原则，读取数据时，依次比较第一主键列到第四主键列。例如表的主键包括PK1、PK2、PK3三个主键列，读取数据时，优先比较PK1是否在开始主键与结束主键的范围内，如果PK1在设置的主键范围内，则不会再比较其他的主键，返回在PK1主键范围内的数据；如果PK1在设置的主键边界上，则继续比较PK2是否在开始主键与结束主键的范围内，以此类推。

当使用GetRange扫描的数据量较大时，表格存储每次请求仅会扫描一次（行数大于5000或者大小大于4 MB停止扫描），超过限制的数据不会继续返回，需要通过翻页继续获取后面的数据。

参数

示例

private static void getRange(SyncClient client, String startPkValue, String endPkValue) {
    //设置数据表名称。
    RangeRowQueryCriteria rangeRowQueryCriteria = new RangeRowQueryCriteria("<TABLE_NAME>");

    //设置起始主键。
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(startPkValue));
    rangeRowQueryCriteria.setInclusiveStartPrimaryKey(primaryKeyBuilder.build());

    //设置结束主键。
    primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(endPkValue));
    rangeRowQueryCriteria.setExclusiveEndPrimaryKey(primaryKeyBuilder.build());

    rangeRowQueryCriteria.setMaxVersions(1);

    System.out.println("GetRange的结果为：");
    while (true) {
        GetRangeResponse getRangeResponse = client.getRange(new GetRangeRequest(rangeRowQueryCriteria));
        for (Row row : getRangeResponse.getRows()) {
            System.out.println(row);
        }

        //如果NextStartPrimaryKey不为null，则继续读取。
        if (getRangeResponse.getNextStartPrimaryKey() != null) {
            rangeRowQueryCriteria.setInclusiveStartPrimaryKey(getRangeResponse.getNextStartPrimaryKey());
        } else {
            break;
        }
    }
}         

private static void getRange(SyncClient client, String startPkValue, String endPkValue) {
    //设置数据表名称。
    RangeRowQueryCriteria rangeRowQueryCriteria = new RangeRowQueryCriteria("<TABLE_NAME>");
    //设置起始主键，以两个主键为例。
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString(startPkValue));//确定值。
    primaryKeyBuilder.addPrimaryKeyColumn("pk2", PrimaryKeyValue.INF_MIN);//最小值。
    rangeRowQueryCriteria.setInclusiveStartPrimaryKey(primaryKeyBuilder.build());

    //设置结束主键。
    primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromString(endPkValue));//确定值。
    primaryKeyBuilder.addPrimaryKeyColumn("pk2", PrimaryKeyValue.INF_MAX);//最大值。
    rangeRowQueryCriteria.setExclusiveEndPrimaryKey(primaryKeyBuilder.build());

    rangeRowQueryCriteria.setMaxVersions(1);

    System.out.println("GetRange的结果为：");
    while (true) {
        GetRangeResponse getRangeResponse = client.getRange(new GetRangeRequest(rangeRowQueryCriteria));
        for (Row row : getRangeResponse.getRows()) {
            System.out.println(row);
        }

        //如果nextStartPrimaryKey不为null，则继续读取。
        if (getRangeResponse.getNextStartPrimaryKey() != null) {
            rangeRowQueryCriteria.setInclusiveStartPrimaryKey(getRangeResponse.getNextStartPrimaryKey());
        } else {
            break;
        }
    }
}    

private static void getRange(SyncClient client) {
    //设置数据表名称。
    RangeRowQueryCriteria criteria = new RangeRowQueryCriteria("<TABLE_NAME>");
 
    //设置主键范围为["pk:2020-01-01.log", "pk:2021-01-01.log")，读取范围为左闭右开的区间。
    PrimaryKey pk0 = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("2020-01-01.log"))
        .build();
    PrimaryKey pk1 = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString("2021-01-01.log"))
        .build();
    criteria.setInclusiveStartPrimaryKey(pk0);
    criteria.setExclusiveEndPrimaryKey(pk1);
 
    //设置读取最新版本。
    criteria.setMaxVersions(1);
 
    //设置过滤器，当cast<int>(regex(Col1)) > 100时，返回该行。
    RegexRule regexRule = new RegexRule("t1:([0-9]+),", RegexRule.CastType.VT_INTEGER);
    SingleColumnValueRegexFilter filter =  new SingleColumnValueRegexFilter("Col1",
        regexRule,SingleColumnValueRegexFilter.CompareOperator.GREATER_THAN,ColumnValue.fromLong(100));
    criteria.setFilter(filter);

    while (true) {
        GetRangeResponse resp = client.getRange(new GetRangeRequest(criteria));
        for (Row row : resp.getRows()) {
            // do something
            System.out.println(row);
        }
        if (resp.getNextStartPrimaryKey() != null) {
            criteria.setInclusiveStartPrimaryKey(resp.getNextStartPrimaryKey());
        } else {
            break;
        }
   }
}

详细代码请参见GetRange@GitHub。

迭代读取数据

以下示例用于通过createRangeIterator接口迭代读取exampletable表中的数据。

private static void getRangeByIterator(SyncClient client, String startPkValue, String endPkValue) {
    //设置数据表名称。
    RangeIteratorParameter rangeIteratorParameter = new RangeIteratorParameter("<TABLE_NAME>");

    //设置起始主键。
    PrimaryKeyBuilder primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(startPkValue));
    rangeIteratorParameter.setInclusiveStartPrimaryKey(primaryKeyBuilder.build());

    //设置结束主键。
    primaryKeyBuilder = PrimaryKeyBuilder.createPrimaryKeyBuilder();
    primaryKeyBuilder.addPrimaryKeyColumn("pk", PrimaryKeyValue.fromString(endPkValue));
    rangeIteratorParameter.setExclusiveEndPrimaryKey(primaryKeyBuilder.build());

    rangeIteratorParameter.setMaxVersions(1);

    Iterator<Row> iterator = client.createRangeIterator(rangeIteratorParameter);

    System.out.println("使用Iterator进行GetRange的结果为：");
    while (iterator.hasNext()) {
        Row row = iterator.next();
        System.out.println(row);
    }
}           

详细代码请参见GetRangeByIterator@GitHub。

并发读取数据

TableStoreReader是表格存储Java SDK提供的工具类，封装了BatchGetRow接口，可以实现并发查询表中数据。同时支持多表查询、查询状态统计、行级别回调和自定义配置功能。

快速上手

1. 构造TableStoreReader。

   String endpoint = "<ENDPOINT>";
   String accessKeyId = System.getenv("OTS_AK_ENV");
   String accessKeySecret = System.getenv("OTS_SK_ENV");
   String instanceName = "<INSTANCE_NAME>";
   
   AsyncClientInterface client = new AsyncClient(endpoint, accessKeyId, accessKeySecret, instanceName);
   TableStoreReaderConfig config = new TableStoreReaderConfig();
   ThreadPoolExecutor executor = new ThreadPoolExecutor(4, 4, 0L, TimeUnit.MILLISECONDS, new LinkedBlockingQueue(1024))
   
   TableStoreReader reader = new DefaultTableStoreReader(client, config, executor, null);

2. 构造查询请求。

   将要查询的数据缓存到内存中，支持一次添加一条或多条数据。

   PrimaryKey pk1 = PrimaryKeyBuilder.createPrimaryKeyBuilder()
           .addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromLong(0))
           .addPrimaryKeyColumn("pk2", PrimaryKeyValue.fromLong(0))
           .build();
   //新增一列查询表中，pk1的属性列。
   Future<ReaderResult> readerResult = reader.addPrimaryKeyWithFuture("<TABLE_NAME1>", pk1);
   //也可以使用List一次添加多列。
   List<PrimaryKey> primaryKeyList = new ArrayList<PrimaryKey>();
   Future<ReaderResult> readerResult = reader.addPrimaryKeysWithFuture("<TABLE_NAME2>", primaryKeyList);

3. 查询数据。

   将内存中缓存的查询发送出去。您可以通过同步阻塞方式或者异步方式查询数据。

   • 同步阻塞方式

     reader.flush();

   • 异步方式

     reader.send();

4. 获取查询结果。

   //打印成功查询和失败查询的信息。
   for (RowReadResult success : readerResult.get().getSucceedRows()) {
       System.out.println(success.getRowResult());
   }
   
   for (RowReadResult fail : readerResult.get().getFailedRows()) {
       System.out.println(fail.getRowResult());
   }

5. 关闭TableStoreReader。

   reader.close();
   //根据实际需要关闭client和executor。
   client.shutdown();
   executor.shutdown();

配置项

您可以通过修改TableStoreReaderConfig自定义配置TableStoreReader。

指定查询条件

您可以指定表级别的查询参数，例如查询的最大版本数，要查询的列、时间范围等。

//查询表的col1列过去60秒的最多10个版本。
//设置数据表名称。
RowQueryCriteria criteria = new RowQueryCriteria("<TABLE_NAME>");
//设置要返回的列。
criteria.addColumnsToGet("col1");
//设置返回的最大版本数。
criteria.setMaxVersions(10);
criteria.setTimeRange(new TimeRange(System.currentTimeMillis() - 60 * 1000, System.currentTimeMillis()));
reader.setRowQueryCriteria(criteria);

完整示例

public class TableStoreReaderDemo {
    private static final String endpoint = "<ENDPOINT>";
    private static final String accessKeyId = System.getenv("OTS_AK_ENV");
    private static final String accessKeySecret = System.getenv("OTS_SK_ENV");
    private static final String instanceName = "<INSTANCE_NAME>";
    private static AsyncClientInterface client;
    private static ExecutorService executor;
    private static AtomicLong succeedRows = new AtomicLong();
    private static AtomicLong failedRows = new AtomicLong();

    public static void main(String[] args) throws ExecutionException, InterruptedException {
        /**
         * 步骤一：构造TableStoreReader。
         */
        //构造AsyncClient。
        client = new AsyncClient(endpoint, accessKeyId, accessKeySecret, instanceName);
        //构造reader配置类。
        TableStoreReaderConfig config = new TableStoreReaderConfig();
        {
            //以下参数均有默认值，可不配置。
            //向reader添加要查询的数据前，会先检查表的结构。
            config.setCheckTableMeta(true);  
            //一次请求的最大请求行数，上限为100。
            config.setMaxBatchRowsCount(100);    
            //默认情况下，获取的columns最大版本数。
            config.setDefaultMaxVersions(1);
            //发送请求的总并发数。
            config.setConcurrency(16); 
            //内存分桶数。
            config.setBucketCount(4);      
            //将缓存数据全部发送的时间间隔。
            config.setFlushInterval(10000);      
            //日志记录reader状态的时间间隔。
            config.setLogInterval(10000);                   
        }
        //构造用于发送请求的executor。
        ThreadFactory threadFactory = new ThreadFactory() {
            private final AtomicInteger counter = new AtomicInteger(1);

            @Override
            public Thread newThread(Runnable r) {
                return new Thread(r, "reader-" + counter.getAndIncrement());
            }
        };
        executor = new ThreadPoolExecutor(4, 4, 0L, TimeUnit.MILLISECONDS,
                new LinkedBlockingQueue(1024), threadFactory, new ThreadPoolExecutor.CallerRunsPolicy());

        //构造reader的回调函数。
        TableStoreCallback<PrimaryKeyWithTable, RowReadResult> callback = new TableStoreCallback<PrimaryKeyWithTable, RowReadResult>() {
            @Override
            public void onCompleted(PrimaryKeyWithTable req, RowReadResult res) {
                succeedRows.incrementAndGet();
            }

            @Override
            public void onFailed(PrimaryKeyWithTable req, Exception ex) {
                failedRows.incrementAndGet();
            }
        };
        TableStoreReader reader = new DefaultTableStoreReader(client, config, executor, callback);
        /**
         * 步骤二：构造查询请求。
         */
        //向内存添加一列要查询的数据。
        PrimaryKey pk1 = PrimaryKeyBuilder.createPrimaryKeyBuilder()
                .addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromLong(0))
                .addPrimaryKeyColumn("pk2", PrimaryKeyValue.fromLong(0))
                .build();
        reader.addPrimaryKey("<TABLE_NAME1>", pk1);

        //向内存添加一列要查询的数据，并获取查询结果Future。
        PrimaryKey pk2 = PrimaryKeyBuilder.createPrimaryKeyBuilder()
                .addPrimaryKeyColumn("pk1", PrimaryKeyValue.fromLong(0))
                .addPrimaryKeyColumn("pk2", PrimaryKeyValue.fromLong(0))
                .build();
        Future<ReaderResult> readerResult = reader.addPrimaryKeyWithFuture("<TABLE_NAME2>", pk2);
        /**
         * 步骤三：查询数据。
         */
        //异步将内存中的数据发送出去。
        reader.send();
        /**
         * 步骤四：获取查询结果。
         */
        //打印成功查询和失败查询的信息。
        for (RowReadResult success : readerResult.get().getSucceedRows()) {
            System.out.println(success.getRowResult());
        }
        for (RowReadResult fail : readerResult.get().getFailedRows()) {
            System.out.println(fail.getRowResult());
        }
        /**
         * 步骤五：关闭TableStoreReader。
         */
        reader.close();
        client.shutdown();
        executor.shutdown();
    }
}

相关文档

• 如果要使用索引技术加速数据查询，您可以通过二级索引或者多元索引功能实现。更多信息，请参见二级索引或者多元索引。

• 如果要可视化展示表中数据，您可以通过对接DataV或者Grafana工具实现。更多信息，请参见数据可视化。

• 如果要下载表中数据到本地，您可以通过DataX、表格存储命令行CLI工具实现。更多信息，请参见将表格存储数据下载到本地文件。

• 如果要计算与分析表中数据，您可以通过表格存储SQL查询实现。更多信息，请参见SQL查询。

  说明

  您还可以通过MaxCompute、Spark、Hive或者HadoopMR、函数计算、Flink等计算引擎实现表中数据的计算与分析。具体操作，请参见计算与分析。