文档文档

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 或映射查询，请遵循标准的 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 等），并假定时间相对于“现在”。如果使用日期选择器定义的绝对时间，: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 等），并假定时间相对于“现在”。如果使用日期选择器定义的绝对时间，v.timeRangeStart 将填充为开始时间。

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

要使用日期选择器指定过去的时间范围而不使用“现在”，请使用 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 上传驱动的自定义模板变量，这些变量会返回一个可能值的数组。

创建模板变量

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

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

模板变量类型

Chronograf 支持以下模板变量类型

数据库

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

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

SHOW DATABASES

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

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

数据库变量使用场景

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

测量

更改目标度量。

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

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 模板变量非常有用。它们允许您使用自定义变量值。

映射

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

CSV 示例

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

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

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

单元格查询中的示例映射变量

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

映射变量使用场景

当您需要将简单名称或键映射或别名为更长或更复杂的值时，映射模板变量非常有用。例如，您可能希望创建一个 :customer: 变量，该变量用长数字客户 ID (11394850823894034209) 填充您的单元格查询。使用映射变量，您可以为复杂值设置别名，以便您的客户列表看起来像这样

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。

感谢您的反馈！

让我们知道我们可以做得更好

谢谢！

不用了，谢谢

InfluxDB 3.8 新特性

InfluxDB 3.8 和 InfluxDB 3 Explorer 1.6 的主要增强功能。

查看博客文章

InfluxDB 3.8 现已适用于 Core 和 Enterprise 版本，同时发布了 InfluxDB 3 Explorer UI 的 1.6 版本。本次发布着重于操作成熟度，以及如何更轻松地部署、管理和可靠地运行 InfluxDB。

更多信息，请查看

InfluxDB Docker 的 latest 标签将指向 InfluxDB 3 Core

在 **2026 年 2 月 3 日**，InfluxDB Docker 镜像的 latest 标签将指向 InfluxDB 3 Core。为避免意外升级，请在您的 Docker 部署中使用特定的版本标签。

如果使用 Docker 来安装和运行 InfluxDB，latest 标签将指向 InfluxDB 3 Core。为避免意外升级，请在您的 Docker 部署中使用特定的版本标签。例如，如果使用 Docker 运行 InfluxDB v2，请将 latest 版本标签替换为 Docker pull 命令中的特定版本标签 — 例如

docker pull influxdb:2