本文介绍配置、查询、删除预降采样的方法以及预降采样的最佳实践。

预降采样介绍

预降采样是一种预计算的方法。在数据写入时根据配置的预降采样规则将数据降低精度后单独存储，查询时按查询条件中指定的降采样精度自动查询最接近预降采样精度的数据，然后交由执行引擎进行后续处理，以减少实时查询需要计算的数据量，降低访问延迟。时序引擎版本需为3.4.19以上。

与连续查询相比预降采样主要有以下优势：
  • 写入即可见，无需连续查询的执行等待时间。
  • 性能高，对于写入性能无影响，写入时实时转存数据。
  • 预降采样数据和原始数据存储在同一张表中，预降采样查询时自动匹配最佳规则的数据，规则不匹配时，自动切换到原始数据查询。

配置预降采样规则

在配置预降采样规则后，对于已经写入的数据不会生效。如果在数据库级别配置预降采样规则，该规则对数据库下所有的数据都生效。预降采样数据和原始数据可以配置不同的数据有效期（TTL），预降采样数据默认使用数据库级别设置的TTL。

使用SQL语句配置预降采样规则

使用如下SQL语句配置预降采样规则，表级别的预降采样规则只支持通过SQL配置。

示例

  • 设置预降采样精度为1小时，并对预降采样周期执行sum和max预计算。
    CREATE PREDOWNSAMPLE `1h` AGGREGATORS (`sum`, `max`) ON sensor;
  • 设置预降采样的数据有效期（TTL）为90天。
    CREATE PREDOWNSAMPLE `1h` AGGREGATORS (`sum`, `max`) TTL `90d` ON sensor;

语法参考：CREATE PREDOWNSAMPLE。

使用API配置预降采样规则

请求路径和方法

请求路径请求方法描述
/api/database
  • POST
  • PUT
配置指定数据库的预降采样规则。使用POST方法会创建数据库。如果数据库已经存在，需要使用PUT方法来更新预降采样规则。
说明 实例创建后，会自动创建default数据库，需要使用PUT方法更新降采样规则。

请求参数

名称是否必需描述
name是数据库名称。 例如：default。
downsampleRules是聚合规则列表。JSON格式。每次更新规则时为全量更新。

聚合规则列表参数

名称是否必需描述举例
aggregator是聚合函数。更多信息，请参见支持的聚合函数。
说明 预降采样不支持使用avg函数，但可以通过count和sum函数计算平均值。如果存在覆盖写的情况，可能会出现数据重复相加导致平均值结果不精确。
sum、count、max、min、first、last、median。
intervals是聚合时间窗口列表。支持的单位：s代表秒，m代表分钟，h代表小时，d代表天。["10m", "1h"] ，表示对10分钟和1小时两个时间间隔做预降采样。

请求示例

PUT /api/database

{
    "name": "default",
    "downsampleRules": {
        "rules": [
            {
                "aggregator": "sum",
                "intervals": [
                    "1m",
                    "1h"
                ]
            },
            {
                "aggregator": "max",
                "intervals": [
                    "1m",
                    "1h"
                ]
            }
        ]
    }
}

响应说明

响应状态码为200。

查询预降采样规则

可以使用API或者SQL语句来查询预降采样规则，在查询数据时，如果同时配置了数据库和表级别的预降采样规则，优先匹配表级别的预降采样规则。推荐您使用SQL语句查询预降采样规则。

使用SQL语句查询预降采样规则

使用如下SQL语句可以查询所有已经配置的预降采样规则。

示例

  • 查询数据库所有的预降采样规则。
    SHOW PREDOWNSAMPLES
  • 查询指定数据表sensor的预降采样规则。
    SHOW PREDOWNSAMPLES ON sensor

语法参考：SHOW PREDOWNSAMPLES。

使用API查询预降采样规则

请求路径和方法

请求路径请求方法描述
/api/databaseGET查询已经配置的预降采样规则。

请求示例

[{
    "name": "default",
    "downsampleRules": {
        "rules": [
            {
                "aggregator": "sum",
                "intervals": [
                    "1m",
                    "1h"
                ]
            },
            {
                "aggregator": "max",
                "intervals": [
                    "1m",
                    "1h"
                ]
            }
        ]
    }
}]

响应说明

响应状态码为200。

删除预降采样规则

使用如下SQL语句可以删除预降采样规则。

示例

DROP PREDOWNSAMPLE `1h` AGGREGATORS (`sum`, `max`) ON sensor;
重要 删除预降采样规则后，已经生效的预降采样数据不会立即被删除，但在查询规则时不会查询已经删除的预降采样规则。

语法参考：DROP PREDOWNSAMPLE。

预降采样数据查询匹配原则

  • 当同时存在数据库级别规则和表级别规则时，预降采样查询数据时优先匹配表级别规则。
  • 当查询请求指定的降采样精度与预降采样不能精确匹配时，选择最优的预降采样精度查询。推荐设置预降采样时间精度为1m、10m、1h、1d，可以满足绝大多数的降精度查询场景。
    说明 最优预降采样精度选择的规则是能整除查询请求降采样精度的最大值。例如，预降采样精度有1m、5m、8m和15m，查询请求的降采样精度为10m，则最优预降采样精度为5m。
  • 当没有满足条件的预聚合时间窗口时，从原始数据中进行降采样查询。

查询预降采样数据

使用SQL语句查询预降采样数据

默认情况下，降采样查询数据是从原始数据中进行查询。如果要从预降采样数据中查询数据需要在查询语句中使用Hint（/*+ PREDOWNSAMPLE */）。

SELECT /*+ PREDOWNSAMPLE */ sum(temperature) from sensor
WHERE time >= 1619074800000 AND time <= 1619085600000
SAMPLE BY 1h

时间序列数据库TSDB兼容查询预降采样数据

时间序列数据库TSDB兼容使用API多值查询、API单值查询、SDK查询三种方式查询预降采样数据。

使用API多值查询预降采样数据

使用API查询数据时，需要添加downsampleSource参数来指定查询数据源。具体操作，请参见多值数据查询。

请求路径和方法

请求路径请求方法描述
/api/mqueryGET查询预降采样数据。

请求参数

名称是否必须描述示例
downsampleSource否指定查询数据源。取值：
  • raw（默认值）：原始数据。
  • downsample：预降采样数据。
downsample

请求示例

POST /api/mquery

{
    "end": 1619085600000,
    "queries": [
        {
            "downsampleDataSource" : "downsample",
            "metric": "aggMetric",
            "fields" : [
                {
                    "field" : "score",
                    "aggregator" : "none",
                    "downsample" : "1h-sum"
                }
            ],
                      "tags":{
                    "sensor":"IOTE_8859_0005"
                  }
        }
    ],
    "start": 1619074800000
}

使用API单值查询预降采样数据

API单值查询接口兼容OpenTSDB接口，也支持Grafana通过OpenTSDB插件源来配置数据源访问。但需要将metric配置成metric@field##downsample的形式，其中，metric表示要访问的table，field表示要访问的值，downsample是固定后缀表示需要查询预降采样数据。

使用SDK查询预降采样数据

查询降采样数据时，需要在MultiFieldSubQuery Builder设定downsampleDataSource参数。

示例

long startTime = 1619074800000;
long endTime = 1619085600000;
final String metric = "wind";
final String field = "speed";
MultiFieldSubQueryDetails fieldSubQueryDetails = MultiFieldSubQueryDetails
        .field(field)
        .aggregator(Aggregator.SUM)
        .downsample("1h-sum")
        .build();
MultiFieldSubQuery subQuery = MultiFieldSubQuery
        .metric(metric)
        .fieldsInfo(fieldSubQueryDetails)
        // 从预降采样查询
        .downsampleDataSource(DownsampleDataSource.DOWNSAMPLE)
        .build();
MultiFieldQuery query = MultiFieldQuery.
        start(startTime).
        end(endTime).
        sub(subQuery).
        build();
List<MultiFieldQueryResult> result = tsdb.multiFieldQuery(query);

参数说明

DownsampleDataSource 参数的可选值及其含义为：
  • DOWNSAMPLE：预降采样数据查询。
  • RAW：原始数据查询。如果参数没有被指定，默认为RAW。

使用SDK多值查询预降采样数据，请参见SDK多值读取。

预降采样的最佳配置

秒级采样频率场景

对于秒级采样频率的场景，推荐配置1m、1h、1d粒度的预降采样规则来满足任意分钟、任意小时、任意天级别的降采样查询需求。

  • 配置sum、count、min、max4种常用聚合函数在1m、1h、1d粒度的预降采样规则。
    CREATE PREDOWNSAMPLE `1m` AGGREGATORS (`sum`, `count`, `min`, `max`) ON sensor;
CREATE PREDOWNSAMPLE `1h` AGGREGATORS (`sum`, `count`, `min`, `max`) ON sensor;
CREATE PREDOWNSAMPLE `1d` AGGREGATORS (`sum`, `count`, `min`, `max`) ON sensor;
  • 基于分钟粒度的预降采样规则，满足任意分钟级别的降采样查询。
    SELECT /*+ PREDOWNSAMPLE */ sum(temperature), max(temperature) from sensor
WHERE time >= 1619074800000 AND time <= 1619085600000
SAMPLE BY <N>m;
  • 基于小时粒度的预降采样规则，满足任意小时级别的降采样查询。
    SELECT /*+ PREDOWNSAMPLE */ sum(temperature), max(temperature) from sensor
WHERE time >= 1619074800000 AND time <= 1619085600000
SAMPLE BY <N>h;
  • 基于天粒度的预降采样规则，满足任意天级别的降采样查询。
    SELECT /*+ PREDOWNSAMPLE */ sum(temperature), max(temperature) from sensor
WHERE time >= 1619074800000 AND time <= 1619600400000
SAMPLE BY <N>d;

分钟级采样频率场景

对于分钟级采样频率的场景，推荐配置1h、1d粒度的预降采样规则来满足任意小时、任意天级别的降采样查询需求。

  • 配置sum、count、min、max4种常用聚合函数在1h、1d粒度的预降采样规则。
    CREATE PREDOWNSAMPLE `1h` AGGREGATORS (`sum`, `count`, `min`, `max`) ON sensor;
CREATE PREDOWNSAMPLE `1d` AGGREGATORS (`sum`, `count`, `min`, `max`) ON sensor;
  • 基于小时粒度的预降采样规则，满足任意小时级别的降采样查询。
    SELECT /*+ PREDOWNSAMPLE */ sum(temperature), max(temperature) from sensor
WHERE time >= 1619074800000 AND time <= 1619085600000
SAMPLE BY <N>h;
  • 基于天粒度的预降采样规则，满足任意天级别的降采样查询。
    SELECT /*+ PREDOWNSAMPLE */ sum(temperature), max(temperature) from sensor
WHERE time >= 1619074800000 AND time <= 1619600400000
SAMPLE BY <N>d;