TimescaleDB API 参考超级函数间隙填充

time_bucket_gapfill()函数

社区社区功能在 Timescale 社区版中可用。点击了解更多。

介绍

按时间间隔聚合数据，同时填充缺失数据的间隙。

time_bucket_gapfill 的工作原理类似于 time_bucket，但增加了间隙填充功能。此组中的其他函数必须与 time_bucket_gapfill 在同一个查询中使用。它们控制如何处理缺失值。

重要

time_bucket_gapfill 必须用作查询或子查询中的顶级表达式。例如，您不能将 time_bucket_gapfill 嵌套在另一个函数中（例如 round(time_bucket_gapfill(...))），也不能将间隙填充调用的结果进行强制转换。如果您需要进行强制转换，可以在子查询中使用 time_bucket_gapfill，并让外部查询进行类型强制转换。

此组中的函数

桶

time_bucket_gapfill
按时间间隔将行分组，同时填充数据中的间隙

插值器

interpolate
通过线性插值填充缺失值
locf
通过将最后观察到的值向前推进以填充缺失值

函数详细信息

time_bucket_gapfill(
  bucket_width INTERVAL | INTEGER,
  time TIMESTAMPTZ | INTEGER,
  [, timezone TEXT]
  [, start TIMESTAMPTZ | INTEGER]
  [, finish TIMESTAMPTZ | INTEGER]
) RETURNS TIMESTAMPTZ

将数据分组到基于时间间隔的桶中，同时填充缺失数据的间隙。如果您没有提供间隙填充算法，例如 locf 或 interpolate，则间隙将在返回的数据中以 NULL 表示。

必需参数
名称类型描述
bucket_widthINTERVAL, INTEGER一个 PostgreSQL 时间间隔，用于指定每个桶的长度。例如，使用 1 day 获取每日桶。如果您的时间列是基于整数的，则仅使用 INTEGER。
timeTIMESTAMPTZ, INTEGER用于确定桶的时间戳
可选参数
名称类型描述
timezoneTEXT用于分组的时间区域。例如，Europe/Berlin。在 TimescaleDB 2.9 或更高版本中可用。不适用于基于整数的时间。如果您有一个未类型的 start 或 finish 参数和一个 timezone 参数，您可能会遇到一个问题，即您没有为预期的参数传递参数。要解决此问题，请命名您的参数或显式地对其进行类型转换。
startTIMESTAMPTZ, INTEGER要进行间隙填充的时期的开始。start 之前的值将被传递，但不会执行间隙填充。如果您的时间列是基于整数的，则仅使用 INTEGER。最佳做法是使用 WHERE 子句。指定 start 是遗留行为。WHERE 性能更高，因为查询规划器可以通过约束排除过滤掉分块。
finishTIMESTAMPTZ, INTEGER要进行间隙填充的时期的结束。finish 之后的值将被传递，但不会执行间隙填充。如果您的时间列是基于整数的，则仅使用 INTEGER。最佳做法是使用 WHERE 子句。指定 finish 是遗留行为。WHERE 性能更高，因为查询规划器可以通过约束排除过滤掉分块。
返回值
列类型描述
time_bucket_gapfillTIMESTAMPTZ时间桶的开始时间。
interpolate(
  value SMALLINT | INTEGER | BIGINT | REAL | DOUBLE PRECISION
  [, prev EXPRESSION]
  [, next EXPRESSION]
) RETURNS SMALLINT | INTEGER | BIGINT | REAL | DOUBLE PRECISION

通过线性插值填充缺失值。与 time_bucket_gapfill 在同一个查询中使用。interpolate 不能嵌套在另一个函数调用中。

必需参数
名称类型描述
valueSMALLINT, INTEGER, BIGINT, REAL, DOUBLE PRECISION要进行插值的价值
可选参数
名称类型描述
prev表达式如果间隙填充没有可用的前一个值，请使用 prev 查找表达式来获取前一个值。例如，您可以使用 prev 来填充查询时间范围内的第一个桶。表达式必须返回一个 (time, value) 元组，其类型与分组的时间和值相对应。
next表达式如果间隙填充没有可用的下一个值，请使用 next 查找表达式来获取下一个值。例如，您可以使用 next 来填充查询时间范围内的最后一个桶。表达式必须返回一个 (time, value) 元组，其类型与分组的时间和值相对应。
返回值
列类型描述
interpolateSMALLINT, INTEGER, BIGINT, REAL, DOUBLE PRECISION间隙填充的值。返回类型是 value 的类型。
locf(
  value ANY ELEMENT
  [, prev EXPRESSION]
  [, treat_null_as_missing BOOLEAN]
) RETURNS ANY ELEMENT

通过将最后观察到的值向前推进以填充缺失值。与 time_bucket_gapfill 在同一个查询中使用。locf 不能嵌套在另一个函数调用中。

必需参数
名称类型描述
value任意元素要向前推进的值
可选参数
名称类型描述
prev表达式如果间隙填充没有可用的前一个值，请使用 prev 查找表达式来获取前一个值。例如，您可以使用 prev 来填充查询时间范围内的第一个桶。
treat_null_as_missing布尔值当为 true 时，NULL 值将被忽略，并且只有非 NULL 值会被向前推进。
返回值
列类型描述
locf任意元素间隙填充的值。返回类型是 value 的类型。

扩展示例

在没有间隙填充算法的情况下使用 time_bucket_gapfill

获取每日平均指标值。使用 time_bucket_gapfill 而不指定间隙填充算法。这会将缺失值保留为 NULL

SELECT time_bucket_gapfill('1 day', time) AS day,
    avg(value) as value
    FROM metrics
    WHERE time > '2021-12-31 00:00:00+00'::timestamptz
        AND time < '2022-01-10 00:00:00-00'::timestamptz
    GROUP BY day
    ORDER BY day desc;
day                    |              value
-----------------------+--------------------
2022-01-09 00:00:00+00 |                   
2022-01-08 00:00:00+00 |  48.61293155993108
2022-01-07 00:00:00+00 | 54.388267525986485
2022-01-06 00:00:00+00 |                   
2022-01-05 00:00:00+00 | 58.257520634785266
2022-01-04 00:00:00+00 |  46.09172424261765
2022-01-03 00:00:00+00 |  42.53498707820027
2022-01-02 00:00:00+00 |                   
2022-01-01 00:00:00+00 |  47.84420001415975
2021-12-31 00:00:00+00 |                   
(10 rows)

使用 time_bucket_gapfill 并将最后一个值向前推进

获取每日平均指标值。如果缺少值，使用 locf 将最后一个值向前推进。请注意，avg 嵌套在 locf 中，而不是相反。

SELECT time_bucket_gapfill('1 day', time) AS day,
    locf(avg(value)) as value
    FROM metrics
    WHERE time > '2021-12-31 00:00:00+00'::timestamptz
        AND time < '2022-01-10 00:00:00-00'::timestamptz
    GROUP BY day
    ORDER BY day desc;
day                    |              value
-----------------------+--------------------
2022-01-09 00:00:00+00 |  48.61293155993108
2022-01-08 00:00:00+00 |  48.61293155993108
2022-01-07 00:00:00+00 | 54.388267525986485
2022-01-06 00:00:00+00 | 58.257520634785266
2022-01-05 00:00:00+00 | 58.257520634785266
2022-01-04 00:00:00+00 |  46.09172424261765
2022-01-03 00:00:00+00 |  42.53498707820027
2022-01-02 00:00:00+00 |  47.84420001415975
2022-01-01 00:00:00+00 |  47.84420001415975
2021-12-31 00:00:00+00 |                   
(10 rows)

使用 time_bucket_gapfill 并使用线性插值

获取每日平均指标值。如果缺少值，使用 interpolate 对其进行线性插值。请注意，avg 嵌套在 interpolate 中。

SELECT time_bucket_gapfill('1 day', time) AS day,
    interpolate(avg(value)) as value
    FROM metrics
    WHERE time > '2021-12-31 00:00:00+00'::timestamptz
        AND time < '2022-01-10 00:00:00-00'::timestamptz
    GROUP BY day
    ORDER BY day desc;
day                    |              value
-----------------------+--------------------
2022-01-09 00:00:00+00 |                   
2022-01-08 00:00:00+00 |  48.61293155993108
2022-01-07 00:00:00+00 | 54.388267525986485
2022-01-06 00:00:00+00 |  56.32289408038588
2022-01-05 00:00:00+00 | 58.257520634785266
2022-01-04 00:00:00+00 |  46.09172424261765
2022-01-03 00:00:00+00 |  42.53498707820027
2022-01-02 00:00:00+00 | 45.189593546180014
2022-01-01 00:00:00+00 |  47.84420001415975
2021-12-31 00:00:00+00 |                   
(10 rows)

使用带时间区域参数的 time_bucket_gapfill

获取每日平均指标值，使用 Europe/Berlin 作为时间区域。请注意，每日时间桶现在从 23:00 UTC 开始，这相当于所选日期的柏林午夜

SELECT time_bucket_gapfill('1 day', time, 'Europe/Berlin') AS day,
    interpolate(avg(value)) as value
    FROM metrics
    WHERE time > '2021-12-31 00:00:00+00'::timestamptz
        AND time < '2022-01-10 00:00:00-00'::timestamptz
    GROUP BY day
    ORDER BY day desc;
day                    |              value
-----------------------+--------------------
2022-01-09 23:00:00+00 |                   
2022-01-08 23:00:00+00 |  48.65079127913703
2022-01-07 23:00:00+00 |  47.31847777099154
2022-01-06 23:00:00+00 |  55.98845740343859
2022-01-05 23:00:00+00 |  55.61667401777108
2022-01-04 23:00:00+00 |  58.74115574522012
2022-01-03 23:00:00+00 |  45.77993635988273
2022-01-02 23:00:00+00 |  41.78689923453202
2022-01-01 23:00:00+00 | 24.324313477743974
2021-12-31 23:00:00+00 |  48.86680377661261
2021-12-30 23:00:00+00 |                   
(11 rows)

关键字

间隙填充超级函数工具包

在此页面上发现问题？报告问题 或 编辑此页面 在 GitHub 上。

上一个candlestick_agg下一个percentile_agg 和 uddsketch

相关内容

间隙填充和插值
填充时间序列数据中的间隙
最后观察到的值向前推进
通过将最后观察到的值向前推进以填充数据中的间隙
时间桶间隙填充
在计算时间桶时填充时间序列数据中的间隙
超级函数
使用超级函数简化数据分析
降采样函数
降采样函数的 API 参考
days_in_month()
计算给定时间戳的月份中的天数