文档文档

Chronograf

使用仪表盘模板变量

Chronograf 仪表盘模板变量允许您更新单元格查询，而无需编辑查询，从而轻松与仪表盘单元格交互并探索数据。

使用模板变量

在创建 Chronograf 仪表盘时，在单元格查询和标题中使用预定义的模板变量或自定义模板变量。设置变量后，变量可在仪表盘用户界面 (UI) 中选择。

Use template variables

在单元格查询中使用模板变量

InfluxQL 和 Flux 都支持模板变量。

InfluxQL

在 InfluxQL 查询中，用冒号 (:) 包围模板变量名称，如下所示

SELECT :variable_name: FROM "telegraf"."autogen".:measurement: WHERE time < :dashboardTime:
在 InfluxQL 中引用模板变量

对于预定义的元查询（例如“字段键”和“标签值”），请勿向查询添加引号（单引号或双引号）。Chronograf 将按如下方式添加引号

SELECT :variable_name: FROM "telegraf"."autogen".:measurement: WHERE time < :dashboardTime:

对于自定义查询、CSV 或 map 查询，请按照标准的 InfluxQL 语法引用查询中的值

  • 对于数值，请勿引用。
  • 对于字符串值，请选择在变量定义中引用值（或不引用）。请参阅下面的字符串示例。

字符串引用提示

  • 当使用返回字符串的自定义元查询时，通常在仪表盘查询中使用变量值时引用它们，因为 InfluxQL 结果在返回时不带引号。
  • 如果您在正则表达式语法中使用模板变量字符串（当使用引号可能导致查询语法错误时），查询引用方法的灵活性尤其有用。
字符串示例

在定义模板变量时或在查询中添加单引号，但不要两者都添加。

在变量定义中添加单引号

如果您使用单引号定义名为 host 的自定义 CSV 变量

'host1','host2','host3'

请勿在查询中包含引号

SELECT mean("usage_user") AS "mean_usage_user" FROM "telegraf"."autogen"."cpu" 
WHERE "host" = :host: and time > :dashboardTime
在查询中添加单引号

如果您在不带引号的情况下定义名为 host 的自定义 CSV 变量

host1,host2,host3

请在查询中添加单引号

SELECT mean("usage_user") AS "mean_usage_user" FROM "telegraf"."autogen"."cpu" 
WHERE "host" = ':host:' and time > :dashboardTime

Flux

在 Flux 中，模板变量存储在 v 记录中。使用点或方括号表示法引用 v 记录内的变量键

from(bucket: v.bucket)
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r._field == v["Field key"])
  |> aggregateWindow(every: v.windowPeriod, fn: v.aggregateFunction)

在单元格标题中使用模板变量

要动态更改仪表盘单元格的标题，请使用 :variable-name: 语法。

例如，一个名为 field 的变量，其值为 temp，以及一个名为 location 的变量，其值为 San Antonio，请使用以下语法

:temp: data for :location:

显示为

Use template variables in cell titles

预定义的模板变量

Chronograf 包括由 Chronograf UI 中的元素控制的预定义模板变量。在单元格查询中使用预定义的模板变量。

InfluxQL 和 Flux 包含它们自己的一组预定义模板变量

InfluxQL Flux

dashboardTime

:dashboardTime: 模板变量由 Chronograf 仪表盘中的“时间”下拉菜单控制。

Dashboard time selector

如果使用相对时间，它表示下拉菜单中指定的时间偏移量（-5m、-15m、-30m 等），并假定时间相对于“now”。如果使用日期选择器定义的绝对时间，:dashboardTime: 将填充较低阈值。

SELECT "usage_system" AS "System CPU Usage"
FROM "telegraf".."cpu"
WHERE time > :dashboardTime:

要使用日期选择器指定过去的时间范围，请使用 :dashboardTime: 作为开始时间，并使用 :upperDashboardTime: 作为停止时间来构造查询。

upperDashboardTime

:upperDashboardTime: 模板变量由使用日期选择器指定的上限时间限制定义。

Dashboard date picker

当使用相对时间范围或使用绝对时间范围时的上限时间限制时，它将继承 now()。

SELECT "usage_system" AS "System CPU Usage"
FROM "telegraf".."cpu"
WHERE time > :dashboardTime: AND time < :upperDashboardTime:

interval

:interval: 模板变量由 Chronograf 仪表盘中的间隔下拉菜单定义。

Dashboard interval selector

在单元格查询中，它应在伴随聚合函数的 GROUP BY time() 子句中使用

SELECT mean("usage_system") AS "Average System CPU Usage"
FROM "telegraf".."cpu"
WHERE time > :dashboardtime:
GROUP BY time(:interval:)

向后兼容的 Flux 模板变量

Chronograf 1.9+ 支持 InfluxDB 2.0 变量模式，即将预定义的模板变量和自定义模板变量存储在 v 记录中，并使用点或方括号表示法引用变量。为了向后兼容，Chronograf 1.9+ 仍然支持以下不使用 v. 语法的预定义变量

v.timeRangeStart

v.timeRangeStart 模板变量由 Chronograf 仪表盘中的“时间”下拉菜单控制。

Dashboard time selector

如果使用相对时间，则此变量表示下拉菜单中指定的时间偏移量（-5m、-15m、-30m 等），并假定时间相对于“now”。如果使用日期选择器定义的绝对时间，则 v.timeRangeStart 将填充开始时间。

from(bucket: "telegraf/autogen")
  |> range(start: v.timeRangeStart)
  |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_system")

要使用日期选择器在过去指定不带“now”的时间范围，请使用 v.timeRangeStart 作为开始时间，并使用 v.timeRangeStop 作为停止时间。

v.timeRangeStop

v.timeRangeStop 模板变量由使用日期选择器指定的上限时间限制定义。

Dashboard date picker

对于相对时间范围，此变量继承 now()。对于绝对时间范围，此变量继承上限时间限制。

from(bucket: "telegraf/autogen")
  |> range(start: v.timeRangeStart, stop: v.timeRangeStop)
  |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_system")

v.windowPeriod

v.windowPeriod 模板变量由仪表盘单元格的显示宽度控制，并通过每个像素覆盖的时间长度计算得出。使用 v.windowPeriod 变量来限制下采样数据，以便每个像素最多显示一个点。

from(bucket: "telegraf/autogen")
  |> range(start: v.timeRangeStart)
  |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_system")
  |> aggregateWindow(every: v.windowPeriod, fn: mean)

创建自定义模板变量

Chronograf 允许您创建自定义模板变量，这些变量由元查询或 CSV 上传提供支持，这些元查询或 CSV 上传返回可能的数组值。

要创建模板变量

  1. 单击仪表盘顶部的模板变量，然后单击 + 添加变量。
  2. 从数据源下拉菜单中选择一个数据源。
  3. 为变量提供名称。
  4. 选择变量类型。类型定义了检索可能值数组的方法。
  5. 查看潜在值列表并选择默认值。如果使用 CSV 或 Map 类型，请上传或输入具有所需值的 CSV，格式正确，然后选择默认值。
  6. 单击创建。

创建后，模板变量可用于任何单元格的查询或标题中，并且变量的下拉菜单将包含在仪表盘的顶部。

模板变量类型

Chronograf 支持以下模板变量类型

数据库

数据库模板变量允许您从多个目标数据库中进行选择。

数据库元查询
数据库模板变量使用以下元查询来返回 InfluxDB 实例中所有数据库的数组。

SHOW DATABASES

单元格查询中的数据库变量示例

SELECT "purchases" FROM :databaseVar:."autogen"."customers"

数据库变量用例

当可视化具有相似或相同数据结构的多个数据库时，请使用数据库模板变量。变量使您可以在每个数据库的visualization之间快速切换。

测量

更改目标测量。

测量元查询
测量模板变量使用以下元查询来返回给定数据库中所有测量的数组。

SHOW MEASUREMENTS ON database_name

单元格查询中的测量变量示例

SELECT * FROM "animals"."autogen".:measurementVar:

测量变量用例

测量模板变量允许您在仪表盘中的单个单元格或多个单元格之间快速切换测量。

字段键

更改目标字段键。

字段键元查询
字段键模板变量使用以下元查询来返回给定数据库中给定测量中的所有字段键的数组。

SHOW FIELD KEYS ON database_name FROM measurement_name

单元格查询中的字段键变量示例

SELECT :fieldKeyVar: FROM "animals"."autogen"."customers"

字段键变量用例

如果您想在给定测量中快速切换字段键可视化，则字段键模板变量非常有用。

标签键

更改目标标签键。

标签键元查询
标签键模板变量使用以下元查询来返回给定数据库中给定测量中的所有标签键的数组。

SHOW TAG KEYS ON database_name FROM measurement_name

单元格查询中的标签键变量示例

SELECT "purchases" FROM "animals"."autogen"."customers" GROUP BY :tagKeyVar:

标签键变量用例

如果您想在给定测量中快速切换标签键可视化，则标签键模板变量非常有用。

标签值

更改目标标签值。

标签值元查询
标签值模板变量使用以下元查询来返回与指定测量和数据库中给定标签键关联的所有值的数组。

SHOW TAG VALUES ON database_name FROM measurement_name WITH KEY tag_key

单元格查询中的标签值变量示例

SELECT "purchases" FROM "animals"."autogen"."customers" WHERE "species" = :tagValueVar:

标签值变量用例

如果您想在给定测量中快速切换标签值可视化，则标签值模板变量非常有用。

CSV

使用自定义的逗号分隔值 (CSV) 列表更改查询的一部分。

CSV 示例

value1, value2, value3, value4

value1
value2
value3
value4

字符串字段值在 InfluxQL 中需要单引号。

'string1','string2','string3','string4'

单元格查询中的 CSV 变量示例

SELECT "purchases" FROM "animals"."autogen"."customers" WHERE "petname" = :csvVar:

CSV 变量用例

当变量所需的数组值无法使用元查询从 InfluxDB 中提取时，CSV 模板变量非常有用。它们允许您使用自定义变量值。

Map

使用 CSV 格式的自定义键值对列表更改查询的一部分。每个键值对的键用于填充仪表盘中的模板变量下拉菜单。值在处理单元格查询时使用。

CSV 示例

key1,value1
key2,value2
key3,value3
key4,value4
Map variable dropdown

将字符串字段值括在单引号中（InfluxQL 要求）。变量键不需要引号。

key1,'value1'
key2,'value2'
key3,'value3'
key4,'value4'

单元格查询中的 Map 变量示例

SELECT "purchases" FROM "animals"."autogen"."customers" WHERE "customer" = :mapVar:

Map 变量用例

当您需要将简单的名称或键映射或别名到更长或更复杂的值时，Map 模板变量非常有用。例如，您可能想要创建一个 :customer: 变量，该变量使用长的数字客户 ID (11394850823894034209) 填充单元格查询。使用 map 变量，您可以将简单名称别名到复杂值，因此您的客户列表将如下所示

Apple,11394850823894034209
Amazon,11394850823894034210
Google,11394850823894034211
Microsoft,11394850823894034212

客户名称将填充您的模板变量下拉菜单，而不是客户 ID。

InfluxQL 元查询

使用自定义元查询更改查询的一部分，该查询从 InfluxDB 中提取特定的值数组。InfluxQL 元查询变量允许您提取高度自定义的潜在值数组，并提供高级功能，例如基于其他模板变量过滤值。

Custom meta query

单元格查询中的自定义元查询变量示例

SELECT "purchases" FROM "animals"."autogen"."customers" WHERE "customer" = :customMetaVar:

InfluxQL 元查询变量用例

当预定义的模板变量类型无法返回您想要的值时，请使用自定义 InfluxQL 元查询模板变量。

Flux 查询

Flux 查询模板变量允许您使用 Flux 查询定义变量值。变量值从 Flux 查询返回的 _value 列中提取。

Flux 查询变量用例

当变量所需的值无法使用 InfluxQL 查询，或者您需要 Flux 的灵活性来返回所需的变量值列表时，Flux 查询模板变量非常有用。

文本

使用单个文本字符串更改查询的一部分。每个文本变量只有一个值，但此值很容易更改。

文本变量用例

文本模板变量允许您动态更改查询，例如一次为多个单元格添加或更改 WHERE 子句。您还可以使用文本模板变量来更改多个查询中使用的正则表达式。当解决影响多个可视化指标的事件时，它们非常有用。

保留变量名

以下变量名称是保留名称，创建模板变量时不能使用。Chronograf 接受作为 URL 查询参数的模板变量以及许多其他控制仪表盘中图形显示的参数。这些名称要么是预定义变量，要么会与现有的 URL 查询参数冲突。

  • :database
  • :measurement
  • :dashboardTime
  • :upperDashboardTime
  • :interval
  • :upper
  • :lower
  • :zoomedUpper
  • :zoomedLower
  • :refreshRate

高级模板变量用法

使用其他模板变量过滤模板变量

自定义 InfluxQL 元查询模板变量允许您使用其他现有模板变量来过滤潜在变量值的数组。

例如，假设您要列出与测量关联的所有字段键，但希望能够更改测量

  1. 创建一个名为 :measurementVar: 的模板变量（名称“measurement”是保留名称），该变量使用测量变量类型从 telegraf 数据库中提取所有测量。

    measurementVar

  2. 创建一个名为 :fieldKey: 的模板变量，该变量使用InfluxQL 元查询变量类型。以下元查询基于现有的 :measurementVar: 模板变量提取字段键列表。

    SHOW FIELD KEYS ON telegraf FROM :measurementVar:
    fieldKey

  3. 创建一个新的仪表盘单元格，该单元格在其查询中使用 fieldKey 和 measurementVar 模板变量。

    InfluxQL Flux

    SELECT :fieldKey: FROM "telegraf"..:measurementVar: WHERE time > :dashboardTime:

    from(bucket: "telegraf/")
  |> range(start: v.timeRangeStart)
  |> filter(fn: (r) =>
    r._measurement == v.measurementVar and
    r._field == v.fieldKey
  )

生成的仪表盘将像这样工作

Custom meta query filtering

在 URL 中定义模板变量

Chronograf 使用 URL 查询参数（也称为查询字符串参数）来设置 URL 中的显示选项和模板变量。这使得共享仪表盘链接变得容易，以便它们以特定状态加载，并选择特定的模板变量值。

URL 查询参数附加到 URL 的末尾，问号 (?) 表示查询参数的开始。使用 & 符号 (&) 将多个查询参数链接在一起。

要将模板变量或日期范围声明为 URL 查询参数，它必须遵循以下模式

模板变量查询参数的模式

# Spaces for clarity only
& tempVars %5B variableName %5D = variableValue

&
指示一系列多个查询参数中新查询参数的开始。

tempVars
通知 Chronograf 正在传递的查询参数是模板变量。所有模板变量查询参数都必需。

%5B, %5D
URL 编码的 [ 和 ] 分别括起模板变量名称。

variableName
模板变量的名称。

variableValue
模板变量的值。

当在仪表盘中修改模板变量时，相应的 URL 查询参数会自动更新。

模板变量查询参数示例

.../?&tempVars%5BmeasurementVar%5D=cpu

在 URL 中包含多个模板变量

要将多个模板变量链接为 URL 查询参数，请为每个模板变量包含完整的模式。

# Spaces for clarity only
.../?  &tempVars%5BmeasurementVar%5D=cpu  &tempVars%5BfieldKey%5D=usage_system

此页是否对您有帮助？

感谢您的反馈！

© 2025 InfluxData, Inc.

您在哪里运行 InfluxDB？

选择您的 InfluxDB Cloud 区域和集群 或您的 InfluxDB OSS URL，我们将为您自定义代码示例。识别您的 InfluxDB Cloud 集群。

  • InfluxDB Cloud
  • InfluxDB OSS 或 Enterprise
AWS

  • 美西（俄勒冈）

GCP
Azure
默认
自定义

有关更多信息，请参阅 InfluxDB Cloud 区域 或 InfluxDB OSS URL。

感谢您的反馈！

请告诉我们如何做得更好

谢谢！

不用了，谢谢

Flux 的未来

Flux 即将进入维护模式。您可以继续像现在一样使用它，而无需对代码进行任何更改。

阅读更多

InfluxDB 3 开源现已发布公开 Alpha 版本

InfluxDB 3 开源现在可用于 Alpha 测试，根据 MIT 或 Apache 2 许可获得许可。

我们正在发布两个产品作为 Alpha 版本的一部分。

InfluxDB 3 Core 是我们新的开源产品。它是用于时间序列和事件数据的最新数据引擎。InfluxDB 3 Enterprise 是一个商业版本，它建立在 Core 的基础上，增加了历史查询功能、读取副本、高可用性、可伸缩性和细粒度的安全性。

有关如何入门的更多信息，请查看