文档

通过SDK使用时序模型

更新时间:

通过SDK创建时序表后,您可以写入时序数据并对时间线进行检索以及查询时序数据。

前提条件

注意事项

  • 时序模型功能将从2022年05月26日正式开始收费。

  • 目前支持使用时序模型功能的地域有华东1(杭州)、华东2(上海)、华北2(北京)、华北3(张家口)、华北6(乌兰察布)、华南1(深圳)、中国香港、德国(法兰克福)、美国(弗吉尼亚)、印度(孟买)和新加坡。

如果使用过程中遇到问题,请通过钉钉加入用户群11789671(表格存储技术交流群)或23307953(表格存储技术交流群-2)联系我们。

接口

接口

描述

CreateTimeseriesTable

创建一张时序表。

ListTimeseriesTable

获取当前实例下的时序表列表。

DescribeTimeseriesTable

获取一个时序表的信息。

UpdateTimeseriesTable

更新时序表的配置信息。

DeleteTimeseriesTable

删除一个时序表。

PutTimeseriesData

写入时序数据。

GetTimeseriesData

查询某个时间线的数据。

QueryTimeseriesMeta

检索时间线的元数据。

UpdateTimeseriesMeta

更新时间线的元数据。

DeleteTimeseriesMeta

删除时间线的元数据。

使用

您可以使用如下语言的SDK实现时序模型功能。本文Java SDK为例介绍时序模型的使用。

步骤一:创建时序表

当使用表格存储时序模型时,您需要使用CreateTimeseriesTable接口创建时序表用于存储时序数据。

说明

如果需要低成本存储时序数据以及快速查询和分析时序数据,您可以为时序表创建分析存储。分析存储功能主要用于时序数据长期存储和分析场景。更多信息,请参见时序分析存储概述

以下示例用于创建test_timeseries_table时序表,且该表中数据永不过期。

private static void createTimeseriesTable(TimeseriesClient client) {
    String tableName = "test_timeseries_table";
    TimeseriesTableMeta timeseriesTableMeta = new TimeseriesTableMeta(tableName);
    int timeToLive = -1;
    timeseriesTableMeta.setTimeseriesTableOptions(new TimeseriesTableOptions(timeToLive));
    CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(timeseriesTableMeta);
    //不创建默认分析存储。
    request.setEnableAnalyticalStore(false);    
    client.createTimeseriesTable(request);
}

步骤二:写入数据

创建时序表后,您可以使用PutTimeseriesData接口批量写入时序数据到时序表。

以下示例用于向test_timeseries_table时序表中写入多个时序数据。

private static void putTimeseriesData(TimeseriesClient client) {
    List<TimeseriesRow> rows = new ArrayList<TimeseriesRow>();
    for (int i = 0; i < 10; i++) {
        Map<String, String> tags = new HashMap<String, String>();
        tags.put("region", "hangzhou");
        tags.put("os", "Ubuntu16.04");
        // 通过measurementName、dataSource和tags构建TimeseriesKey。
        TimeseriesKey timeseriesKey = new TimeseriesKey("cpu", "host_" + i, tags);
        // 指定timeseriesKey和timeInUs创建timeseriesRow。
        TimeseriesRow row = new TimeseriesRow(timeseriesKey, System.currentTimeMillis() * 1000 + i);
        // 增加数据值(field)。
        row.addField("cpu_usage", ColumnValue.fromDouble(10.0));
        row.addField("cpu_sys", ColumnValue.fromDouble(5.0));
        rows.add(row);
    }
    String tableName = "test_timeseries_table";
    PutTimeseriesDataRequest putTimeseriesDataRequest = new PutTimeseriesDataRequest(tableName);
    putTimeseriesDataRequest.setRows(rows);
    // 一次写入多行时序数据。
    PutTimeseriesDataResponse putTimeseriesDataResponse = client.putTimeseriesData(putTimeseriesDataRequest);
    // 检查是否全部成功。
    if (!putTimeseriesDataResponse.isAllSuccess()) {
        for (PutTimeseriesDataResponse.FailedRowResult failedRowResult : putTimeseriesDataResponse.getFailedRows()) {
            System.out.println(failedRowResult.getIndex());
            System.out.println(failedRowResult.getError());
        }
    }
}

步骤三:检索时间线

如果不确定要查询的时间线信息(例如度量名称、数据源信息),请使用QueryTimeseriesMeta接口指定多种条件检索时间线。

以下示例用于查询test_timeseries_table时序表中度量名称为cpu,标签中含有os标签且标签前缀为"Ubuntu"的所有时间线。

private static void queryTimeseriesMeta(TimeseriesClient client) {
    String tableName = "test_timeseries_table";
    QueryTimeseriesMetaRequest queryTimeseriesMetaRequest = new QueryTimeseriesMetaRequest(tableName);
    // 查询度量名称为cpu,标签中含有os标签且前缀为"Ubuntu"的所有时间线。即measurement_name="cpu" and have_prefix(os, "Ubuntu")。
    CompositeMetaQueryCondition compositeMetaQueryCondition = new CompositeMetaQueryCondition(MetaQueryCompositeOperator.OP_AND);
    compositeMetaQueryCondition.addSubCondition(new MeasurementMetaQueryCondition(MetaQuerySingleOperator.OP_EQUAL, "cpu"));
    compositeMetaQueryCondition.addSubCondition(new TagMetaQueryCondition(MetaQuerySingleOperator.OP_PREFIX, "os", "Ubuntu"));
    queryTimeseriesMetaRequest.setCondition(compositeMetaQueryCondition);
    queryTimeseriesMetaRequest.setGetTotalHits(true);
    // 限制单次请求返回的时间线元数据条数。
    queryTimeseriesMetaRequest.setLimit(100);
    // 发起查询。
    QueryTimeseriesMetaResponse queryTimeseriesMetaResponse = client.queryTimeseriesMeta(queryTimeseriesMetaRequest);
    // 打印符合条件的时间线的总条数。
    System.out.println(queryTimeseriesMetaResponse.getTotalHits());

    // 保存请求结果。
    List<TimeseriesMeta> timeseriesMetas = new ArrayList<TimeseriesMeta>();
    timeseriesMetas.addAll(queryTimeseriesMetaResponse.getTimeseriesMetas());

    // 如果有NextToken,可以继续发起请求获取。
    while (queryTimeseriesMetaResponse.getNextToken() != null) {
        queryTimeseriesMetaRequest.setNextToken(queryTimeseriesMetaResponse.getNextToken());
        queryTimeseriesMetaResponse = client.queryTimeseriesMeta(queryTimeseriesMetaRequest);
        timeseriesMetas.addAll(queryTimeseriesMetaResponse.getTimeseriesMetas());
        // 限制总共获取的条数。
        if (timeseriesMetas.size() >= 1000) {
            break;
        }
    }

    System.out.println(timeseriesMetas.size());
    for (TimeseriesMeta timeseriesMeta : timeseriesMetas) {
        System.out.println(timeseriesMeta.getTimeseriesKey().getMeasurementName());
        System.out.println(timeseriesMeta.getTimeseriesKey().getDataSource());
        System.out.println(timeseriesMeta.getTimeseriesKey().getTags());
        System.out.println(timeseriesMeta.getAttributes());
        System.out.println(timeseriesMeta.getUpdateTimeInUs());
    }
}

步骤四:查询时序数据

使用GetTimeseriesData接口查询指定时间线中符合条件的时序数据。

以下示例用于查询test_timeseries_table时序表中满足指定条件的时序数据。

private static void getTimeseriesData(TimeseriesClient client) {
    String tableName = "test_timeseries_table";
    GetTimeseriesDataRequest getTimeseriesDataRequest = new GetTimeseriesDataRequest(tableName);
    Map<String, String> tags = new HashMap<String, String>();
    tags.put("region", "hangzhou");
    tags.put("os", "Ubuntu16.04");
    // 通过measurementName、dataSource和tags构建TimeseriesKey。
    TimeseriesKey timeseriesKey = new TimeseriesKey("cpu", "host_0", tags);
    getTimeseriesDataRequest.setTimeseriesKey(timeseriesKey);
    // 指定时间范围。
    getTimeseriesDataRequest.setTimeRange(0, (System.currentTimeMillis() + 60 * 1000) * 1000);
    // 限制返回行数。
    getTimeseriesDataRequest.setLimit(10);
    // 设置是否倒序读取数据,可不设置,默认值为false。如果设置为true,则倒序读取数据。
    getTimeseriesDataRequest.setBackward(false);
    // 设置获取部分数据列,可不设置,默认获取全部数据列。
    getTimeseriesDataRequest.addFieldToGet("string_1", ColumnType.STRING);
    getTimeseriesDataRequest.addFieldToGet("long_1", ColumnType.INTEGER);

    GetTimeseriesDataResponse getTimeseriesDataResponse = client.getTimeseriesData(getTimeseriesDataRequest);
    System.out.println(getTimeseriesDataResponse.getRows().size());
    if (getTimeseriesDataResponse.getNextToken() != null) {
        // 如果nextToken不为空,可以发起下一次请求。
        getTimeseriesDataRequest.setNextToken(getTimeseriesDataResponse.getNextToken());
        getTimeseriesDataResponse = client.getTimeseriesData(getTimeseriesDataRequest);
        System.out.println(getTimeseriesDataResponse.getRows().size());
    }
}

附录:管理时序表

创建时序表后,请根据需要执行相应操作。

查询时序表描述信息

当需要查询时序表的TTL配置、时序表状态、时间线表的TTL配置等详细信息时,您可以查询时序表的描述信息。

以下示例用于查询指定时序表的描述信息。

private static void describeTimeseriesTable(TimeseriesClient client) {
    // 填写时序表名称。
    String tableName = "<TIMESERIES_TABLE>";
    DescribeTimeseriesTableResponse describeTimeseriesTableResponse = client.describeTimeseriesTable(new DescribeTimeseriesTableRequest(tableName));
    TimeseriesTableMeta tableMeta = describeTimeseriesTableResponse.getTimeseriesTableMeta();
    // 查看时序表名。
    System.out.println(tableMeta.getTimeseriesTableName()); 
    // 查看时序表状态。
    System.out.println(tableMeta.getStatus()); 
    // 查看时序表的TTL配置。
    System.out.println(tableMeta.getTimeseriesTableOptions().getTimeToLive()); 
    // 查看时间线表的TTL配置。
    System.out.println(tableMeta.getTimeseriesMetaOptions().getMetaTimeToLive()); 
    // 查看是否允许更新时间线属性列。
    System.out.println(tableMeta.getTimeseriesMetaOptions().getAllowUpdateAttributes()); 
    //如果为时序表创建了分析存储,您可以使用如下代码获取时序表的分析存储信息。
    List<TimeseriesAnalyticalStore> analyticalStores = describeTimeseriesTableResponse.getAnalyticalStores(); // 查看时序表的分析存储配置。
    for (TimeseriesAnalyticalStore store : analyticalStores) {
        // 查看分析存储名称。
        System.out.println(store.getAnalyticalStoreName()); 
        // 查看分析存储TTL配置。
        System.out.println(store.getTimeToLive()); 
        // 查看分析存储同步配置。
        System.out.println(store.getSyncOption()); 
    }
}

更新时序表

当需要清理时序表中的历史数据或者延长数据保存时长时,您可以更新时序表的TTL配置信息或者时间线表的TTL配置。您还可以更新是否支持修改时间线属性列。

以下示例用于更新指定时序表的TTL为3年。

private static void updateTimeseriesTable(TimeseriesClient client) {
    // 填写时序表名称。
    String tableName = "<TIMESERIES_TABLE>";
    UpdateTimeseriesTableRequest updateTimeseriesTableRequest = new UpdateTimeseriesTableRequest(tableName);
    // 更新TTL为3年。
    updateTimeseriesTableRequest.setTimeseriesTableOptions(new TimeseriesTableOptions(86400 * 365 * 3)); 
    client.updateTimeseriesTable(updateTimeseriesTableRequest);

    DescribeTimeseriesTableResponse describeTimeseriesTableResponse = client.describeTimeseriesTable(new DescribeTimeseriesTableRequest(tableName));
    TimeseriesTableMeta tableMeta = describeTimeseriesTableResponse.getTimeseriesTableMeta();
    // 查看更新后时序表的TTL配置。
    System.out.println(tableMeta.getTimeseriesTableOptions().getTimeToLive()); 
}

删除时序表

当不再需要使用时序表来存储时序数据时,您可以删除时序表。

以下示例用于删除指定时序表。

private static void deleteTimeseriesTable(TimeseriesClient client) {
    // 填写时序表名称。
    String tableName = "<TIMESERIES_TIME>";
    DeleteTimeseriesTableRequest deleteTimeseriesTableRequest = new DeleteTimeseriesTableRequest(tableName);
    client.deleteTimeseriesTable(deleteTimeseriesTableRequest);
}
  • 本页导读 (1)
文档反馈