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

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

 您可以使用 PostgreSQL 資料來源來查詢和視覺化來自 Amazon Aurora PostgreSQL 資料庫的資料。

**重要**  
*Grafana 第 8 版*會變更 Postgres、MySQL 和 Microsoft SQL Server 資料來源的資料影格基礎資料結構。因此，時間序列查詢結果會以寬格式傳回。如需詳細資訊，請參閱 Grafana 資料影格文件中的[寬格式](https://grafana.com/developers/plugin-tools/introduction/data-frames#wide-format)。若要讓視覺化效果如第 8 版之前一樣運作，您可能需要執行一些手動遷移。一個解決方案記錄在 Github 上的 [Postgres/MySQL/MSSQL：中斷 v8.0 中與時間序列查詢和資料欄排序相關的變更](https://github.com/grafana/grafana/issues/35534)。  
在 *Grafana 第 9 版*中，PostgreSQL 資料來源會設定根憑證，以與先前版本不同的方式連線至資料庫。如果您將工作區從第 8 版更新至第 9 版，您可能需要變更連線方式。如需詳細資訊，請參閱[對更新工作區的問題進行故障診斷](AMG-workspace-version-update-troubleshoot.md)。

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

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

1.  在側邊選單的**組態**圖示下，您應該會找到**資料來源**連結。

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

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

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


|  名稱  |  描述  | 
| --- | --- | 
|  Name  |  資料來源名稱。這是您在面板和查詢中查看資料來源的方式。 | 
|  Default  |  預設資料來源表示新面板會預先選取。 | 
|  Host  |  PostgreSQL 執行個體的 IP 地址/主機名稱和選用連接埠。請勿包含資料庫名稱。連線至 Postgres 的連線字串將不正確，且會導致錯誤。 | 
|  Database  |  PostgreSQL 資料庫的名稱。 | 
|  User  |  資料庫使用者的登入/使用者名稱。 | 
|  Password  |  資料庫使用者的密碼  | 
|  SSL Mode  |  此選項會決定安全 SSL TCP/IP 連線是否或優先與伺服器交涉。 | 
|  Max open  |  預設 unlimited(Grafana v5.4\+) 資料庫的開啟連線數目上限。 | 
|  Max idle  |  預設閒置連線集區中的連線數目上限 2(Grafana v5.4\+)。 | 
|  Max lifetime  |  可以重複使用連線的秒數上限，預設 14400/4 小時 (Grafana v5.4\+)。 | 
|  Version  |  此選項會決定查詢建置器中可用的函數 （僅適用於 Grafana 5.3\+)。 | 
|  TimescaleDB  |  TimescaleDB 是建置為 PostgreSQL 延伸模組的時間序列資料庫。如果啟用，Grafana 將在$\_\_timeGroup巨集time\_bucket中使用 ，並在查詢建置器中顯示 TimescaleDB 特定彙總函數 （僅適用於 Grafana 5.3\+)。 | 

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

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


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

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

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

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

```
 CREATE USER grafanareader WITH PASSWORD 'password';
 GRANT USAGE ON SCHEMA schema TO grafanareader;
 GRANT SELECT ON schema.table TO grafanareader;
```

 確定使用者未從公有角色取得任何不需要的許可。

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

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

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

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

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

 在 FROM 欄位中，Grafana 會建議資料庫使用者 `search_path` 中的資料表。若要選取不在 中的資料表或檢視，`search_path`您可以手動輸入完整名稱 (schema.table)，例如 `public.metrics`。

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

 指標欄建議只會包含具有文字資料類型 (char、varchar、text) 的資料欄。若要使用具有不同資料類型的資料欄做為指標資料欄，您可以輸入具有轉換的資料欄名稱：`ip::text`。您也可以在評估為文字資料類型的指標資料欄欄位中輸入任意 SQL 表達式，例如 `hostname || ' ' || container_name`。

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

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

 查詢編輯器中可用的函數取決於您在設定資料來源時選取的 PostgreSQL 版本。如果您使用彙總函數，則必須將結果集分組。如果您新增彙總函數，編輯器會自動新增 `GROUP BY time`。

編輯器會嘗試簡化和統一查詢的這個部分。

您可以選擇加號按鈕，然後從功能表中選取資料欄，以新增其他值資料**欄**。在圖形面板中，多個值資料欄將繪製為單獨的序列。

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

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

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

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

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

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

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

### 文字編輯器模式 (RAW)
<a name="postgresql-text-editor-mode-raw"></a>

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

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

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

 巨集可在查詢中使用，以簡化語法並允許動態組件。


|  巨集範例  |  Description  | 
| --- | --- | 
|  $\_\_time(dateColumn)  |  將由表達式取代，以轉換為 UNIX 時間戳記，並將資料欄重新命名為 time\_sec。例如，UNIX\_TIMESTAMP(dateColumn) 作為 time\_sec。 | 
|  $\_\_timeEpoch(dateColumn)  |  將由表達式取代，以轉換為 UNIX 時間戳記，並將資料欄重新命名為 time\_sec。例如，UNIX\_TIMESTAMP(dateColumn) 作為 time\_sec。 | 
|  $\_\_timeFilter(dateColumn)  |  將由使用指定資料欄名稱的時間範圍篩選條件取代。例如，dateColumn BETWEEN FROM\_UNIXTIME(1494410783) 和 FROM\_UNIXTIME(1494410983)。 | 
|  $\_\_timeFrom()  |  將由目前作用中時間選擇的開始取代。例如 FROM\_UNIXTIME(1494410783)。 | 
|  $\_\_timeTo()  |  將取代為目前作用中時間選擇的結尾。例如 FROM\_UNIXTIME(1494410983)。 | 
|  $\_\_timeGroup(dateColumn,'5m')  |  將由 GROUP BY 子句中可用的表達式取代。例如，Cast(cast(UNIX\_TIMESTAMP(dateColumn)/(300) 為已簽署），300 為已簽署），\*  | 
|  $\_\_timeGroup(dateColumn,'5m', 0)  |  與慣用的資料列相同，但使用填充參數，因此 grafana 會新增該系列中的遺失點，並使用 0 做為值。 | 
|  $\_\_timeGroup(dateColumn,'5m', NULL)  |  與上述相同，但 NULL 將用作遺失點的值。 | 
|  $\_\_timeGroup(dateColumn,'5m', previous)  |  與上述相同，但如果尚未看到 NULL，則會使用該序列中的上一個值作為填充值 （僅適用於 Grafana 5.3\+)。 | 
|  $\_\_timeGroupAlias(dateColumn,'5m')  |  將取代為與 $\_\_timeGroup 相同，但使用新增的資料欄別名  | 
|  $\_\_unixEpochFilter(dateColumn) |  將使用指定的資料欄名稱取代為時間範圍篩選條件，時間表示為 Unix 時間戳記。例如，\*dateColumn > 1494410783 AND dateColumn < 1494497183\* | 
| $\_\_unixEpochFrom()`  | \| 將由目前作用中時間選擇的開頭取代為 Unix 時間戳記。例如，\*1494410783\* | 
| $\_\_unixEpochTo() | 將被目前作用中時間選擇的結尾取代為 Unix 時間戳記。例如，\*1494497183\* | 
| $\_\_unixEpochNanoFilter(dateColumn) | 將使用指定的資料欄名稱取代時間範圍篩選條件，並以 nanosecond 時間戳記表示時間。例如，\*dateColumn > 1494410783152415214 AND dateColumn < 1494497183142514872\* | 
| $\_\_unixEpochNanoFrom() | 將以目前作用中時間選擇的開頭取代為奈秒時間戳記。例如，\*1494410783152415214\* | 
| $\_\_unixEpochNanoTo() | 將被目前作用中時間選擇的結尾取代為奈秒時間戳記。例如，\*1494497183142514872\* | 
| $\_\_unixEpochGroup(dateColumn,"5m", [fillmode]) | 與 $\_\_timeGroup 相同，但時間儲存為 Unix 時間戳記。 | 

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

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

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

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

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

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

 下列範例程式碼顯示 `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
```

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

```
SELECT
  $__timeGroup("createdAt",'5m',0),
  sum(value) 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="postgresql-templating"></a>

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

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

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

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

 例如，如果您在範本變數查詢**設定中指定這類查詢，您可以有一個變數，其中包含資料表中資料`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(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 host
```

 您也可以建立巢狀變數。使用名為 的變數`region`，您可以讓主機變數僅顯示目前所選區域的主機。下列程式碼範例顯示像這樣的查詢 （如果 `region` 是多值變數，請使用`IN`比較運算子`=`，而不是比對多個值）。

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

#### 使用 `__searchFilter` 在查詢變數中篩選結果
<a name="postgresql-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="postgresql-using-variables-in-queries"></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
```

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

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

 `${servers:csv}` 

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

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

 使用註釋在圖形上方疊加豐富的事件資訊。您可以透過儀表板功能表/註釋檢視新增註釋查詢。如需詳細資訊，請參閱[註釋](dashboard-annotations.md)。

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

```
SELECT
  epoch_time as time,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM
  public.test_data
WHERE
  $__unixEpochFilter(epoch_time)
```

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

**注意**  
 這僅適用於 Grafana v6.6\+。

```
SELECT
  epoch_time as time,
  epoch_time_end as timeend,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM
  public.test_data
WHERE
  $__unixEpochFilter(epoch_time)
```

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

```
SELECT
  native_date_time as time,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM
  public.test_data
WHERE
  $__timeFilter(native_date_time)
```


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

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

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