使用仪表板模板变量

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

• 使用模板变量
• 预定义的模板变量
• 创建自定义模板变量
• 模板变量类型
• 保留变量名称
• 高级模板变量使用

使用模板变量

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

• 在单元查询中使用模板变量
  • InfluxQL
  • Flux
• 在单元格标题中使用模板变量

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

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 语法对查询中的值进行引用：

• 对于数值， 不要加引号。
• 对于字符串值，请选择在变量定义中引用这些值（或不引用）。请参见下面的 字符串示例。

字符串示例

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

在变量定义中添加单引号

如果您使用单引号定义名为 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中，模板变量存储在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:

显示为：

预定义模板变量

Chronograf 包含由 Chronograf 用户界面中的元素控制的预定义模板变量。在您的单元查询中使用预定义模板变量。

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

InfluxQL Flux

• :dashboardTime:
• :upperDashboardTime:
• :interval:

仪表板时间

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

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

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

要使用日期选择器指定过去的时间范围，请使用 :dashboardTime: 作为开始时间，并将 :upperDashboardTime: 作为结束时间构建查询。

upperDashboardTime

模板变量 :upperDashboardTime: 是通过日期选择器指定的上限时间定义的。

在使用相对时间框架时，它将继承 now()，或在使用绝对时间框架时将继承上限时间。

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

间隔

模板变量 :interval: 是由 Chronograf 控制面板中的间隔下拉菜单定义的。

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

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

• v.timeRangeStart
• v.timeRangeStop
• v.windowPeriod

向后兼容的 Flux 模版变量

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

• dashboardTime
• upperDashboardTime
• autoInterval

v.timeRangeStart

《code》v.timeRangeStart《/code》模板变量由您在Chronograf仪表板中的“时间”下拉菜单控制。

如果使用相对时间，此变量表示在下拉菜单中指定的时间偏移（-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 由使用日期选择器指定的上限时间确定。

对于相对时间范围，此变量继承 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或Map类型，请以适当的格式上传或输入包含所需值的CSV，然后选择一个默认值。
6. 点击 创建。

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

模板变量类型

Chronograf 支持以下模板变量类型：

• 数据库
• 测量
• 字段键
• 标签键
• 标签值
• CSV
• 地图
• InfluxQL 元数据查询
• Flux 查询
• 文本

数据库

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

数据库元查询
数据库模板变量使用以下元查询来返回您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

单元查询中的示例字段键 var

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

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

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

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

CSV变量使用案例

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

映射

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

示例 CSV：

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

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元查询变量允许您提取高度自定义的潜在值数组，并提供高级功能，例如基于其他模板变量过滤值。

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

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:
• :小写:
• :zoomedUpper:
• :zoomedLower:
• :refreshRate:

高级模板变量使用

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

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

例如，假设您想列出与一个测量相关的所有字段键，但希望能够更改测量：

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

   

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

   SHOW FIELD KEYS ON telegraf FROM :measurementVar:
   

   

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
     )
   

生成的仪表板将如下工作：

在URL中定义模板变量

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

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

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

模板变量查询参数的模式

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

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

tempVars
告知Chronograf传递的查询参数是一个模板变量。所有模板变量查询参数都需要此项。

%5B, %5D
分别是 URL 编码的 [ 和 ]，它们包围模板变量名。

variableName
模板变量的名称。

variableValue
模板变量的值。

示例模板变量查询参数

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

在URL中包括多个模板变量

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

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