使用仪表板模板变量

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: 是通过日期选择器指定的上限时间定义的。

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

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

间隔

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

在单元查询中，它应该用于伴随聚合函数的 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

模板变量 v.timeRangeStart 由您在 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 查询
• 文本

数据库

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

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

'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 meta query 变量类型。以下元查询根据现有的 :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