翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # PostgreSQL データソースに接続する PostgreSQL データソースを使用して、Amazon Aurora PostgreSQL データベースからのデータをクエリおよび視覚化できます。 **重要** *[Grafana バージョン 8] *は、Postgres、MySQL 、および Microsoft SQL Server データソースのデータフレームの基盤となるデータ構造を変更します。その結果、時系列のクエリ結果が幅広い形式で返されます。詳細については、Grafana データフレームドキュメントの「[ワイドフォーマット](https://grafana.com/developers/plugin-tools/introduction/data-frames#wide-format)」を参照してください。視覚化をバージョン 8 以前と同じように機能させるには、手動で移行する必要がある場合があります。1 つの解決策は、Github の 「[Postgres/MySQL/MSSQL: Breaking change in v8.0 related to time series queries and ordering of data column](https://github.com/grafana/grafana/issues/35534)」に記載されています。 *[Grafana バージョン 9]* では、PostgreSQL データソースは、以前のバージョンとは異なる方法でデータベースに接続するためのルート証明書を設定します。ワークスペースをバージョン 8 から 9 に更新する場合、接続方法を変更する必要がある場合があります。詳細については「[ワークスペースの更新後のトラブルシューティング](AMG-workspace-version-update-troubleshoot.md)」を参照してください。 ## データソースの追加 1. 上部ヘッダーの Grafana アイコンを選択して、サイドメニューを開きます。 1. **設定**アイコンのサイドメニューに、**[データソース]** リンクがあります。 1. 上部ヘッダーの **[\$1 データソースの追加]** ボタンを選択します。 1. **[タイプ]** ドロップダウンリストから **[PostgreSQL]** を選択します。 ### データソースオプション | 名前 | 説明 | | --- | --- | | 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 は \$1\$1\$1timeGroup マクロで time\$1bucket を使用し、クエリビルダーに TimescaleDB 固有の集計関数を表示します (Grafana 5.3 以降でのみ使用可能）。 | ### 最小時間間隔 `$_interval` `$_interval_ms` 変数の下限。データを 1 分ごとに書き込む場合は `1m` など、書き込み頻度に設定することをお勧めします。このオプションは、[Data Source] (データソース) オプションのダッシュボードパネルで上書き/設定することもできます。この値は、`1m` (1 分) や `30s` (30 秒) など、有効な時間識別子が続く数値としてフォーマットする**必要があります**。以下の時間識別子がサポートされています。 | 識別子 | 説明 | | --- | --- | | y | 年 | | M | 月 | | w | 週 | | d | 日 | | h | 時間 | | m | 分 | | s | 秒 | | ms | ミリ秒 | ### データベースユーザーのアクセス許可 **重要** データソースを追加するときに指定するデータベースユーザーには、クエリする指定されたデータベースとテーブルに対してのみ SELECT アクセス許可を付与する必要があります。Grafana は、クエリが安全であることを検証しません。クエリには任意の SQL ステートメントを含めることができます。例えば、 `DELETE FROM user;` や`DROP TABLE user;` などのステートメントが実行されます。これを防ぐために、アクセス許可が制限された特定の PostgreSQL ユーザーを作成することを強くお勧めします。 次のコード例は、アクセス許可が制限された特定の PostgreSQL ユーザーの作成を示しています。 ``` CREATE USER grafanareader WITH PASSWORD 'password'; GRANT USAGE ON SCHEMA schema TO grafanareader; GRANT SELECT ON schema.table TO grafanareader; ``` ユーザーがパブリックロールから不要なアクセス許可を付与されていないことを確認します。 ## クエリエディタ PostgreSQL クエリエディタは、Graph または Singlestat パネルの編集モードのメトリクスタブにあります。パネルタイトルを選択して [編集] モードに入り、次に [編集] を選択します。 クエリエディタには、パネル編集モードでクエリが実行された後に表示される**[生成 SQL]** リンクがあります。これを選択すると、実行された未加工の補間 SQL 文字列が展開されて表示されます。 ### テーブル、時間列、メトリクス列 (FROM) を選択する 初めて編集モードに入るか新しいクエリを追加したとき、Grafana はタイムスタンプ列と数値列を持つ最初のテーブルをクエリビルダーに事前入力しようとします。 FROM フィールドでは、Grafana はデータベースユーザーの `search_path` にあるテーブルを提案します。`search_path` にないテーブルまたはビューを選択するには、`public.metrics` などの完全修飾名 (schema.table) を手動で入力できます。 Time 列フィールドは、時間値を保持する列の名前を指します。メトリクス列フィールドの値の選択はオプションです。値を選択すると、メトリクス列フィールドがシリーズ名として使用されます。 メトリクス列の提案には、テキストデータ型 (char、varchar、text) の列のみが含まれます。異なるデータ型を持つ列をメトリクス列として使用するには、キャスト `ip::text` を使用して列名を入力できます。`hostname || ' ' || container_name` などのテキストデータ型に評価される任意の SQL 式をメトリクス列フィールドに入力することもできます。 ### 列、ウィンドウ、集計関数 (SELECT) `SELECT` 行では、使用する列と関数を指定できます。列フィールドでは、`column1 * column2 / column3` などの列名の代わりに任意の式を記述できます。 クエリエディタで使用できる関数は、データソースの設定時に選択した PostgreSQL バージョンによって異なります。集計関数を使用する場合は、結果セットをグループ化する必要があります。集計関数を追加すると、エディタは自動的に `GROUP BY time` を追加します。 エディタは、クエリのこの部分を簡素化および統合しようとします。 プラスボタンを選択し、メニューから**列**を選択すると、さらに値列を追加できます。グラフパネルには、複数の値列が別々のシリーズとしてプロットされます。 ### データのフィルタリング (WHERE) フィルターを追加するには、`WHERE` 条件の右側にあるプラスアイコンを選択します。フィルターを削除するには、フィルターを選択し、**[削除]** を選択します。現在選択されている時間範囲のフィルターが、新しいクエリに自動的に追加されます。 ### グループ化の条件 時間または他の列でグループ化するには、GROUP BY 行の末尾にあるプラスアイコンを選択します。提案ドロップダウンリストには、現在選択されているテーブルのテキスト列のみが表示されますが、手動で任意の列を入力できます。項目を選択し、**[削除]** を選択して、グループを削除できます。 グループ化を追加する場合、選択したすべての列に集計関数を適用する必要があります。グループ化を追加すると、クエリビルダーは集計関数なしですべての列に集計関数を自動的に追加します。 #### ギャップ埋め Amazon Managed Grafana は、時間別にグループ化すると、欠損値を入力できます。時間関数は 2 つの引数を受け入れます。最初の引数はグループ化する時間枠で、2 つ目の引数は Grafana が不足している項目を埋める値です。 ### テキストエディタモード (RAW) ハンバーガーアイコン (三) を選択し、**[スイッチエディタモード]**を選択するか、クエリの下にある **[SQL の編集]** を選択して、未加工クエリエディタモードに切り替えることができます。 **注記** 未加工クエリエディタを使用する場合は、クエリに少なくとも `ORDER BY time` と、返された時間範囲のフィルターがあることを確認してください。 ## マクロ クエリ内でマクロは使用すると構文を簡素化し、動的な部分を使用できます。 | マクロの例 | 説明 | | --- | --- | | \$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) AND 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) as signed)300 as signed),\$1 などです | | \$1\$1\$1timeGroup(dateColumn,'5m', 0) | 前の行と同じですが、fill パラメーターがあるため、その系列の欠落しているポイントは grafana によって追加され、0 が値として使用されます。 | | \$1\$1\$1timeGroup(dateColumn,'5m', NULL) | 上記と同じですが、NULL は欠落ポイントの値として使用されます。 | | \$1\$1\$1timeGroup(dateColumn,'5m', previous) | 上記と同じですが、その系列の前の値がフィル値として使用されます。まだ値が見つからない場合は NULL が使用されます (Grafana 5.3 以降でのみ使用可能) 。 | | \$1\$1\$1timeGroupAlias(dateColumn,'5m') | \$1\$1\$1timeGroup と同じですが、列エイリアスが追加されます | | \$1\$1\$1unixEpochFilter(dateColumn) | 指定された列名を使用して、Unix タイムスタンプとして表される時間を使用して、時間範囲フィルターに置き換えられます。例えば、\$1dateColumn > 1494410783 AND dateColumn < 1494497183\$1 などです | | \$1\$1\$1unixEpochFrom()` | 現在アクティブな時間選択の開始が Unix タイムスタンプに置き換えられます。例えば、\$11494410783\$1 などです | | \$1\$1\$1unixEpochTo() | 現在アクティブな時間選択の最後が Unix タイムスタンプに置き換えられます。例えば、\$11494497183\$1 などです | | \$1\$1\$1unixEpochNanoFilter(dateColumn) | 指定された列名とナノ秒タイムスタンプとして表される時刻を使用して、時間範囲フィルターに置き換えられます。例えば、\$1dateColumn > 1494410783152415214 AND dateColumn < 1494497183142514872\$1 などです | | \$1\$1\$1unixEpochNanoFrom() | 現在アクティブな時間選択の開始がナノ秒タイムスタンプに置き換えられます。例えば、\$11494410783152415214\$1 などです | | \$1\$1\$1unixEpochNanoTo() | 現在アクティブな時間選択の終了がナノ秒タイムスタンプに置き換えられます。例えば、\$11494497183142514872\$1 などです | | \$1\$1\$1unixEpochGroup(dateColumn,"5m", [fillmode]) | \$1\$1\$1 timeGroup と同じですが、時刻は Unix タイムスタンプとして格納されます。 | ## テーブルクエリ クエリオプションが**[]テーブル としてフォーマット**に設定されている場合、基本的に任意のタイプの SQL クエリを実行できます。テーブルパネルには、クエリが返す列と行の結果が自動的に表示されます。 テーブルパネルの列名は、通常の `as` SQL 列選択構文を使用して制御できます。 ## 時系列クエリ **[Format as]** を `Time series` に設定する場合、例えばグラフパネルで使用するには、クエリは SQL 日時または Unix エポックを表す任意の数値データ型を返す `time` という名前の列を返す必要があります。`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 ``` 次のコード例は、\$1\$1\$1timeGroup マクロの fill パラメータを使用して 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 ``` ## テンプレート作成 メトリクスクエリでサーバー、アプリケーション、センサー名などのものをハードコーディングする代わりに変数を使用できます。変数は、ダッシュボードの上部にドロップダウン選択ボックスとして表示されます。これらのドロップダウンボックスを使用して、ダッシュボードに表示されるデータを変更できます。 テンプレート作成とテンプレート変数の詳細については、「[テンプレート](templates-and-variables.md#templates)」を参照してください。 ### クエリ変数 タイプ `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) ``` もう 1 つのオプションは、キー/値変数を作成できるクエリです。クエリは、 `__text` と `__value` という名前の 2 つの列を返します。`__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` を使用してクエリ変数で結果をフィルタリングする クエリフィールドで `__searchFilter` を使用すると、ドロップダウン選択ボックスのユーザータイプに基づいてクエリ結果がフィルタリングされます。ユーザーによって何も入力されていない場合、`__searchFilter` のデフォルト値は `%` です。 **注記** Grafana はこれを行わないため、`__searchFilter` 式を引用符で囲むことが重要です。 次の例は、`__searchFilter` をクエリフィールドの一部として使用してユーザーがドロップダウン選択ボックスに入力するときに `hostname` を検索できるようにします。 ``` SELECT hostname FROM my_host WHERE hostname LIKE '$__searchFilter' ``` ### クエリでの変数の使用 テンプレート変数の値は、テンプレート変数が `multi-value` の場合にのみ引用符で囲まれます。 変数が複数値の変数の場合は、`=` を使用して複数の値と照合するのではなく、`IN` 比較演算子を使用します。 2 つの構文があります。 `$` `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 ``` #### 複数値変数の引用をオフにする Amazon Managed Grafana は、複数値変数に対して引用符で囲まれたカンマ区切り文字列を自動的に作成します。例えば、`server01` と `server02` を選択した場合、`'server01', 'server02'` の形式になります。引用を無効にするには、変数に csv フォーマットオプションを使用します。 `${servers:csv}` 変数形式オプションの詳細については、「[テンプレートおよび変数](templates-and-variables.md)」を参照してください。 ## ‏注釈 注釈を使用して、グラフの上にリッチイベント情報をオーバーレイします。ダッシュボードメニュー/注釈ビューを使用して注釈クエリを追加します。詳細については、「[‏注釈](dashboard-annotations.md)」を参照してください。 次のコード例は、エポック値を持つ時間列を使用したクエリを示しています。 ``` SELECT epoch_time as time, metric1 as text, concat_ws(', ', metric1::text, metric2::text) as tags FROM public.test_data WHERE $__unixEpochFilter(epoch_time) ``` 次のコード例は、エポック値を持つ時間列と timeend 列を使用するリージョンクエリを示しています。 **注記** これは 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 日付/時刻データ型またはエポック値を持つ列にすることができます。 | | timeend | 終了日時フィールドのオプション名。ネイティブ SQL 日付/時刻データ型またはエポック値を持つ列にすることができます (Grafana v6.6 以降)。 | | text | イベントの説明フィールド。 | | tags | カンマ区切り文字列としてイベントタグに使用するオプションのフィールド名。 | ## [アラート] 時系列クエリは、アラート条件で機能します。テーブル形式のクエリは、アラートルール条件ではまだサポートされていません。