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

前提条件

已创建时序模型实例。具体操作，请参见创建时序模型实例。

注意事项

  • 时序模型功能将从2022年05月26日正式开始收费。
  • 目前支持使用时序模型功能的地域有华东1（杭州）、华东2（上海）、华北2（北京）、华北3（张家口）、华南1（深圳）、德国（法兰克福）和新加坡。

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

接口

接口描述
CreateTimeseriesTable创建一张时序表。
ListTimeseriesTable获取当前实例下的时序表列表。
DescribeTimeseriesTable获取一个时序表的信息。
UpdateTimeseriesTable更新时序表的配置信息。
DeleteTimeseriesTable删除一个时序表。
PutTimeseriesData写入时序数据。
GetTimeseriesData查询某个时间线的数据。
QueryTimeseriesMeta检索时间线的元数据。
UpdateTimeseriesMeta更新时间线的元数据。
DeleteTimeseriesMeta删除时间线的元数据。

使用

您可以使用如下语言的SDK实现时序模型功能。

创建时序表

使用CreateTimeseriesTable创建时序表时，需要指定表的配置信息。

  • 参数

    时序表的结构信息（timeseriesTableMeta）包括表名（timeseriesTableName）和配置信息（timeseriesTableOptions）的配置，详细参数说明请参见下表。

    参数说明
    timeseriesTableName时序表名。
    timeseriesTableOptions时序表的配置信息，包括如下内容：

    timeToLive：配置时序表的数据存活时间，单位为秒。如果希望数据永不过期，可以设置为-1。您可以通过UpdateTimeseriesTable接口修改。

  • 示例

    创建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);
    client.createTimeseriesTable(request);
}

写入数据

使用PutTimeseriesData接口，您可以批量写入时序数据。一次PutTimeseriesData调用可以写入多行数据。

  • 参数

    一行时序数据（timeseriesRow）包括时间线标识（timeseriesKey）和时间线数据的配置，其中时间线数据包括数据点的时间（timeInUs）和数据点（fields）。详细参数说明请参见下表。

    参数说明
    timeseriesKey时间线标识，包括如下内容：
    • measurementName：时间线的度量名称。
    • dataSource：数据源信息，可以为空。
    • tags：时间线的标签信息，为多个字符串的key-value对。
    timeInUs数据点的时间，单位为微秒。
    fields数据点，可以由多个名称（FieldKey）和数据值（FieldValue）对组成。
  • 示例

    向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());
        }
    }
}

检索时间线

  • 参数

    metaQueryCondition表示检索时间线的条件，包括compositeMetaQueryCondition（组合条件）、measurementMetaQueryCondition（度量名称条件）、dataSourceMetaQueryCondition（数据源条件）、tagMetaQueryCondition（标签条件）、attributeMetaQueryCondition（属性条件）和updateTimeMetaQueryCondition（更新时间条件）。详细参数说明请参见下表。

    参数说明
    compositeMetaQueryCondition组合条件，包括如下内容：
    • operator：逻辑运算符，可选AND、OR、NOT。
    • subConditions：子条件列表，通过operator组成复杂查询条件。
    measurementMetaQueryCondition度量名称条件，包括如下内容：
    • operator：关系运算符或前缀匹配条件，关系运算符可选=、!=、>、>=、<、<=。
    • value：要匹配的度量名称值，类型为字符串。
    dataSourceMetaQueryCondition数据源条件，包括如下内容：
    • operator：关系运算符或前缀匹配条件，关系运算符可选=、!=、>、>=、<、<=。
    • value：要匹配的数据源值，类型为字符串。
    tagMetaQueryCondition标签条件，包括如下内容：
    • operator：关系运算符或前缀匹配条件，关系运算符可选=、!=、>、>=、<、<=。
    • value：要匹配的标签值，类型为字符串。
    attributeMetaQueryCondition时间线元数据的属性条件，包括如下内容：
    • operator：关系运算符或前缀匹配条件，关系运算符可选=、!=、>、>=、<、<=。
    • attributeName：属性名称，类型为字符串。
    • value：属性值，类型为字符串。
    updateTimeMetaQueryCondition时间线元数据的更新时间条件，包括如下内容：
    • operator：关系运算符，可选=、!=、>、>=、<、<=。
    • timeInUs：时间线元数据更新时间的时间戳，单位为微秒。
  • 示例

    查询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());
    }
}

查询时序数据

  • 参数
    参数说明
    timeseriesKey要查询的时间线，包括如下内容：
    • measurementName：时间线的度量名称。
    • dataSource：数据源信息，可以为空。
    • tags：时间线的标签信息，为多个字符串的key-value对。
    timeRange要查询的时间范围，范围为左闭右开区间。包括如下内容：
    • beginTimeInUs：起始时间。
    • endTimeInUs：结束时间。
    backward是否按照时间倒序读取数据，可用于获取某条时间线的最新数据。取值范围如下：
    • true：按照时间倒序读取。
    • false（默认）：按照时间正序读取。
    fieldsToGet要获取的数据列列名。如果不指定，则默认获取所有列。
    重要 fieldsToGet中需要指定要获取的每一列的列名和类型。如果类型不匹配，则读取不到对应列的数据。
    limit本次最多返回的行数。
    说明 limit仅限制最多返回的行数，在满足条件行数大于limit时，也可能由于扫描数据量等限制导致返回行数少于limit条，此时可以通过nextToken继续获取后面的行。
    nextToken如果一次查询仅返回了部分符合条件的行，此时response中会包括nextToken，可在下一次请求中指定nextToken用来继续读取数据。
  • 示例

    查询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());
    }
}