文档文档

Chronograf

使用仪表板模板变量

Chronograf 仪表板模板变量允许您在不编辑查询的情况下更新单元格查询，从而轻松地与仪表板单元格进行交互并探索数据。

使用模板变量

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

Use template variables

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

InfluxQL 和 Flux 都支持模板变量。

InfluxQL

在 InfluxQL 查询中，请使用冒号 (:) 将模板变量名称括起来，如下所示

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

对于“Field Keys”（字段键）和“Tag Values”（标签值）等预定义元查询，请不要在查询中添加引号（单引号或双引号）。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
在查询中添加单引号

如果您定义的自定义 CSV 变量 host 不带引号

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 仪表板中的“time”（时间）下拉菜单控制。

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 仪表板中的“time”（时间）下拉菜单控制。

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. 点击仪表板顶部的 Template Variables（模板变量），然后点击 + Add Variable（添加变量）。
  2. 从 Data Source（数据源）下拉菜单中选择一个数据源。
  3. 为变量提供一个名称。
  4. 选择变量类型。该类型定义了检索可能值数组的方法。
  5. 查看潜在值列表并选择默认值。如果使用 CSV 或映射类型，请以上传或输入适当格式的 CSV 值，然后选择一个默认值。
  6. 点击创建。

创建后，该模板变量即可在任何单元格的查询或标题中使用，并且该变量的下拉菜单将出现在仪表板顶部。

模板变量类型

Chronograf 支持以下模板变量类型

数据库

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

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

SHOW DATABASES

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

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

数据库变量使用场景

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

测量

更改目标测量指标 (Measurement)。

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

SHOW MEASUREMENTS ON database_name

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

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

测量指标变量使用场景

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

字段键

更改目标字段键 (Field Key)。

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

SHOW FIELD KEYS ON database_name FROM measurement_name

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

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

字段键变量使用场景

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

标签键

更改目标标签键 (Tag Key)。

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

SHOW TAG KEYS ON database_name FROM measurement_name

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

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

标签键变量使用场景

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

标签值

更改目标标签值 (Tag Value)。

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

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”是保留的），该变量使用测量指标 (Measurements) 变量类型从 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

此页面是否有帮助？

感谢您的反馈！

© 2026 InfluxData, Inc.

您在哪里运行 InfluxDB？

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

  • InfluxDB Cloud
  • InfluxDB OSS 或 Enterprise
AWS

  • 美国西部（俄勒冈州）

GCP
Azure
默认
自定义

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

感谢您的反馈！

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

谢谢！

不用了，谢谢

InfluxDB OSS 2.9.0：API 令牌默认进行哈希处理

InfluxDB OSS 2.9.0 增强了令牌安全性 —— 令牌在磁盘上默认进行哈希处理。现有令牌在首次启动时会被哈希，之后无法恢复。请在升级前保存您仍然需要的所有明文令牌。

查看 InfluxDB OSS 2.9.0 发行说明

哈希令牌的认证方式与未哈希令牌完全相同 —— 客户端和集成功能可继续正常工作。

2.9.0 中的其他新特性

  • 可配置的备份压缩
  • 恢复对包含哈希令牌的备份的支持
  • 更严格的边缘数据复制（Edge Data Replication）队列验证
  • Flux 升级
  • 压缩可靠性改进

Explorer 1.9 的主要增强功能

Explorer 1.9 现已发布，支持 InfluxQL、AI 辅助的 Flux 转 SQL 转换器（测试版）以及新的实时示例数据模拟器。

查看 Explorer 1.9 发行说明

Explorer 1.9 包含多项新功能和改进，使查询、可视化和管理数据变得更加轻松。

亮点

  • Flux 转 SQL 转换器（测试版）：通过 AI 辅助转换器将 Flux 查询转换为 SQL。
  • InfluxQL 支持：在数据浏览器（Data Explorer）和仪表板中使用 InfluxQL 查询数据，并保存和加载 InfluxQL 查询。
  • InfluxQL 可视化：根据 InfluxQL 结果渲染折线图和柱状图，并支持按标签进行序列分组。
  • 查询错误历史记录：在查询工具中查看查询错误历史记录。
  • 实时示例数据模拟器：使用新的鸟类数据和信号发生器模拟器生成连续的实时示例数据。

更多详细信息，请参阅 Explorer 1.9 发行说明

InfluxDB 3.10 现已发布

InfluxDB 3 Core 3.10 增加了自动目录格式升级、可配置的查询并发限制以及处理引擎改进。

InfluxDB 3 Core 3.10 的关键更新

  • 目录格式升级：在 3.10 首次启动时，磁盘目录会自动从 v2 格式升级到 v3 格式。迁移是单向的——升级前请务必备份您的目录。
  • --max-concurrent-queries：限制并发查询（可在运行时调整）。
  • GET /ready 端点，用于就绪探针。
  • 处理引擎：跨数据库查询和触发器锁定标志。

更多信息，请参阅 InfluxDB 3 Core 发行说明。

InfluxDB 3.10 现已发布

InfluxDB 3 Enterprise 3.10 增加了自动备份与恢复、行级删除和用户管理功能，并改进了自动目录格式升级和性能预览。

InfluxDB 3 Enterprise 3.10 的关键更新

  • 目录格式升级：在 3.10 首次启动时，磁盘目录会自动从 v2 格式升级到 v3 格式。迁移是单向的——升级前请务必备份您的目录。
  • 自动备份与恢复（测试版）
  • 行级删除
  • 用户管理（认证和 RBAC）— 预览版
  • 性能预览改进

备份与恢复、行级删除以及性能预览需要升级到企业级存储引擎（选择性加入测试版）。测试版和预览版功能可能会发生重大变更，不建议用于生产环境。

更多信息，请参阅 InfluxDB 3 Enterprise 发行说明

Telegraf Enterprise 现已全面上市（General Availability）

Telegraf Enterprise 现已全面上市，同时发布的还有 Telegraf Controller v1.0。

Telegraf Enterprise 将 Telegraf Controller（一个用于 Telegraf 的集中式管理控制台）与 InfluxData 的官方支持相结合。通过单一系统管理配置、监控集群健康状况并操作数以万计的 Telegraf 代理。

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

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

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

docker pull influxdb:2