本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 变量语法
<a name="v9-dash-variable-syntax"></a>

****  
本文档主题专为支持 **Grafana 9.x 版本**的 Grafana 工作区而设计。  
有关支持 Grafana 版本 12.x 的 Grafana 工作空间，请参阅。[在 Grafana 版本 12 中工作](using-grafana-v12.md)  
对于支持 Grafana 10.x 版本的 Grafana 工作区，请参阅[使用 Grafana 版本 10](using-grafana-v10.md)。  
对于支持 Grafana 8.x 版本的 Grafana 工作区，请参阅[使用 Grafana 版本 8](using-grafana-v8.md)。

面板标题和指标查询可以使用两种不同的语法来引用变量。
+ `$varname`：此语法易于读取，但不能在词中间使用变量。

  **示例**：`apps.frontend.$server.requests.count`
+ `${var_name}`：如果要在表达式中间使用变量，请使用此语法。
+ `${var_name:<format>}`：此格式让您可以更好地控制 Grafana 如何解释值。有关更多信息，请参阅*高级变量格式选项*。
+ `[[varname]]`：请勿使用。此语法已过时，不再使用。这将在未来版本中删除。

在将查询发送到数据来源之前，会对查询进行*插值*，这意味着变量将替换为当前值。在插值过程中，变量值可能会被*转义*，以符合查询语言的语法和使用场合。例如，InfluxDB 或 Prometheus 查询中的正则表达式中使用的变量将被正则表达式转义。

**高级变量格式选项**

变量插值的格式取决于数据来源，但在某些情况下，可能需要更改默认格式。

例如，MySQL 数据来源的默认格式是以逗号分隔的形式联接多个值，并使用引号：`'server01','server02'`。在某些情况下，您可能希望使用逗号分隔的字符串，但不使用引号：`server01,server02`。您可以使用下面列出的高级变量格式选项来实现这一点。

**一般语法**

语法：`${var_name:option}`

如果指定了任何无效的格式选项，`glob`则为该 default/fallback 选项。

**CSV**

将具有多个值的变量格式化为逗号分隔的字符串。

```
servers = [ 'test1',  'test2' ]
String to interpolate:  '${servers:csv}'
Interpolation result:  'test1,test2'
```

**分布式 OpenTSDB**

以 OpenTSDB 自定义格式来格式化具有多个值的变量。

```
servers = [ 'test1',  'test2' ]
String to interpolate:  '${servers:distributed}'
Interpolation result:  'test1,servers=test2'
```

**Doublequote**

将单值和多值变量格式化为逗号分隔的字符串，在每个值中使用 `\"` 对 `"` 进行转义，并在每个值两侧加上 `"`。

```
servers = [ 'test1',  'test2' ]
String to interpolate:  '${servers:doublequote}'
Interpolation result:  '"test1","test2"'
```

**Glob - Graphite**

将具有多个值的变量格式化为 glob（用于 Graphite 查询）。

```
servers = [ 'test1',  'test2' ]
String to interpolate:  '${servers:glob}'
Interpolation result:  '{test1,test2}'
```

**JSON**

将具有多个值的变量格式化为逗号分隔的字符串。

```
servers = [ 'test1',  'test2' ]
String to interpolate:  '${servers:json}'
Interpolation result:  '["test1", "test2"]'
```

**Lucene - Elasticsearch**

将具有多个值的变量格式化为适用于 Elasticsearch 的 Lucene 格式。

```
servers = [ 'test1',  'test2' ]
String to interpolate:  '${servers:lucene}'
Interpolation result:  '("test1" OR "test2")'
```

**Percentencode**

格式化单值和多值变量，供 URL 参数使用。

```
servers = [ 'foo()bar BAZ',  'test2' ]
String to interpolate:  '${servers:percentencode}'
Interpolation result:  'foo%28%29bar%20BAZ%2Ctest2'
```

**Pipe**

将具有多个值的变量格式化为以竖线分隔的字符串。

```
servers = [ 'test1.',  'test2' ]
String to interpolate:  '${servers:pipe}'
Interpolation result:  'test1.|test2'
```

**Raw**

关闭特定于数据来源的格式化，如 SQL 查询中的单引号。

```
servers = [ 'test.1',  'test2' ]
String to interpolate:  '${var_name:raw}'
Interpolation result:  'test.1,test2'
```

**Regex (正则表达式)**

将具有多个值的变量格式化为正则表达式字符串。

```
servers = [ 'test1.',  'test2' ]
String to interpolate:  '${servers:regex}'
Interpolation result:  '(test1\.|test2)'
```

**Singlequote**

将单值和多值变量格式化为逗号分隔的字符串，在每个值中使用 `\'` 对 `'` 进行转义，并在每个值两侧加上 `'`。

```
servers = [ 'test1',  'test2' ]
String to interpolate:  '${servers:singlequote}'
Interpolation result:  "'test1','test2'"
```

**Sqlstring**

将单值和多值变量格式化为逗号分隔的字符串，在每个值中使用 `''` 对 `'` 进行转义，并在每个值两侧加上 `'`。

```
servers = [ "test'1",  "test2" ]
String to interpolate:  '${servers:sqlstring}'
Interpolation result:  "'test''1','test2'"
```

**文本**

将单值和多值变量格式化为其文本表示形式。对于单个变量，仅返回文本表示形式。对于多值变量，将返回与 `+` 组合的文本表示形式。

```
servers = [ "test1",  "test2" ]
String to interpolate:  '${servers:text}'
Interpolation result:  "test1 + test2"
```

**查询参数**

将单值和多值变量格式化为其查询参数表示形式。示例：`var-foo=value1&var-foo=value2`

```
servers = [ "test1",  "test2" ]
String to interpolate:  '${servers:queryparam}'
Interpolation result:  "var-servers=test1&var-servers=test2"
```