gauge_agg() 函数

工具包TimescaleDB 工具包函数在 Timescale 社区版下可用。它们自动包含在 Timescale 中，但必须为自托管 TimescaleDB 单独安装。单击以了解更多信息。

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

如果您的值只能增加，请改用 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 中的访问器函数以执行最终计算。或者，将聚合传递到汇总函数以将多个仪表聚合合并为更大的聚合。

示例

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


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` 创建的仪表聚合
`method`	`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` 创建的仪表聚合
`method`	`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()

相关内容