本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 連線至 MySQL 資料來源
<a name="using-mysql-in-AMG"></a>

 新增 MySQL 資料來源，以查詢和視覺化 MySQL 相容資料庫中的資料。

**重要**  
Grafana 8.0 版會變更 MySQL、Postgres 和 Microsoft SQL Server 資料來源的資料影格基礎資料結構。因此，時間序列查詢結果會以寬格式傳回。如需詳細資訊，請參閱 Grafana 資料影格文件中的[廣角格式](https://grafana.com/developers/plugin-tools/introduction/data-frames#wide-format)。  
若要讓視覺化效果如之前一樣運作，您可能需要進行一些手動遷移。一個解決方案記錄在 Github 上的 [Postgres/MySQL/MSSQL：中斷 v8.0 中與時間序列查詢和資料欄排序相關的變更](https://github.com/grafana/grafana/issues/35534)。

## 新增資料來源
<a name="mysql-adding-the-data-source"></a>

1.  選擇頂端標頭中的 Grafana 圖示，開啟側邊選單。

1.  在**儀表板**連結下的側邊選單中，您應該會找到名為**資料來源**的連結。

1.  選擇頂端標頭中的 **\$1 新增資料來源**按鈕。

1.  從**類型**下拉式清單中選取 **MySQL**。

### 資料來源選項
<a name="mysql-data-source-options"></a>


|  名稱  |  描述  | 
| --- | --- | 
|  Name  |  資料來源名稱。這是您在面板和查詢中查看資料來源的方式。 | 
|  Default  |  預設資料來源表示將針對新面板預先選取。 | 
|  Host  |  MySQL 執行個體的 IP 地址/主機名稱和選用連接埠。 | 
|  Database  |  MySQL 資料庫的名稱。 | 
|  User  |  資料庫使用者的登入/使用者名稱。 | 
|  Password  |  資料庫使用者的密碼。 | 
|  Max open  |  預設資料庫的開啟連線數目上限 unlimited(Grafana v5.4\$1)。 | 
|  Max idle  |  預設閒置連線集區中的連線數目上限 2(Grafana v5.4\$1)。 | 
|  Max lifetime  |  可以重複使用連線的秒數上限，預設為 14400/4 小時。這應一律低於 MySQL 中設定的 [wait\$1timeout](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_wait_timeout) (Grafana v5.4\$1)。 | 

### 最短時間間隔
<a name="mysql-min-time-interval"></a>

 `$_interval` `$_interval_ms` 變數的下限。建議設定為寫入頻率，例如`1m`，如果您的資料每分鐘寫入一次。也可以在資料來源選項下的儀表板面板中覆寫/設定此選項。此值的格式**必須是**數字，後面接著有效的時間識別符；例如 `1m`(1 分鐘） 或 `30s`(30 秒）。支援下列時間識別符。


|  識別符  |  Description  | 
| --- | --- | 
|  y  |  年  | 
|  M  |  月  | 
|  w  |  週  | 
|  d  |  天  | 
|  h  |  小時  | 
|  m  |  分鐘  | 
|  s  |  秒  | 
|  ms  |  毫秒  | 

### 資料庫使用者許可
<a name="database-user-permissions-important"></a>

**重要**  
 您在新增資料來源時指定的資料庫使用者，應僅獲得您要查詢之指定資料庫和資料表的 SELECT 許可。Grafana 不會驗證查詢是否安全。查詢可能包含任何 SQL 陳述式。例如，`DROP TABLE user;`會執行 `USE otherdb;`和 等陳述式。為了防止這種情況，強烈建議您建立具有受限許可的特定 MySQL 使用者。

 下列程式碼範例顯示建立具有受限許可的特定 MySQL 使用者。

```
 CREATE USER 'grafanaReader' IDENTIFIED BY 'password';
 GRANT SELECT ON mydatabase.mytable TO 'grafanaReader';
```

 若要授予對更多資料庫和資料表的存取權，您可以視需要使用萬用字元 (`*`) 取代資料庫或資料表。

## 查詢編輯器
<a name="mysql-query-editor"></a>

 您可以在面板編輯模式中的指標索引標籤中找到 MySQL 查詢編輯器。您可以選擇面板標題，然後選擇編輯，以進入**編輯**模式。

 查詢編輯器具有**產生的 SQL** 連結，會在查詢執行後，在面板編輯模式中顯示。選擇它，它會展開並顯示已執行的原始插補 SQL 字串。

### 選取資料表、時間欄和指標欄 (FROM)
<a name="select-table-time-column-and-metric-column-from"></a>

 當您第一次進入編輯模式或新增查詢時，Grafana 會嘗試使用具有時間戳記欄和數值欄的第一個資料表預先填入查詢建置器。

 在 FROM 欄位中，Grafana 會建議已設定資料庫中的資料表。若要選取資料庫使用者可存取的另一個資料庫中的資料表或檢視，您可以手動輸入完整名稱 (database.table)，例如 `otherDb.metrics`。

 時間欄欄位是指保留時間值的資料欄名稱。選取指標資料欄欄位的值是選用的。如果選取值，則會使用指標欄欄位做為序列名稱。

 指標欄建議只會包含具有文字資料類型 （文字、小文字、中文字、長文字、varchar、char) 的資料欄。如果您想要使用具有不同資料類型的資料欄做為指標資料欄，您可以輸入具有轉換的資料欄名稱：`CAST(numericColumn as CHAR)`。您也可以在評估為文字資料類型的指標資料欄欄位中輸入任意 SQL 表達式，例如 `CONCAT(column1, " ", CAST(numericColumn as CHAR))`。

### 資料欄和彙總函數 (SELECT)
<a name="columns-and-aggregation-functions-select"></a>

 在 `SELECT`列中，您可以指定要使用的資料欄和函數。在資料欄欄位中，您可以撰寫任意表達式，而不是資料欄名稱，例如 `column1 * column2 / column3`。

 如果您使用彙總函數，則必須將結果集分組。`GROUP BY time`如果您新增彙總函數，編輯器會自動新增 。

 您可以選擇加號按鈕並從`Column`選單中選取，以新增更多值欄。圖形面板中的多個值資料欄將繪製為個別序列。

### 篩選資料 (WHERE)
<a name="mysql-filter-data-where"></a>

 若要新增篩選條件，請選擇`WHERE`條件右側的加號圖示。您可以透過選擇篩選條件並選取 來移除篩選條件`Remove`。目前所選時間範圍的篩選條件會自動新增至新查詢。

### 分組依據
<a name="mysql-group-by"></a>

 若要依時間或任何其他資料欄分組，請選擇 GROUP BY 資料列結尾的加號圖示。建議下拉式清單只會顯示目前所選資料表的文字資料欄，但您可以手動輸入任何資料欄。您可以透過選擇項目，然後選擇 來移除群組`Remove`。

 如果您新增任何分組，則所有選取的資料欄都必須套用彙總函數。當您新增分組時，查詢建置器會自動將彙總函數新增至所有資料欄，而不需要彙總函數。

#### 間隙填充
<a name="mysql-gap-filling"></a>

 當您依時間分組時，Grafana 可以填入缺少的值。時間函數接受兩個引數。第一個引數是您要分組的時間範圍，第二個引數是您希望 Grafana 填入缺少項目的值。

### 文字編輯器模式 （原始）
<a name="mysql-text-editor-mode-raw"></a>

 您可以選擇漢堡圖示並選取**切換編輯器模式，或選擇查詢下方的編輯 SQL，即可切換到原始查詢編輯器模式**。 ****

**注意**  
 如果您使用原始查詢編輯器，請確定您的查詢至少具有 ，`ORDER BY time`並在傳回的時間範圍上有一個篩選條件。

## 巨集
<a name="mysql-macros"></a>

 為了簡化語法並允許動態部分，例如日期範圍篩選條件，查詢可以包含巨集。


|  巨集範例  |  Description  | 
| --- | --- | 
|  \$1\$1\$1time(dateColumn)  |  將由表達式取代，以轉換為 UNIX 時間戳記，並將資料欄重新命名為 time\$1sec；例如 UNIX\$1TIMESTAMP(dateColumn) 作為 time\$1sec。 | 
|  \$1\$1\$1timeEpoch(dateColumn)  |  將由表達式取代，以轉換為 UNIX 時間戳記，並將資料欄重新命名為 time\$1sec；例如 UNIX\$1TIMESTAMP(dateColumn) 作為 time\$1sec。 | 
|  \$1\$1\$1timeFilter(dateColumn)  |  將由使用指定資料欄名稱的時間範圍篩選條件取代。例如，dateColumn BETWEEN FROM\$1UNIXTIME(1494410783) 和 FROM\$1UNIXTIME(1494410983)。 | 
|  \$1\$1\$1timeFrom()  |  將由目前作用中時間選擇的開始取代。例如 FROM\$1UNIXTIME(1494410783)。 | 
|  \$1\$1\$1timeTo()  |  將取代為目前作用中時間選擇的結尾。例如 FROM\$1UNIXTIME(1494410983)。 | 
|  \$1\$1\$1timeGroup(dateColumn,'5m')  |  將由 GROUP BY 子句中可用的表達式取代。例如，Cast(cast(UNIX\$1TIMESTAMP(dateColumn)/(300) 為已簽署），300 為已簽署），\$1  | 
|  \$1\$1\$1timeGroup(dateColumn,'5m', 0)  |  與上一列相同，但具有填充參數，因此 grafana 會新增該系列中的遺失點，並使用 0 做為值。 | 
|  \$1\$1\$1timeGroup(dateColumn,'5m', NULL)  |  與上述相同，但 NULL 將用作遺失點的值。 | 
|  \$1\$1\$1timeGroup(dateColumn,'5m', previous)  |  與上述相同，但如果尚未看到 NULL，則會使用該序列中的上一個值作為填充值 （僅適用於 Grafana 5.3\$1)。 | 
|  \$1\$1\$1timeGroupAlias(dateColumn,'5m')  |  將與 相同，\$1\$1\$1timeGroup但以新增的資料欄別名取代 （僅適用於 Grafana 5.3\$1)。 | 
| \$1\$1\$1unixEpochFilter(dateColumn) | 將使用指定資料欄名稱取代為時間範圍篩選條件，時間表示為 Unix 時間戳記。例如 dateColumn > 1494410783 AND dateColumn < 1494497183。 | 
| \$1\$1\$1unixEpochFrom() | 將由目前作用中時間選擇的開頭取代為 Unix 時間戳記。例如 1494410783。 | 
| \$1\$1\$1unixEpochTo() | 將被目前作用中時間選擇的結尾取代為 Unix 時間戳記。例如 1494497183。 | 
| \$1\$1\$1unixEpochNanoFilter(dateColumn) | 將使用指定的資料欄名稱取代為時間範圍篩選條件，時間表示為奈秒時間戳記。例如 dateColumn > 1494410783152415214 AND dateColumn < 1494497183142514872。 | 
| \$1\$1\$1unixEpochNanoFrom() | 將由目前作用中時間選擇的開頭取代為奈秒時間戳記。例如 1494410783152415214。 | 
| \$1\$1\$1unixEpochNanoTo() | 將被目前作用中時間選擇的結尾取代為奈秒時間戳記。例如 1494497183142514872。 | 
| \$1\$1\$1unixEpochGroup(dateColumn,"5m", [fillmode]) | 與 相同，\$1\$1\$1timeGroup但適用於儲存為 Unix 時間戳記的時間 （僅適用於 Grafana 5.3\$1)。 | 
| \$1\$1\$1unixEpochGroupAlias(dateColumn,"5m", [fillmode])` | 與上述相同，但也會新增資料欄別名 （僅適用於 Grafana 5.3\$1)。 | 

 查詢編輯器具有**產生的 SQL** 連結，會在查詢執行後，在面板編輯模式中顯示。選擇它，它會展開並顯示已執行的原始插補 SQL 字串。

## 資料表查詢
<a name="mysql-table-queries"></a>

 如果**格式化為**查詢選項設定為**資料表**，基本上您可以執行任何類型的 SQL 查詢。資料表面板會自動顯示查詢傳回的任何資料欄和資料列的結果。

 下列程式碼顯示範例查詢。

```
SELECT
  title as 'Title',
  user.login as 'Created By' ,
  dashboard.created as 'Created On'
 FROM dashboard
INNER JOIN user on user.id = dashboard.created_by
WHERE $__timeFilter(dashboard.created)
```

 您可以使用一般 `as` SQL 資料欄選取語法來控制資料表面板資料欄的名稱。

## 時間序列查詢
<a name="mysql-time-series-queries"></a>

 如果您**將 格式**設定為**時間序列**，例如用於圖形面板，查詢必須傳回名為 的資料欄`time`，該資料欄會傳回 SQL 日期時間或任何代表 Unix epoch 的數值資料類型。除了 `time`和 以外的任何資料欄`metric`都會視為值資料欄。您可以傳回名為 的資料欄`metric`，做為值資料欄的指標名稱。如果您傳回多個值資料欄和名為 的資料欄`metric`，則此資料欄會用作序列名稱的字首 （僅適用於 Grafana 5.3\$1)。

 時間序列查詢的結果集必須依時間排序。

 下列程式碼範例顯示 `metric`欄。

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

 下列程式碼範例顯示使用 \$1\$1\$1timeGroup 巨集中的填充參數，將 null 值改為零。

```
SELECT
  $__timeGroup(createdAt,'5m',0),
  sum(value_double) as value,
  measurement
FROM test_data
WHERE
  $__timeFilter(createdAt)
GROUP BY time, measurement
ORDER BY time
```

 下列程式碼範例顯示多個資料欄。

```
SELECT
  $__timeGroup(time_date_time,'5m'),
  min(value_double) as min_value,
  max(value_double) as max_value
FROM test_data
WHERE $__timeFilter(time_date_time)
GROUP BY time
ORDER BY time
```

根據時間範圍和面板寬度，不支援依時間的動態群組。

## 範本化
<a name="mysql-templating"></a>

 您可以在指標查詢中使用變數，而不是硬式編碼，例如伺服器、應用程式和感應器名稱。變數會顯示為儀表板頂端的下拉式清單選取方塊。您可以使用這些下拉式方塊來變更儀表板中顯示的資料。

 如需範本和範本變數的詳細資訊，請參閱 [範本](templates-and-variables.md#templates)。

### 查詢變數
<a name="mysql-query-variable"></a>

 如果您新增類型 的範本變數`Query`，您可以撰寫 MySQL 查詢，以傳回顯示為下拉式清單選取方塊的測量名稱、索引鍵名稱或索引鍵值等物件。

 例如，如果您在範本變數查詢**設定中指定這類查詢，您可以有一個變數，其中包含資料表中資料`hostname`欄的所有值。

```
SELECT hostname FROM my_host
```

 查詢可以傳回多個資料欄，Grafana 會自動從中建立清單。例如，下列查詢將傳回來自 `hostname`和 的值清單`hostname2`。

```
SELECT my_host.hostname, my_other_host.hostname2 FROM my_host JOIN my_other_host ON my_host.city = my_other_host.city
```

 若要在查詢`$__timeFilter(column)`中使用時間範圍相依巨集，例如 ，範本變數的重新整理模式必須設定為*時間範圍變更*。

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

 另一個選項是可建立索引鍵/值變數的查詢。查詢應傳回兩個名為 `__text`和 的資料欄`__value`。`__text` 資料欄值應該是唯一的 （如果不是唯一的，則會使用第一個值）。下拉式清單中的選項會有文字和值，因此您可以將易記的名稱做為文字，並將 ID 做為值。

下列程式碼範例顯示使用 `hostname`做為文字和 `id` 做為值的查詢。

```
SELECT hostname AS __text, id AS __value FROM my_host
```

 您也可以建立巢狀變數。例如，如果您有另一個名為 的變數`region`。然後，您可以讓主機變數只顯示目前所選區域中具有此類查詢的主機 （如果 `region` 是多值變數，則使用`IN`比較運算子，而不是`=`比對多個值）。

```
SELECT hostname FROM my_host  WHERE region IN($region)
```

#### 使用 `__searchFilter` 在查詢變數中篩選結果
<a name="using-__searchfilter-to-filter-results-in-query-variable"></a>

 `__searchFilter` 在查詢欄位中使用 會根據下拉式清單選取方塊中的使用者類型來篩選查詢結果。當使用者未輸入任何內容時， 的預設值`__searchFilter`為 `%`。

**注意**  
 請務必使用引號括住`__searchFilter`表達式，因為 Grafana 不會為您執行此操作。

 下列範例示範如何使用 `__searchFilter`做為查詢欄位的一部分，以在下拉式清單選取方塊中的使用者類型`hostname`時啟用搜尋。

```
SELECT hostname FROM my_host  WHERE hostname LIKE '$__searchFilter'
```

### 在查詢中使用變數
<a name="using-variables-in-queries-2"></a>

 從 Grafana 4.3.0 到 4.6.0，範本變數一律會自動引號，因此如果是字串值，則不會在 子句所在的引號中包裝它們。

 從 Grafana 4.7.0 開始，只有在範本變數為 時，才會引用範本變數值。 `multi-value`

 如果變數是多值變數，請使用`IN`比較運算子`=`，而不是比對多個值。

 有兩種語法：

 `$<varname>` 範本變數名為 的範例`hostname`：

```
SELECT
  UNIX_TIMESTAMP(atimestamp) as time,
  aint as value,
  avarchar as metric
FROM my_table
WHERE $__timeFilter(atimestamp) and hostname in($hostname)
ORDER BY atimestamp ASC
```

 `[[varname]]` 範本變數名為 的範例`hostname`：

```
SELECT
  UNIX_TIMESTAMP(atimestamp) as time,
  aint as value,
  avarchar as metric
FROM my_table
WHERE $__timeFilter(atimestamp) and hostname in([[hostname]])
ORDER BY atimestamp ASC
```

#### 關閉多值變數的引號
<a name="disabling-quoting-for-multi-value-variables"></a>

 Grafana 會自動為多值變數建立以逗號分隔的引號字串。例如：如果選取 `server02` `server01`和 ，則會格式化為：`'server01', 'server02'`。若要關閉引號，請使用變數的 csv 格式選項。

 `${servers:csv}` 

 如需變數格式化選項的詳細資訊，請參閱 [進階變數格式選項](templates-and-variables.md#advanced-variable-format-options)。

## 註釋
<a name="mysql-annotations"></a>

 您可以使用註釋在圖形上方覆蓋豐富的事件資訊。您可以透過儀表板功能表/註釋檢視新增註釋查詢。如需詳細資訊，請參閱。

 下列範例程式碼顯示使用具有 epoch 值的時間欄的查詢。

```
SELECT
  epoch_time as time,
  metric1 as text,
  CONCAT(tag1, ',', tag2) as tags
FROM
  public.test_data
WHERE
  $__unixEpochFilter(epoch_time)
```

下列範例程式碼顯示使用具有 epoch 值的時間和結束時間資料欄進行區域查詢。

**注意**  
 僅適用於 Grafana v6.6\$1。

```
SELECT
  epoch_time as time,
  epoch_timeend as timeend,
  metric1 as text,
  CONCAT(tag1, ',', tag2) as tags
FROM
  public.test_data
WHERE
  $__unixEpochFilter(epoch_time)
```

 下列範例程式碼使用原生 SQL 日期/時間資料類型的時間資料欄顯示查詢。

```
SELECT
  native_date_time as time,
  metric1 as text,
  CONCAT(tag1, ',', tag2) as tags
FROM
  public.test_data
WHERE
  $__timeFilter(native_date_time)
```


|  名稱  |  描述  | 
| --- | --- | 
|  time  |  日期/時間欄位的名稱。可以是具有原生 SQL 日期/時間資料類型或 epoch 值的資料欄。 | 
|  timeend  |  結束日期/時間欄位的選用名稱。可以是具有原生 SQL 日期/時間資料類型或 epoch 值的資料欄。 | 
|  text  |  事件描述欄位。 | 
|  tags  |  用於事件標籤的選用欄位名稱，做為逗號分隔字串。 | 

## 提醒
<a name="mysql-alerting"></a>

 時間序列查詢應在提醒條件下運作。警示規則條件中尚不支援資料表格式的查詢。