gauge_agg() 函数

工具包TimescaleDB 工具包函数在 Timescale 社区版中可用。它们已自动包含在 Timescale 中，但对于自托管的 TimescaleDB，必须单独安装。点击了解更多。

Timescale Cloud：性能、扩展性、企业版

自托管产品

MST

分析来自仪表的数据。与计数器不同，仪表值可以增加也可以减少。

如果您的值只能增加，请改用 counter_agg 以适当处理重置。

此组中的函数

警告

此函数组包含一些实验性函数。实验性函数在未来版本中可能会更改或删除。我们不建议在生产环境中使用它们。实验性函数带有实验性标签。

gauge_agg: 实验性将仪表数据聚合成中间形式以供进一步分析

corr: 实验性从仪表聚合中计算相关系数
delta: 实验性从仪表聚合中计算仪表的变化
extrapolated_delta: 实验性从仪表聚合中计算外推变化
extrapolated_rate: 实验性从仪表聚合中计算外推变化率
gauge_zero_time: 实验性计算仪表值预计为零的时间
idelta_left: 实验性计算仪表聚合左侧（或最早）边缘的瞬时变化
idelta_right: 实验性计算仪表聚合右侧（或最新）边缘的瞬时变化
intercept: 实验性从仪表聚合中计算 y 轴截距
interpolated_delta: 实验性计算仪表的变化，必要时在边界处进行值插值
interpolated_rate: 实验性计算仪表的变化率，必要时在边界处进行值插值
irate_left: 实验性计算仪表聚合左侧（或最早）边缘的瞬时变化率
irate_right: 实验性计算仪表聚合右侧（或最新）边缘的瞬时变化率
num_changes: 实验性从仪表聚合中获取仪表值变化的次数
num_elements: 实验性从仪表聚合中获取具有不同时间戳的点数
rate: 实验性从仪表聚合中计算变化率
slope: 实验性从仪表聚合中计算斜率
time_delta: 实验性从仪表聚合中计算第一个和最后一个时间之间的差值

rollup: 实验性合并多个仪表聚合

with_bounds: 实验性为仪表聚合添加边界

函数详情

gauge_agg(
  ts TIMESTAMPTZ,
  value DOUBLE PRECISION
  [, bounds TSTZRANGE]
) RETURNS GaugeSummary

这是对仪表数据执行任何聚合计算的第一步。使用 gauge_agg 从您的数据创建中间聚合。此中间形式可由本组中的一个或多个访问器用于计算最终结果。可选地，您可以在应用访问器之前，使用 rollup() 组合多个中间聚合对象。

必填参数

名称	类型	描述
`ts`	`TIMESTAMPTZ`	每个点的时间
`value`	`DOUBLE PRECISION`	每个点的仪表值

可选参数

名称	类型	描述
`bounds`	`TSTZRANGE`	可以输入到此聚合的最小和最大可能时间。外推法需要边界，但其他访问器函数不需要。如果您在聚合创建时未指定边界，则可以稍后使用 `with_bounds` 函数添加它们。

返回值

列	类型	描述
`gauge_agg`	`GaugeSummary`	仪表聚合，包含有关变量的中间形式数据。将聚合传递给仪表聚合 API 中的访问器函数以执行最终计算。或者，将聚合传递给 rollup 函数以将多个仪表聚合组合成更大的聚合。

示例

创建仪表聚合以汇总每日仪表数据


SELECT
  time_bucket('1 day'::interval, ts) as dt,
  gauge_agg(ts, val) AS cs
FROM foo
WHERE id = 'bar'
GROUP BY time_bucket('1 day'::interval, ts)

corr(
    summary GaugeSummary
) RETURNS DOUBLE PRECISION

从仪表聚合中计算相关系数。此计算使用线性最小二乘拟合，并返回一个介于 0.0 到 1.0 之间的值，分别表示无相关性到最强相关性。

必填参数

名称	类型	描述
`summary`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表聚合

返回值

列	类型	描述
`corr`	`DOUBLE PRECISION`	以时间为自变量、仪表值为因变量计算的相关系数。

示例

计算相关系数以确定仪表值与时间之间线性拟合的优劣


SELECT
    id,
    bucket,
    corr(summary)
FROM (
    SELECT
        id,
        time_bucket('15 min'::interval, ts) AS bucket,
        gauge_agg(ts, val) AS summary
    FROM foo
    GROUP BY id, time_bucket('15 min'::interval, ts)
) t

delta(
    summary GaugeSummary
) RETURNS DOUBLE PRECISION

获取仪表在一段时间内的变化。这是简单的增量，通过从第一个观测值中减去最后一个观测值来计算。

必填参数

名称	类型	描述
`summary`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表聚合

返回值

列	类型	描述
`delta`	`DOUBLE PRECISION`	仪表在桶化区间内的变化

示例

获取表 foo 中每个仪表在整个时间间隔内的变化


SELECT
    id,
    delta(summary)
FROM (
    SELECT
        id,
        gauge_agg(ts, val) AS summary
    FROM foo
    GROUP BY id
) t

extrapolated_delta(
    summary GaugeSummary,
    method TEXT
) RETURNS DOUBLE PRECISION

计算仪表在仪表聚合中由边界指定的时间段内的变化。extrapolated_delta 函数需要指定边界。您可以在原始的 gauge_agg 调用中提供它们，或通过在现有仪表聚合上使用 with_bounds 函数来添加它们。

必填参数

名称	类型	描述
`summary`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表聚合
`方法`	`TEXT`	要使用的外推方法。不区分大小写。唯一允许的值是 `prometheus`，表示 Prometheus 外推协议。

返回值

列	类型	描述
`extrapolated_delta`	`DOUBLE PRECISION`	仪表在仪表聚合时间段内的外推变化。

示例

外推每个 15 分钟间隔内仪表的变化


SELECT
    id,
    bucket,
    extrapolated_delta(
        with_bounds(
            summary,
            toolkit_experimental.time_bucket_range('15 min'::interval, bucket)
        ),'prometheus'
    )
FROM (
    SELECT
        id,
        time_bucket('15 min'::interval, ts) AS bucket,
        gauge_agg(ts, val) AS summary
    FROM foo
    GROUP BY id, time_bucket('15 min'::interval, ts)
) t;

extrapolated_rate(
    summary GaugeSummary,
    method TEXT
) RETURNS DOUBLE PRECISION

计算仪表在仪表聚合中由边界指定的时间段内的变化率。extrapolated_rate 函数需要指定边界。您可以在原始的 gauge_agg 调用中提供它们，或通过在现有仪表聚合上使用 with_bounds 函数来添加它们。

必填参数

名称	类型	描述
`summary`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表聚合
`方法`	`TEXT`	要使用的外推方法。不区分大小写。唯一允许的值是 `prometheus`，表示 Prometheus 外推协议。

返回值

列	类型	描述
`extrapolated_rate`	`DOUBLE PRECISION`	仪表在仪表聚合时间段内的外推变化率。

示例


SELECT
    id,
    bucket,
    extrapolated_rate(
        with_bounds(
            summary,
            toolkit_experimental.time_bucket_range('15 min'::interval, bucket)
        ),'prometheus'
    )
FROM (
    SELECT
        id,
        time_bucket('15 min'::interval, ts) AS bucket,
        gauge_agg(ts, val) AS summary
    FROM foo
    GROUP BY id, time_bucket('15 min'::interval, ts)
) t;

gauge_zero_time(
    summary GaugeSummary
) RETURNS TIMESTAMPTZ

计算仪表值模型为零的时间。这是仪表值和时间之间线性拟合的 x 轴截距。

必填参数

名称	类型	描述
`summary`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表聚合

返回值

列	类型	描述
`gauge_zero_time`	`TIMESTAMPTZ`	仪表值预计为零的时间

示例

估计仪表启动的时间


SELECT
    id,
    bucket,
    gauge_zero_time(summary)
FROM (
    SELECT
        id,
        time_bucket('15 min'::interval, ts) AS bucket,
        gauge_agg(ts, val) AS summary
    FROM foo
    GROUP BY id, time_bucket('15 min'::interval, ts)
) t

idelta_left(
  summary GaugeSummary
) RETURNS DOUBLE PRECISION

计算仪表聚合左侧（或最早）边缘的瞬时变化。这等于第二个值减去第一个值。

必填参数

名称	类型	描述
`summary`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表聚合

返回值

列	类型	描述
`idelta_left`	`DOUBLE PRECISION`	仪表聚合左侧（或最早）边缘的瞬时增量

示例

获取每个 15 分钟仪表聚合开始时的瞬时变化


SELECT
    id,
    bucket,
    idelta_left(summary)
FROM (
    SELECT
        id,
        time_bucket('15 min'::interval, ts) AS bucket,
        gauge_agg(ts, val) AS summary
    FROM foo
    GROUP BY id, time_bucket('15 min'::interval, ts)
) t

idelta_right(
  summary GaugeSummary
) RETURNS DOUBLE PRECISION

计算仪表聚合右侧（或最新）边缘的瞬时变化。这等于最后一个值减去倒数第二个值。

必填参数

名称	类型	描述
`summary`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表聚合

返回值

列	类型	描述
`idelta_right`	`DOUBLE PRECISION`	仪表聚合右侧（或最新）边缘的瞬时增量

示例

获取每个 15 分钟仪表聚合结束时的瞬时变化


SELECT
    id,
    bucket,
    idelta_right(summary)
FROM (
    SELECT
        id,
        time_bucket('15 min'::interval, ts) AS bucket,
        gauge_agg(ts, val) AS summary
    FROM foo
    GROUP BY id, time_bucket('15 min'::interval, ts)
) t

intercept(
    summary GaugeSummary
) RETURNS DOUBLE PRECISION

计算仪表值和时间之间线性最小二乘拟合的 y 轴截距。这对应于 PostgreSQL 纪元 (2000-01-01 00:00:00+00) 的预测值。您可以将 y 轴截距与斜率一起使用，以绘制最佳拟合线。

必填参数

名称	类型	描述
`summary`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表聚合

返回值

列	类型	描述
`intercept`	`DOUBLE PRECISION`	线性最小二乘拟合的 y 轴截距

示例

计算每个 15 分钟仪表聚合的线性拟合 y 轴截距


SELECT
    id,
    bucket,
    intercept(summary)
FROM (
    SELECT
        id,
        time_bucket('15 min'::interval, ts) AS bucket,
        gauge_agg(ts, val) AS summary
    FROM foo
    GROUP BY id, time_bucket('15 min'::interval, ts)
) t

interpolated_delta(
    summary GaugeSummary,
    start TIMESTAMPTZ,
    interval INTERVAL
    [, prev GaugeSummary]
    [, next GaugeSummary]
) RETURNS DOUBLE PRECISION

计算仪表在仪表聚合所涵盖时间段内的变化。不需要时间段精确边界处的数据点。如果需要，函数会从相邻的仪表聚合中插值边界处的仪表值。

必填参数

名称	类型	描述
`summary`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表聚合
`start`	`TIMESTAMPTZ`	计算增量的时间段的开始
`interval`	`INTERVAL`	计算增量的时间段的长度

可选参数

名称	类型	描述
`prev`	`GaugeSummary`	前一个时间间隔的仪表聚合，用于插值 `start` 处的值。如果为 `NULL`，则 `summary` 中的第一个时间戳用作时间间隔的开始。
`next`	`GaugeSummary`	下一个时间间隔的仪表聚合，用于插值 `start + interval` 处的值。如果为 `NULL`，则 `summary` 中的最后一个时间戳用作时间间隔的结束。

返回值

列	类型	描述
`interpolated_delta`	`DOUBLE PRECISION`	时间间隔的第一个点和最后一个点之间的增量。如果原始数据中缺少第一个和最后一个点的精确值，则这些值将从相邻的仪表聚合中进行线性插值。

示例

计算每个 15 分钟间隔的仪表增量，如果数据中不存在，则使用插值获取间隔边界处的值


SELECT
    id,
    bucket,
    interpolated_delta(
        summary,
        bucket,
        '15 min',
        LAG(summary) OVER (PARTITION BY id ORDER by bucket),
        LEAD(summary) OVER (PARTITION BY id ORDER by bucket)
    )
FROM (
    SELECT
        id,
        time_bucket('15 min'::interval, ts) AS bucket,
        gauge_agg(ts, val) AS summary
    FROM foo
    GROUP BY id, time_bucket('15 min'::interval, ts)
) t

interpolated_rate(
    summary GaugeSummary,
    start TIMESTAMPTZ,
    interval INTERVAL
    [, prev GaugeSummary]
    [, next GaugeSummary]
) RETURNS DOUBLE PRECISION

计算仪表在一段时间内的变化率。不需要时间段精确边界处的数据点。如果需要，函数会从相邻的仪表聚合中插值边界处的仪表值。

必填参数

名称	类型	描述
`summary`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表聚合
`start`	`TIMESTAMPTZ`	计算变化率的时间段的开始
`interval`	`INTERVAL`	计算变化率的时间段的长度

可选参数

名称	类型	描述
`prev`	`GaugeSummary`	前一个时间间隔的仪表聚合，用于插值 `start` 处的值。如果为 `NULL`，则 `summary` 中的第一个时间戳用作时间间隔的开始。
`next`	`GaugeSummary`	下一个时间间隔的仪表聚合，用于插值 `start + interval` 处的值。如果为 `NULL`，则 `summary` 中的最后一个时间戳用作时间间隔的结束。

返回值

列	类型	描述
`interpolated_rate`	`DOUBLE PRECISION`	在指定边界之间仪表的每秒变化率。如果原始数据中缺少第一个和最后一个点的精确值，则这些值将从相邻的仪表聚合中进行线性插值。

示例

计算每个 15 分钟间隔的每秒变化率，如果数据中不存在，则使用插值获取间隔边界处的值


SELECT
    id,
    bucket,
    interpolated_rate(
        summary,
        bucket,
        '15 min',
        LAG(summary) OVER (PARTITION BY id ORDER by bucket),
        LEAD(summary) OVER (PARTITION BY id ORDER by bucket)
    )
FROM (
    SELECT
        id,
        time_bucket('15 min'::interval, ts) AS bucket,
        gauge_agg(ts, val) AS summary
    FROM foo
    GROUP BY id, time_bucket('15 min'::interval, ts)
) t

irate_left(
  summary GaugeSummary
) RETURNS DOUBLE PRECISION

计算仪表聚合左侧（或最早）边缘的瞬时变化率。这等于第二个值减去第一个值，再除以两点之间的时间差。此计算对于快速变化的仪表很有用。

必填参数

名称	类型	描述
`summary`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表聚合

返回值

列	类型	描述
`idelta_left`	`DOUBLE PRECISION`	仪表聚合左侧（或最早）边缘的瞬时变化率

示例

获取每个 15 分钟仪表聚合开始时的瞬时变化率


SELECT
    id,
    bucket,
    irate_left(summary)
FROM (
    SELECT
        id,
        time_bucket('15 min'::interval, ts) AS bucket,
        gauge_agg(ts, val) AS summary
    FROM foo
    GROUP BY id, time_bucket('15 min'::interval, ts)
) t

irate_right(
  summary GaugeSummary
) RETURNS DOUBLE PRECISION

计算仪表聚合右侧（或最新）边缘的瞬时变化率。这等于最后一个值减去倒数第二个值，再除以两点之间的时间差。此计算对于快速变化的仪表很有用。

必填参数

名称	类型	描述
`summary`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表聚合

返回值

列	类型	描述
`idelta_right`	`DOUBLE PRECISION`	仪表聚合右侧（或最新）边缘的瞬时变化率

示例

获取每个 15 分钟仪表聚合结束时的瞬时变化率


SELECT
    id,
    bucket,
    irate_right(summary)
FROM (
    SELECT
        id,
        time_bucket('15 min'::interval, ts) AS bucket,
        gauge_agg(ts, val) AS summary
    FROM foo
    GROUP BY id, time_bucket('15 min'::interval, ts)
) t

num_changes(
    summary GaugeSummary
) RETURNS BIGINT

获取仪表在仪表聚合所总结的时间段内变化的次数。

必填参数

名称	类型	描述
`summary`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表摘要

返回值

列	类型	描述
`num_changes`	`BIGINT`	仪表变化的次数

示例

获取仪表在每个 15 分钟间隔内变化的次数


SELECT
    id,
    bucket,
    num_changes(summary)
FROM (
    SELECT
        id,
        time_bucket('15 min'::interval, ts) AS bucket,
        gauge_agg(ts, val) AS summary
    FROM foo
    GROUP BY id, time_bucket('15 min'::interval, ts)
) t

num_elements(
    summary GaugeSummary
) RETURNS BIGINT

从仪表聚合中获取具有不同时间戳的点数。重复的时间戳将被忽略。

必填参数

名称	类型	描述
`summary`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表聚合

返回值

列	类型	描述
`num_elements`	`BIGINT`	具有不同时间戳的点数

示例

获取每个 15 分钟仪表聚合的点数


SELECT
    id,
    bucket,
    num_elements(summary)
FROM (
    SELECT
        id,
        time_bucket('15 min'::interval, ts) AS bucket,
        gauge_agg(ts, val) AS summary
    FROM foo
    GROUP BY id, time_bucket('15 min'::interval, ts)
) t

rate(
    summary GaugeSummary
) RETURNS DOUBLE PRECISION

计算仪表的变化率。这是简单的变化率，等于最后一个值减去第一个值，再除以经过的时间。

必填参数

名称	类型	描述
`summary`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表聚合

返回值

列	类型	描述
`rate`	`DOUBLE PRECISION`	仪表的变化率

示例

获取每个 id 在整个记录间隔内的变化率


SELECT
    id,
    rate(summary)
FROM (
    SELECT
        id,
        gauge_agg(ts, val) AS summary
    FROM foo
    GROUP BY id
) t

slope(
    summary GaugeSummary
) RETURNS DOUBLE PRECISION

计算仪表聚合的线性最小二乘拟合的斜率。因变量是仪表值，自变量是时间。时间总是以秒为单位，因此斜率估计的是每秒变化率。这与 rate 的结果相似，但在出现不频繁的异常大变化时，它能更准确地反映正常的仪表行为。

必填参数

名称	类型	描述
`summary`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表聚合

返回值

列	类型	描述
`slope`	`DOUBLE PRECISION`	线性最小二乘拟合的斜率

示例

计算每个 id 和每个 15 分钟间隔的仪表斜率


SELECT
    id,
    bucket,
    slope(summary)
FROM (
    SELECT
        id,
        time_bucket('15 min'::interval, ts) AS bucket,
        gauge_agg(ts, val) AS summary
    FROM foo
    GROUP BY id, time_bucket('15 min'::interval, ts)
) t

time_delta(
    summary GaugeSummary
) RETURNS DOUBLE PRECISION

获取仪表聚合中第一次和最后一次测量之间相差的秒数

必填参数

名称	类型	描述
`summary`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表聚合

返回值

列	类型	描述
`time_delta`	`DOUBLE PRECISION`	第一次和最后一次时间之间的差值，以秒为单位

示例

获取每个 15 分钟间隔内第一次和最后一次仪表读数之间的时间差。请注意，此差值不一定等于 15 分钟 * 60 秒 / 分钟，因为第一次和最后一次读数可能不精确地落在间隔边界上


SELECT
    id,
    bucket,
    time_delta(summary)
FROM (
    SELECT
        id,
        time_bucket('15 min'::interval, ts) AS bucket,
        gauge_agg(ts, val) AS summary
    FROM foo
    GROUP BY id, time_bucket('15 min'::interval, ts)
) t

rollup(
    cs GaugeSummary
) RETURNS GaugeSummary

此函数将多个仪表聚合合并为一个。这可用于将相邻间隔的聚合组合成一个更大的间隔，例如将每日聚合合并为每周或每月聚合。

必填参数

名称	类型	描述
`cs`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表聚合

返回值

列	类型	描述
`gauge_agg`	`GaugeSummary`	通过组合输入仪表聚合创建的新仪表聚合

with_bounds(
    summary GaugeSummary,
    bounds TSTZRANGE,
) RETURNS GaugeSummary

为已计算的仪表聚合添加时间边界。聚合上使用外推访问器时需要边界。

必填参数

名称	类型	描述
`cs`	`GaugeSummary`	使用 `gauge_agg` 创建的仪表聚合
`bounds`	`TSTZRANGE`	一个 `timestamptz` 范围，给出仪表聚合中允许的最小和最大时间

返回值

列	类型	描述
`gauge_agg`	`GaugeSummary`	应用了边界的新仪表聚合

示例

为每个 id 和每个 15 分钟间隔创建一个仪表聚合。然后为仪表聚合添加边界，以便您可以计算外推变化率


SELECT
    id,
    bucket,
    extrapolated_rate(
        with_bounds(
            summary,
            time_bucket_range('15 min'::interval, bucket)
        )
    )
FROM (
    SELECT
        id,
        time_bucket('15 min'::interval, ts) AS bucket,
        gauge_agg(ts, val) AS summary
    FROM foo
    GROUP BY id, time_bucket('15 min'::interval, ts)
) t

gauge_agg() 函数

相关超函数组

两步聚合

此组中的函数

警告

聚合

访问器

合并

修改器

函数详情

gauge_agg()

corr()

delta()

extrapolated_delta()

extrapolated_rate()

gauge_zero_time()

idelta_left()

idelta_right()

intercept()

interpolated_delta()

interpolated_rate()

irate_left()

irate_right()

num_changes()

num_elements()

rate()

slope()

time_delta()

rollup()

with_bounds()

gauge_agg() 函数

简介

相关超函数组

两步聚合

此组中的函数

警告

聚合

访问器

合并

修改器

函数详情

gauge_agg()

corr()

delta()

extrapolated_delta()

extrapolated_rate()

gauge_zero_time()

idelta_left()

idelta_right()

intercept()

interpolated_delta()

interpolated_rate()

irate_left()

irate_right()

num_changes()

num_elements()

rate()

slope()

time_delta()

rollup()

with_bounds()

相关内容