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

# 连接到 Oracle 数据库数据来源
<a name="oracle-datasource-AMG"></a>

**注意**  
此数据来源仅适用于 Grafana Enterprise。有关更多信息，请参阅 [管理对 Enterprise 插件的访问](upgrade-to-enterprise-plugins.md)。  
此外，在支持版本 9 或更高版本的工作区中，此数据来源可能需要您安装相应的插件。有关更多信息，请参阅 [使用插件扩展您的工作区](grafana-plugins.md)。

## 添加数据来源
<a name="datasource-configuration"></a>

 在 Grafana 的左侧面板上选择**数据来源**。

 选择“添加数据来源”：

 输入 **oracle** 以查找数据来源。

 输入 Oracle 服务器详细信息。

 输入主机名（或 IP 地址）以及端口号，并输入用于连接的用户名和密码。

 切换 tnsnames 选项后，可以使用 tnsnames.ora 配置文件中找到的任何有效条目以及基本身份验证。

 与上一示例类似，但使用 Kerberos 进行身份验证。有关如何将操作系统或 Docker 容器配置为使用 Kerberos 的详细信息，请参阅 Kerberos 特定的设置指南。

 （可选）更改用于连接到 Oracle 服务器并由时区感知型宏所使用的时区。默认设置为 UTC。

 保存并测试数据来源，您应该会看到一条绿色消息，上面写着“数据库连接正常” 

## 用法
<a name="usage-4"></a>

### 宏
<a name="macros-1"></a>

 为了简化语法并允许动态部分（如日期范围筛选器），查询可包含宏。列名称必须位于双引号（`"`）内。


|  宏示例  |  说明  | 
| --- | --- | 
|  \*$\_\_time(dateColumn)\* \| 将替换为表达式，以将列重命名为 `time`。例如，`dateColumn as time` \*$\_\_timeEpoch(dateColumn)\*  |  将替换为一个表达式，以将列重命名为 time，并将该值转换为 Unix 时间戳（以毫秒为单位）。 | 
|  \*$\_\_timeFilter(dateColumn)\* \| 将替换为使用指定列名的时间范围筛选条件。例如，`DateColumn TO\_DATE ('19700101'，'yyyymmdd') \+ (/1000) \* 1500376552001 和 TO\_DATE ('19700101'，'yyyymmdd') \+ (1/2460/60/1000) \* 1500376552002` \*$\_\_TimeFrom () \* 1/24 60/60  |  将替换为当前活动时间选择的开始时间（已转换为 DATE 数据类型）。例如 TO\_DATE('19700101','yyyymmdd') \+ (1/24/60/60/1000) \* 1500376552001。 | 
|  \*$\_\_timeTo()\* \| 将替换为当前活动时间选择的结束时间（已转换为 `DATE` 数据类型）。\*$\_\_timeGroup(dateColumn,"5m")\*  |  将替换为 GROUP BY 子句中可用的表达式。 | 
|  \*$\_\_timeGroup(dateColumn,"5m"[, fillvalue])\*  |  将替换为 GROUP BY 子句中可用的表达式。如果 fillValue 为 NULL 或浮点值，则会自动用该值填充时间范围内的空序列。例如，timeGroupcreatedAt, ′1m′, 0.\*\_\_timeGroup(dateColumn,"5m", 0)\*。 | 
|  \*timeGroup(dateColumn, ‘5m’, NULL) \* \|SameasabovebutNULLwillbeusedasvalueformissingpoints。\*\_\_timeGroup(dateColumn,"5m", previous)\*  |  与上面相同，但如果未看到任何值却使用 NULL，则该序列中的前一个值将用作填充值。 | 
|  \*$\_\_unix EpochFilter (dateColumn) \* \| 将替换为使用指定列名的时间范围过滤器，时间以 unix 时间戳（以毫秒为单位）表示。例如，`dateColumn >= 1500376552001 和 dateColumn <= 1500376552002` \*$\_\_unix () \* EpochFrom  |  将替换为当前活动时间选择的开始时间，作为 Unix 时间戳。例如 1500376552001。 | 
|  \*$\_\_unix EpochTo () \*  |  将替换为当前活动时间选择的结束时间，作为 Unix 时间戳。例如 1500376552002。 | 

 该插件还支持使用大括号 `{}`。当需要在参数内进行查询时，请使用此表示法。

**注意**  
每个查询使用一种表示法类型。如果查询需要大括号，则查询中的所有宏都必须使用大括号。

```
$__timeGroup{"dateColumn",'5m'}
$__timeGroup{SYS_DATE_UTC("SDATE"),'5m'}
$__timeGroup{FROM_TZ(CAST("SDATE" as timestamp), 'UTC'), '1h'}
```

 在面板编辑模式下，查询编辑器有一个**生成式 SQL** 链接，并在查询运行后显示。选择链接之后，将会展开并显示运行的原始插值 SQL 字符串。

### 表查询
<a name="table-queries"></a>

 如果**格式化为**查询选项设置为**表**，则基本上可以执行任何类型的 SQL 查询。表面板将自动显示查询返回的任何列和行的结果。您可以使用常规 `as` SQL 列选择语法来控制表面板列的名称。

### 时间序列查询
<a name="time-series-queries"></a>

 如果将**格式化为**设置为**时间序列**，例如在图形面板中使用，查询必须返回名为 `time` 的列，该列返回 SQL 日期时间或任何表示 Unix 纪元（秒）的数字数据类型。Grafana 将没有明确时区的 DATE 和 TIMESTAMP 列解释为 UTC。除 `time` 和 `metric` 之外的任何列都被视为值列。您可以返回一个名为 `metric` 的列，该列用作值列的指标名称。

 以下代码示例显示了多个 `metric` 列。

```
SELECT
  $__timeGroup("time_date_time", '5m') AS time,
  MIN("value_double"),
  'MIN' as metric
FROM test_data
WHERE $__timeFilter("time_date_time")
GROUP BY $__timeGroup("time_date_time", '5m')
ORDER BY time
```

### 更多查询：使用 oracle-fake-data-gen
<a name="more-queries---using-oracle-fake-data-gen"></a>

```
SELECT
  $__timeGroup("createdAt", '5m') AS time,
  MIN("value"),
  'MIN' as metric
FROM "grafana_metric"
WHERE $__timeFilter("createdAt")
GROUP BY $__timeGroup("createdAt", '5m')
ORDER BY time
```

 以下代码示例显示了“伪造数据”时间序列。

```
SELECT
  "createdAt",
  "value"
FROM "grafana_metric"
WHERE $__timeFilter("createdAt")
ORDER BY "createdAt" ASC
```

```
SELECT
  "createdAt" as time,
  "value" as value
FROM "grafana_metric"
WHERE $__timeFilter("createdAt")
ORDER BY time ASC
```

 以下示例显示了一个有用的表结果。

```
select tc.table_name Table_name
,tc.column_id Column_id
,lower(tc.column_name) Column_name
,lower(tc.data_type) Data_type
,nvl(tc.data_precision,tc.data_length) Length
,lower(tc.data_scale) Data_scale
,tc.nullable nullable
FROM all_tab_columns tc
,all_tables t
WHERE tc.table_name = t.table_name
```

### 模板化
<a name="templating-3"></a>

 您可以在指标查询中使用变量来代替服务器、应用程序和传感器名称等硬编码的内容。变量显示为控制面板顶部的下拉选择框。通过这些下拉框可以轻松更改控制面板中显示的数据。

#### 查询变量
<a name="query-variable-1"></a>

 如果添加 `Query` 类型的模板变量，则可以编写一个 Oracle 查询，该查询可以返回测量名称、键名或键值等显示为下拉选择框的内容。

 例如，如果在模板变量 *Query* 设置中指定了这样的查询，则会有一个变量，其中包含表中 `hostname` 列的所有值。

```
SELECT "hostname" FROM host
```

 查询可以返回多列，Grafana 会自动根据这些列创建一个列表。例如，以下查询将返回一个列表，其中包含来自 `hostname` 和 `hostname2` 的值。

```
SELECT "host.hostname", "other_host.hostname2" FROM host JOIN other_host ON host.city = other_host.city
```

 要在查询中使用依赖于时间范围的宏（如 `$__timeFilter("time_column")`），需要将模板变量的刷新模式设置为*时间范围更改时*。

```
SELECT "event_name" FROM event_log WHERE $__timeFilter("time_column")
```

 另一种选择是可以创建 key/value 变量的查询。该查询应返回名为 `__text` 和 `__value` 的两列。`__text` 列值应该是唯一的（如果它不是唯一的，则使用第一个值）。下拉列表中的选项包含文本和值，允许将友好名称作为文本，将 id 作为值。以下示例代码显示了一个以 `hostname` 作为文本，以 `id` 作为值的查询。

```
SELECT "hostname" AS __text, "id" AS __value FROM host
```

 您还可以创建嵌套变量。例如，您还有一个名为 `region` 的变量。然后，您可以让主机变量仅显示来自当前所选区域的主机，并使用以下查询（如果 `region` 是多值变量，则使用 `IN` 比较运算符而不是 `=` 与多个值匹配）。

```
SELECT "hostname" FROM host WHERE region IN('$region')
```

#### 在查询中使用变量
<a name="using-variables-in-queries-1"></a>

 仅当模板变量是 `multi-value` 时，才会引用模板变量值。

 如果该变量是多值变量，则使用 `IN` 比较运算符而不是 `=` 与多个值匹配。

 共有两种语法：

 `$<varname>` 名为 `hostname` 的模板变量的示例：

```
SELECT
  "atimestamp" as time,
  "aint" as value
FROM table
WHERE $__timeFilter("atimestamp") AND "hostname" IN('$hostname')
ORDER BY "atimestamp" ASC
```

 `[[varname]]` 名为 `hostname` 的模板变量的示例：

```
SELECT
  "atimestamp" as time,
  "aint" as value
FROM table
WHERE $__timeFilter("atimestamp") AND "hostname" IN('[[hostname]]')
ORDER BY atimestamp ASC
```