QueryHub データソース設定とクエリ例¶
本記事では、データソースごとの接続設定、ネイティブクエリと DQL Like クエリの例、およびクエリ可能なテーブル、メトリクス、インデックス、コレクション、フィールドの確認方法について説明します。
- MySQL · PostgreSQL · Prometheus · Elasticsearch · MongoDB
- データソース ID、名前、説明、および接続テスト、権限、保存の共通手順については、概要と設定を参照してください。データソース ID は手動で入力する必要があります。
- 実際のクエリ入口と結果を更新する手順については、クエリと利用を参照してください。QueryHub はネイティブクエリと DQL Like をサポートしており、どちらも手入力で、選択したインスタンスで実際に有効なクエリモードに従います。
各表の認証フィールドには具体的な必須条件が記載されています。対応する認証方式を選択した後、該当する資格情報を入力してください。証明書フィールドは TLS の要件に従って入力します。アドレス、アカウント、パスワード、トークン、証明書は、データソース管理者または運用担当者が提供します。
DQL Like 式の datasource は、現在選択しているインスタンスの ID と一致している必要があり、source はデータソースタイプと一致している必要があります。クエリ対象とフィールドは実際のデータに合わせて入力してください。以下の例はすべて読み取り専用であり、アカウントにも対象データの読み取り権限が必要です。
共通 TLS 設定¶
5 種類のデータソースはいずれも TLS 設定を提供します。新しい接続の作成時はデフォルトで disable が使用され、証明書などのサブフィールドは非表示になります。disable 以外のモードを選択した後、サーバー側の要件に従って対応するフィールドを入力してください。各タイプ固有のフィールドについては、後続の該当セクションを参照してください。
| 設定項目 | 必須 | 意味と入力方法 |
|---|---|---|
| TLS モード | 任意 | デフォルトは disable です。TLS が必要な場合は、サーバー側の要件に従って対応するモードを選択し、データソース管理者が確認します |
| CA 証明書 | 任意 | サーバー証明書の検証に使用する CA 証明書の内容です。必要な場合は管理者が提供し、証明書のテキストを貼り付けます |
| クライアント証明書 | 認証方式に応じて必須 | サーバーがクライアント証明書認証を要求する場合に入力します。管理者が発行し、クライアント秘密鍵とペアで入力する必要があります |
| クライアント秘密鍵 | 認証方式に応じて必須 | クライアント証明書と一致する秘密鍵の内容です。管理者が提供し、クライアント証明書とペアで入力する必要があります |
| サーバー名 | 任意 | TLS 検証で使用するサーバー名です。通常は証明書内のドメイン名に対応し、管理者が確認します |
| 証明書検証をスキップ | 任意 | チェックするとサーバー証明書の検証をスキップします。CA 証明書を同時に設定できず、verify、verify-full モードとも併用できません。通常はチェックしないでください |
MySQL¶
接続フィールド¶
| 設定項目 | 必須 | 意味と入力方法 |
|---|---|---|
| ホストアドレス | 必須 | MySQL サービスのドメイン名または IP です。データベース管理者またはクラウドデータベースの接続情報から取得し、管理コンソールの URL は入力しません |
| ポート | 任意 | ページには 3306 が事前入力されています。カスタムポートを使用する場合は実際の値を入力します |
| デフォルトデータベース | 任意 | 接続でデフォルト使用するデータベース名であり、テーブル名ではありません。クエリ内でデータベース名のプレフィックスがないテーブル名は、これをデフォルトデータベースとして扱います。データベース管理者が確認します |
| ユーザー名 | 任意 | サービスの認証要件に従い、対象データベースとテーブルの読み取り権限を持つデータベースアカウントを入力します |
| パスワード | 任意 | 上記データベースアカウントのパスワードです。アカウント管理者が提供します |
| 文字セット | 任意 | 接続で使用する文字エンコーディングです。ドロップダウンからデータベースの要件と一致する文字セットを選択し、データベース管理者が確認します |
| 日時を解析 | 任意 | データベースの日時値を時間型として解析するかどうかを制御します。ページではデフォルトでチェックされています。クエリの時間範囲を設定するものではありません |
クエリ例¶
例では orders テーブルの id、total、status フィールドを使用しています。実際のテーブル名とフィールドに置き換えてください。
ネイティブクエリ
支払済み注文を最大 10 件取得し、注文 ID で並べ替えます:
DQL Like
queryhub(source="mysql", datasource="mysql-orders")::orders:(id,total) {status = "paid"} ORDER BY id LIMIT 10
テーブルとフィールドの確認¶
以下はすべてネイティブクエリで手動実行し、1 回につき 1 件ずつ実行します。
現在のデータベースでアカウントが参照権限を持つテーブルを確認します:
orders の列名、型などの定義を確認します:
これらのクエリはメタデータテーブルを返しますが、ページがすべてのフィールドを自動スキャンまたは生成することを意味しません。表示範囲はデータベースアカウントの権限によって異なります。
集計クエリ例¶
ネイティブクエリに以下の SQL を入力し、注文ステータス別に金額を集計してから、右上の更新をクリックして結果を確認します:
SELECT status, SUM(total) AS total_amount
FROM orders
GROUP BY status
ORDER BY total_amount DESC
LIMIT 10
時間を限定する必要がある場合は、実際に存在する時間フィールドを使用して SQL に条件を記述してください。ページの時間範囲を調整しても、任意の SQL に時間フィルターが自動追加されることはありません。
PostgreSQL¶
接続フィールド¶
| 設定項目 | 必須 | 意味と入力方法 |
|---|---|---|
| ホスト | 必須 | PostgreSQL サービスのドメイン名または IP です。データベース管理者またはクラウドデータベースの接続情報から提供されます |
| ポート | 任意 | ページには 5432 が事前入力されています。カスタムポートを使用する場合は実際の値を入力します |
| データベース | 必須 | この接続でアクセスするデータベース名であり、スキーマまたはテーブル名ではありません |
| ユーザー名 | 必須 | 対象スキーマとテーブルの読み取り権限を持つデータベースアカウントです。データベース管理者が提供します |
| パスワード | 認証方式に応じて必須 | パスワード認証を使用する場合は必須です。サーバーがクライアント証明書認証を許可しており、ペアのクライアント証明書と秘密鍵を入力済みの場合は空欄にできます |
| スキーマ | 任意 | テーブルが存在する名前空間です。ページには public が事前入力されています。データベース管理者が確認し、クエリ時にも同じ範囲を使用します |
クエリ例¶
例では public スキーマの orders テーブルを使用しています。実際の設定に合わせてスキーマ、テーブル名、フィールドを置き換えてください。データベースとスキーマは異なる 2 つの範囲です。
ネイティブクエリ
DQL Like
テーブルとフィールドの確認¶
ネイティブクエリで 1 回につき 1 件ずつ実行し、public を設定済みのスキーマに置き換えてください。結果はデータベースアカウントの表示範囲によって異なります。
テーブル名を確認します:
orders のフィールド名と型を確認します:
SELECT column_name, data_type FROM information_schema.columns
WHERE table_schema = 'public' AND table_name = 'orders'
ORDER BY ordinal_position LIMIT 50
テーブル名が同じでもスキーマが異なる場合は、クエリで完全な schema.table を使用し、選択したインスタンスで許可される範囲と一致させてください。
Prometheus¶
接続フィールド¶
| 設定項目 | 必須 | 意味と入力方法 |
|---|---|---|
| サービスアドレス | 必須 | Prometheus クエリサービスのベースアドレスです。例:http://prometheus.example.com:9090。この HTTP の例は TLS モード disable に対応します。HTTPS アドレスを使用する場合は、disable 以外の TLS モードを選択する必要があります。サービス管理者が提供し、管理ページのアドレスや完全な /api/v1/query パスは入力しません |
| 認証方式 | 任意 | デフォルトは認証なしです。Basic または Bearer を選択でき、2 つの認証方式は排他的です |
| ユーザー名 | 認証方式に応じて必須 | Basic 認証を選択した場合に必須です。サービスまたはゲートウェイの管理者が提供し、ワークスペースのログインアカウントではありません |
| パスワード | 認証方式に応じて必須 | Basic 認証を選択した場合に必須です。上記のユーザー名に対応します |
| Bearer トークン | 認証方式に応じて必須 | Bearer 認証を選択した場合に必須です。管理者が発行し、Bearer プレフィックスは付けません。ワークスペースの API Key ではありません |
クエリ例¶
クエリ対象はメトリクスであり、job、instance などはサンプルラベルです。例は実際のメトリクスとラベルに置き換えてください。
ネイティブクエリ
ネイティブクエリの入力欄に完全な JSON を入力し、operation でクエリ操作を指定し、PromQL は statement に記述します。
インスタントクエリ:
レンジクエリ:
{"operation":"query_range","statement":"up{job=\"fixture\"}","arguments":{"start":"#{startTime}","end":"#{endTime}","step":15}}
#{startTime} と #{endTime} はグラフの時間範囲を参照し、フロントエンドが自動的に時間を秒に変換します。step の単位も秒で、例では 15 秒です。これらのパラメータは JSON の arguments に記述します。
DQL Like
クエリ結果¶
Studio のテーブルでは、「名前」と「ラベル」はそれぞれシリーズの name と tags に由来します。時間列は time で、API は Unix ミリ秒タイムスタンプを使用し、ページでは書式設定して表示されます。数値列名はメトリクス名または式に応じて変わります。
メトリクスとラベルの確認¶
ネイティブクエリの入力欄に以下の JSON を入力し、確認するメトリクスの PromQL を statement に記述します。既知の名前または範囲の狭い正規表現を使用して、現在サンプルがあるメトリクスを確認します:
例は up と http_requests_total のみに一致します。実行後、テーブルで一致したシリーズの名前とラベルを確認します。
job、instance などのラベルを確認する場合は、上記のインスタントクエリの JSON を実行し、結果テーブルの「ラベル」で確認します。サンプルがない場合は、ラベル条件を確認するか、クエリ時間を調整してください。
これらの結果は現在一致したサンプルのみを反映し、すべてのラベルやメトリクスカタログを表すものではありません。これに基づいて他のメトリクスが存在しないと判断することはできません。
Elasticsearch¶
接続フィールド¶
| 設定項目 | 必須 | 意味と入力方法 |
|---|---|---|
| サービスアドレス | 必須 | Elasticsearch クエリサービスのベースアドレスです。例:https://es.example.com:9200。この HTTPS の例では disable 以外の TLS モードを選択する必要があります。HTTP アドレスを使用する場合は disable を選択する必要があります。管理者が提供し、Kibana のアドレスや完全な _search パスは入力しません |
| 認証方式 | 任意 | デフォルトは認証なしです。Basic または Bearer を選択でき、2 つの認証方式は排他的です |
| ユーザー名 | 認証方式に応じて必須 | Basic 認証を選択した場合に必須です。対象インデックスの読み取り権限が必要です |
| パスワード | 認証方式に応じて必須 | Basic 認証を選択した場合に必須です。上記のユーザー名に対応し、アカウント管理者が提供します |
| Bearer トークン | 認証方式に応じて必須 | Bearer 認証を選択した場合に必須です。管理者が発行し、Bearer プレフィックスは付けません。API Key を Bearer トークンとして入力しないでください |
| インデックス | 必須 | このインスタンスでクエリするインデックスです。例:orders。データ管理者が確認します。DQL Like の対象は、インスタンス設定の範囲と一致している必要があります |
クエリ例¶
例では、インスタンスに設定されたインデックスが orders であることを前提としています。ドキュメントをクエリする場合は、テーブルチャートで結果を確認します。
ネイティブクエリ
ネイティブクエリの入力欄に完全な JSON を入力し、operation に search を使用し、リクエスト本文を arguments.body に記述します:
DQL Like
テーブルチャートで document JSON を展開してドキュメントを確認します。投影フィールドは JSON 内に保持され、自動的に独立したテーブル列になることはありません。
インデックスとフィールドの確認¶
クエリ可能なインデックスは、現在のインスタンス設定に従います。ネイティブクエリの入力欄に以下の JSON を入力し、実行後にテーブルで一致した結果の index 列を読み取ります:
インデックスに一致するドキュメントがない場合は、インスタンス設定に従ってください。空の結果によってインデックスの存在を判断しないでください。
ドキュメントサンプルとそのキーを確認するには、ネイティブクエリに以下を入力します:
テーブルチャートで結果の document JSON を展開してフィールドを確認します。ドキュメントには疎なフィールドが含まれる場合があり、限られた範囲でより多くのサンプルを読み取れます。これは完全な mapping ではなく、完全な定義は Elasticsearch 側で確認する必要があります。
MongoDB¶
接続フィールド¶
| 設定項目 | 必須 | 意味と入力方法 |
|---|---|---|
| ホストリスト | 必須 | 実際には 1 つのホスト名または IP のみ入力できます。データベース管理者が提供し、ポートは別途入力します |
| ポート | 任意 | ページには 27017 が事前入力されています。カスタムポートを使用する場合は実際の値を入力します |
| 認証方式 | 任意 | デフォルトは認証なしです。パスワード認証を選択すると、ユーザー名、パスワード、認証データベースのフィールドが表示されます |
| ユーザー名 | 認証方式に応じて必須 | パスワード認証を選択した場合に必須です。対象データベースとコレクションの読み取り権限を持つ MongoDB アカウントを使用します |
| パスワード | 認証方式に応じて必須 | パスワード認証を選択した場合に必須です。上記のユーザー名に対応し、アカウント管理者が提供します |
| 認証データベース | 任意 | パスワード認証時に入力できます。アカウントの識別情報が存在するデータベースを示し、admin も指定できます。管理者が確認します |
| クエリデータベース | 必須 | 業務ドキュメントを読み取るデータベース名です。admin、config、local は使用できません |
| コレクション | 必須 | コレクション名のみを入力します。例:items。データベース名のプレフィックスは付けません。ネイティブの find クエリはこのコレクションを使用します |
クエリ例¶
例では、インスタンスに items コレクションが設定され、ドキュメントに業務フィールド id と status が含まれていることを前提としています。クエリデータベースと認証データベースは異なる場合があります。テーブルチャートでドキュメント結果を確認します。
ネイティブクエリ
ネイティブクエリの入力欄に完全な JSON を入力し、operation に find を使用し、フィルター、投影、返却件数を arguments に記述します。データベースとコレクションは現在のインスタンス設定を使用します:
{"operation":"find","arguments":{"filter":{"status":"paid"},"projection":{"id":1,"status":1},"limit":10}}
filter はフィルター条件を定義し、projection は読み取るドキュメントフィールドを指定し、limit は返却件数を制限します。例の id は業務フィールドであり、MongoDB のデフォルトの _id とは異なります。実際のドキュメント構造に合わせて調整してください。
DQL Like
テーブルチャートで document JSON を展開してドキュメントを確認します。投影フィールドは JSON 内に保持され、自動的に独立した列に展開されることはありません。
コレクションとフィールドの確認¶
クエリ可能なデータベースとコレクションは、現在のインスタンス設定に従います。Studio のエントリポイントでは listCollections は提供されません。
ネイティブクエリの入力欄に以下の JSON を入力し、1 件のサンプルドキュメントを読み取ります:
テーブルチャートで document JSON を展開してドキュメントのキーを確認します。ドキュメントによって構造が異なる場合があるため、フィルター条件を変更するか、限られた範囲でサンプル数を適切に増やしてください。サンプル内容は完全なスキーマを表すものではなく、アカウント権限が増えることもありません。