gauge_agg()functions

工具包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()functions

相关超函数组

两步聚合

本组中的函数

警告

聚合

访问器

汇总

变异器

函数详细信息

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()functions

介绍

相关超函数组

两步聚合

本组中的函数

警告

聚合

访问器

汇总

变异器

函数详细信息

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()

相关内容