# Data Explorer

**Data Explorer**は、EMQX Tablesに保存されたデータをクエリ、分析、エクスポートするための統合インターフェースを提供します。クエリの作成・実行、クエリ実行の挙動の確認、クエリ履歴の管理、結果のエクスポートなど、一般的なワークフローを効率化するよう設計されています。

本ページでは、Data Explorerの主要コンポーネントを説明し、その機能を効果的に活用する方法を解説します。

## Overview

Data Explorerは以下の主要エリアで構成されています：

1. **Tablesパネル**：利用可能なスキーマ、テーブル、カラムを参照し、クエリ作成時にテーブル構造を素早く確認できます。
2. **クエリエディター**：SQLまたはPromQLクエリを作成・実行します。
3. **アクションツールバー**：クエリの実行、Explain Queryによる実行計画の解析、クエリファイルのアップロード・ダウンロード、クエリ履歴へのアクセスを行います。
4. **結果エリア**：クエリ結果、実行詳細を表示し、対応フォーマットでデータをエクスポートできます。

![data_explorer_overview](./_assets/data_explorer_overview.png)

## Tables Panel Controls

**Tables**パネルは展開・折りたたみが可能で、クエリ作成や結果分析に集中しやすくなっています。

- **Tables**の横にある展開/折りたたみアイコンをクリックしてパネルを切り替えます。

  ![tables_panel_control](./_assets/tables_panel_control.png)

- パネルが非表示の場合、クエリエディターと結果エリアが自動的に拡大し、横方向のスペースが増えます。

これは、長いまたは複雑なクエリを扱う際に、エディターの表示領域が広くなるため、可読性と作業効率が向上します。

## Query Editor

クエリエディターは、EMQX Tablesのデータに対してSQLまたはPromQLクエリを作成・実行する場所です。

### 対応クエリタイプ

クエリエディターは以下のクエリ言語をサポートしています：

- **SQL**（デフォルト）
- **PromQL**

エディター右上のセレクターでクエリタイプを切り替えられます。

### クエリ実行

**Run Query**ボタンは、選択されたクエリ言語に基づいてクエリを実行します。

#### SQLクエリ

**Run Query**ボタンは一度に1つのSQL文を実行します。

- エディターにSQL文が1つだけの場合は、**Run Query**をクリックすると直接実行されます。
- 複数のSQL文がある場合は、Data Explorerが以下のルールに従って実行する文を判別します。

この動作により、単純なクエリと複数文スクリプトの両方を同じエディターで効率的に扱えます。

#### 文選択ルール（SQLのみ）

複数のSQL文がある場合：

- 文はセミコロン（`;`）で区切られます。
- テキストが選択されていない場合、カーソルがある文が実行されます。
- テキストが選択されている場合は、選択された文のみが実行されます。

> すべてのSQL文を順に実行するには、**[Run All](#run-all)**を使用してください。

#### SQL文選択の例

##### 例1：1行に複数文がある場合

```sql
SELECT * FROM t1;SELECT count(*) FROM t1;SELECT * FROM t2;
```

- カーソルが`SELECT count(*) FROM t1;`内にある場合、以下の文が実行されます：

  ```sql
  SELECT count(*) FROM t1;
  ```

  ![query_example_1](./_assets/query_example_1.png)

- カーソルが`SELECT * FROM t2;`内にある場合、以下の文が実行されます：

  ```sql
  SELECT * FROM t2;
  ```

  ![query_example_1_result2](./_assets/query_example_1_result2.png)

##### 例2：複数行に分かれた文

```sql
SELECT * FROM t1
WHERE host = 'server1';

SELECT * FROM t2
ORDER BY "timestamp" DESC
LIMIT 10;
```

カーソルが最初のクエリ（`SELECT * FROM t1 ...`）内のどこかにある場合、以下の文が実行されます：

```sql
SELECT * FROM t1
WHERE host = 'server1';
```

![query_example_2](./_assets/query_example_2.png)

##### 例3：複数文をまとめて実行

```sql
SELECT * FROM t1
WHERE host = 'server1';

SELECT avg(usage_user) FROM t1
WHERE region = 'us-east-1';
```

マウスで両方の文を選択し、**Run Query**をクリックします。

両方の文が順に実行され、各成功した実行は別々の結果タブを生成します。

![query_example3_result1](./_assets/query_example3_result1.png)

![query_example3_result2](./_assets/query_example3_result2.png)

#### PromQLクエリ

PromQLの場合、**Run Query**ボタンは常に単一のPromQL文を実行します。

- エディターには1つのPromQL文のみがサポートされます。
- カーソル位置やテキスト選択は**適用されません**。
- 複数のPromQL文の実行や文の一部選択はサポートされていません。

PromQLクエリがある場合は、**Run Query**をクリックすると文が直接実行されます。

### Run All

**Run All**ボタンは、エディター内のすべてのSQL文を順に実行します。

- **SQLのみ**対応。
- 各成功した文の実行は別々の結果タブを生成します。

バッチクエリの実行や複数クエリの結果比較に便利です。

## Explain Query

**Explain Query**機能は、SQLまたはPromQLクエリが内部でどのように実行されるかを理解するのに役立ちます。

クエリの詳細な実行プロセスを返し、以下を含みます：

- 実行ステージの構成
- クエリの計画と実行方法
- 各ステージに費やされた時間

Explain Queryは、パフォーマンスのボトルネック特定、遅いSQL/PromQLクエリの分析、クエリ設計の最適化に一般的に利用されます。

現在のSQLまたはPromQL文を解析するには、**Explain Query**をクリックします。Explain結果は専用の**Explain**タブに表示され、通常のクエリ結果タブの左側に配置されます。最新のExplain結果のみが保持・表示されます。

Explain Query結果は3つの異なるビューをサポートし、実行計画を多角的に確認できます。

### Table View

Tableビューは、クエリ実行計画を構造化されたステージベースの表形式で表現します。実行はステージごとにグループ化され、各ステージはクエリが内部でどのように処理されるかを反映した階層的なオペレーターツリーを表示します。

![explain_query_table](./_assets/explain_query_table.png)

**Select Metric**ドロップダウンで、選択したステージに表示する実行メトリックを切り替えられます。メトリックを変更すると、Tableビューの値や視覚的指標が更新され、同じ実行計画を異なるパフォーマンス視点から分析可能です。

![explain_query_select_metric](./_assets/explain_query_select_metric.png)

::: tip 注意

クラスター展開の場合、実行詳細は各GreptimeDBノードごとに表示され、個々のノードでのクエリ実行状況を確認できます。ノードセレクターはクラスターに複数ノードがある場合のみ表示されます。

本節の例はすべて単一ノード展開のExplain結果に基づいています。

:::

### Chart View

Chartビューは、クエリ実行計画をインタラクティブなグラフィカルツリー図として表示し、実行ステージとオペレーターの関係を視覚的に表現します。

Chartビューでは以下が可能です：

- 個々の実行ノードをクリックして詳細を確認、または各ノードに表示された主要メトリックを直接読み取る。
- ノードに表示された実行メトリック（実行時間やリソース使用量など）を生のExplainデータの対応値と照合する。

![explain_query_chart_view](./_assets/explain_query_chart_view.png)

**メトリック表示モード**

右上のコントロールで、チャート内のメトリック表示方法を切り替えられます：

- **None**：メトリックに基づく視覚化なしで実行ツリー構造のみを表示
- **Rows**：処理行数に基づいてノードを強調表示
- **Duration**：実行時間に基づいてノードを強調表示

モードを変更すると、視覚的な強調表示と各ノードの表示値が更新され、異なる視点から実行計画を分析できます。

Chartビューは、実行パスの視覚的追跡、オペレーター間の親子関係の理解、各実行ステップのパフォーマンス特性の検証に便利です。

### Raw View

RawビューはAPIレスポンスのJSON形式を表示し、コピーしてさらなる分析に利用できます。

![explain_query_api](./_assets/explain_query_api.png)

## Query Results

クエリが正常に実行されるたびに、Data Explorerは新しいクエリ結果を生成します。

- 成功したクエリ実行ごとに新しい**Result**タブが生成されます。
- タブは連番でラベル付けされ（例：`Result 1`、`Result 2`）、自由に切り替え可能です。
- 個別のタブは**✕**アイコンで閉じられます。

結果は現在のデプロイメントページを離れると**保持されません**。

### 結果ビュー

クエリやデータの形状に応じて、結果は以下の形式で表示されます：

- **Tableビュー（デフォルト）**：ページネーション付きの表形式でクエリ結果を表示します。生データや正確な値の確認に適しています。

- **Chartビュー**：クエリ結果をチャートとして可視化し、傾向分析や比較を容易にします。

  ![query_result_chart](./_assets/query_result_chart.png)

## クエリ結果のエクスポート

Data Explorerからクエリ結果をCSV形式で直接エクスポートできます。

1. クエリ文を入力します。
2. **Run Query**の隣のドロップダウン矢印をクリックします。
3. **Export Result as CSV**を選択します。
4. システムがクエリを実行し、結果をダウンロードします。

![export_result](./_assets/export_query_result.png)

## Query History

Query Historyは、現在のデプロイメント内で過去に実行したSQLおよびPromQLクエリを確認、再利用、管理するのに役立ちます。

### 自動履歴保持

クエリ履歴は以下のルールに従って自動的に記録されます：

- クエリ履歴はブラウザのローカルに保存されます。
- 履歴は最大30日間保持されます。
- 各デプロイメントごとに：
  - SQLクエリは最大100件
  - PromQLクエリは最大100件
- 上限に達すると最も古い履歴が自動的に削除されます。
- デプロイメントが削除されると、すべてのクエリ履歴も削除されます。

### クエリ履歴パネルの開き方

ツールバーの**History**アイコンをクリックすると、**Query History**パネルが開きます。

このパネルからは：

- **SQL**または**PromQL**で履歴をフィルターできます。
- クエリ履歴内を検索できます。
- 各クエリの実行時間を確認できます。
- 履歴エントリーをクリックすると、クエリエディターにクエリが挿入されます。

### クエリ履歴のダウンロード

フィルター検索結果を含むクエリ履歴をダウンロードできます。

- **SQL履歴**

  - `.sql`ファイルとしてエクスポート
  - 文は空行で区切られています
  - 各文はセミコロン（`;`）で終了

  ```sql
  select * from t2
  where host = 'server1';
  
  SELECT * FROM public."t2" ORDER BY "timestamp" DESC LIMIT 100;
  ```

- **PromQL履歴**

  - `.txt`ファイルとしてエクスポート
  - 1行に1クエリ

  ```text
  sum(t1)
  t1
  ```

![query_history_panel](./_assets/query_history_panel.png)

### クエリ履歴ファイルのアップロード

クエリ履歴ファイルをアップロードして、既存クエリの再利用や編集を素早く行えます。

- 対応ファイル形式は`.sql`および`.txt`です。
- アップロード後、ファイル内容が現在のクエリエディターの内容に置き換わります。

![upload_query_file](./_assets/upload_query_file.png)