通过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);
        QueryTimeseriesMetaResponse queryTimeseriesMetaResponse = client.queryTimeseriesMeta(queryTimeseriesMetaRequest);
        System.out.println(queryTimeseriesMetaResponse.getTotalHits());
        for (TimeseriesMeta timeseriesMeta : queryTimeseriesMetaResponse.getTimeseriesMetas()) {
            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());
        }
    }