# SQL エディタ

> DuckLocal の DuckDB SQL エディタ：クエリタブ、フォーマット、インラインエラー、スキーマに応じた自動補完、Explain プラン、オペレーターごとのプロファイリング、ショートカット。

Source: https://ducklocal.app/docs/ja/sql-editor

各クエリタブは独自のエディタバッファーを持ちます。エディタは tree-sitter によって実際の SQL を
ハイライトし、2 スペースでインデントし、行番号を表示します。

## タブ

| 操作 | 動作 |
| --- | --- |
| `+` または **⌘T** | 新しいクエリタブを追加し、そこにフォーカスします |
| タブをクリック | そのタブに切り替えます |
| **Ctrl+Tab** / **Ctrl+Shift+Tab** | 次 / 前のタブ |
| **⌘1** … **⌘8**、**⌘9** | 1 番目から 8 番目のタブ。⌘9 は最後のタブ |
| タブをドラッグ | タブストリップ上で移動します |
| `×`、**⌘W**、または中クリック | タブを閉じます。最後のタブは閉じられません。その `×` は非表示になり、⌘W は何もしません。未保存の変更があるダッシュボードは先に確認します |
| タブを右クリック | **タブを閉じる**、**他のタブを閉じる**、**右側のタブを閉じる**。未保存の変更があるダッシュボードは開いたままになり、通知にその数が表示されます |
| タブをダブルクリック | そのタイトルをその場で編集します。Enter または外側をクリックで新しいタイトルを保持し、Escape で元のタイトルを保持します。空のタイトルは `Query N` に戻ります |

開いているタブは次回の起動時にその順序で戻ってきます。クエリタブはタイトルとエディタ内の SQL
（実行したかどうかに関係なく）、そしてダッシュボードタブです。結果は戻りません —
クエリを再実行してください。新しく開いたクエリタブは
`SELECT 'Hello, DuckLocal' AS greeting;` から始まります。

## ツールバー

エディタの上、左から：

| ボタン | 動作 |
| --- | --- |
| **実行** | エディタの SQL を実行します — [SQL の実行](#running-sql) を参照 |
| **停止** | 実行がしばらく続いたときに表示され、それを中断します |
| **フォーマット** | SQL を再フォーマットします — [フォーマット](#format) を参照 |
| **Explain** | 文を実行せずに、DuckDB が使うプランを表示します |
| **プロファイル** | クエリを実行し、各オペレーターのコストを表示します |

**Explain** と **プロファイル** については
[Explain とプロファイル](#explain-and-profile) で説明します。

## SQL の実行 {#running-sql}

エディタにフォーカスがある状態で **⌘↵**（Cmd+Enter）を押すか、**実行** ボタンを使います。

クエリの実行中に実行を再度押しても何も起こらず（Explain とプロファイルも同様）、
クエリの実行がしばらく続くと **実行** の横に **停止** ボタンが表示されます。停止、または **⌘.** でクエリを
中断します。クエリは DuckDB の `Interrupted` エラーで終わり、他の失敗と同様に履歴に記録されます。
タイムアウトはありません。停止しない限り、クエリは DuckDB が必要とするだけ実行され、
他のデータベース作業はその後ろで待ちます。

結果は DuckDB からストリーミングされるため、スキャンはグリッドの
[行数制限](results-and-charts.md#row-limits) に達した時点で止まり、ファイルの残りを
読むことはありません。最初の行より前にすべての行を見る必要があるクエリ —
`ORDER BY`、`GROUP BY`、集計、ウィンドウ関数 — は完全に計算されます。

各タブは独自の結果を持ちます。タブを切り替えた後に届いた結果は、
それを実行したタブに入ります。

文がどう扱われるかは先頭のキーワードで決まります。`SELECT`、`WITH`、
`SHOW`、`DESCRIBE`、`EXPLAIN`、`PRAGMA`、`SUMMARIZE`、`VALUES`、`FROM`、
`TABLE`、`PIVOT`、`CALL` は結果セットを返します。それ以外 — DDL（データ定義）と
DML（データ変更）の文 — はグリッドの代わりに
`Done: N rows affected, took …` を報告します。判定時に先頭の `--`
コメントはスキップされますが、ブロックコメントはスキップされません。

### スクリプト

エディタは複数の文を保持できます。**実行** はそれらをすべて順番に、
DuckDB シェルがファイルを読むのと同じように実行し、**最初の失敗で停止** します —
失敗した `ATTACH` の後に `SELECT` を実行しても、2 つ目の誤解を招くエラーが
増えるだけだからです。結果の上のストリップに文が一覧表示され、それぞれに
行数、*完了*、*失敗*、*未実行* のマークが付きます。クリックするとその結果を確認できます。
エラーはスクリプト全体ではなく、失敗した文に下線を引きます。

シェルのドットコマンドの一部も、それぞれ独立した行で動作します。

| コマンド | 表示内容 |
| --- | --- |
| `.tables ?PATTERN?` | テーブルとビュー。オプションで `stat%` のような `ILIKE` パターンで絞り込めます |
| `.schema ?PATTERN?` | テーブルとビューの `CREATE` 文。オプションで絞り込めます |
| `.databases` | アタッチされているデータベース |
| `.help` | この一覧 |

その他のドットコマンド（`.mode`、`.read`、…）は、動作するコマンド名を示す
エラーになります。

## エラー

失敗した文は、DuckDB のメッセージをそのまま含む *クエリに失敗しました* というタイトルのアラートを表示します。
メッセージはエンジンからのもので、インターフェースの言語にかかわらず
常に英語です。グリッドには何も書き込まれず、
その試行は失敗マーカー付きで [履歴](schema-and-history.md) に記録されます。

メッセージが位置を指す場合 — パーサーとバインダーのエラーは
`LINE n:` の行とキャレットでそうします — エディタはその箇所に赤い波線を
引きます。キャレットが指すトークン、または連続するキャレットが覆う範囲です。マークは
編集に追従し、次の実行で消えます。実行時エラーは位置を持たないため、
マークは付きません。

## フォーマット {#format}

**フォーマット** はバッファーを `sqlformat` に通します。インデントは 2 スペース、キーワードは
大文字になり、バッファー全体が置き換えられます。空のバッファーでは
何もしません。

## Explain とプロファイル {#explain-and-profile}

どちらのボタンもエディタのテキスト全体に対して動作し、どちらも **ちょうど 1 つの文** を
取ります。2 つ以上ある場合 — またはドットコマンドがある場合 — は
*Explain とプロファイルは 1 つの文だけを扱います。対象の文を専用のタブに入れてください。*
というメッセージで拒否します。末尾の `;` と末尾のコメントは問題ありません。

実行、Explain、プロファイルのいずれかが実行中は、残りの 2 つは何もしません。
Explain もプロファイルも [履歴](schema-and-history.md#query-history) には記録されません。
その出力は **結果** タブのグリッドを置き換え、別のタブが開いていればそこへ切り替わります。
失敗した場合は、実行の失敗と同様に *クエリに失敗しました* アラートを表示します。

### Explain（実行計画）

**Explain** は `EXPLAIN <your statement>` を実行し、DuckDB のプランをプレーンな
等幅テキストで、所要時間とともに表示します。プランを立てるだけで、文は
実行されないため、`INSERT`、`UPDATE`、`DELETE` の Explain は安全です。

### プロファイル

**プロファイル** は `EXPLAIN (ANALYZE, FORMAT JSON)` の下で文を実行し、
実行されたプランをツリーとして表示します。各オペレーター自身の時間と全体に占める割合、
オプティマイザーの推定値に対する実際の出力行数（10 倍以上ずれている場合は
フラグ付き）、そして何をフィルターし、何で結合し、何を射影したかです。最もコストが
高かったオペレーターは上部に示され、赤で描画されます。読み方については
[Explain とプロファイルの出力](results-and-charts.md#explain-and-profile) を参照してください。

**プロファイルは実際に文を実行します** — それによってオペレーターの時間が計測されます。
そのため、単一の読み取り専用クエリのみを受け付けます。

- **受け付ける：** `SELECT`、`WITH … SELECT`、`FROM …`、`VALUES`、`TABLE`、`SHOW`、
  `DESCRIBE`、`SUMMARIZE`。
- **拒否する：** 書き込みを行うもの（`INSERT`、`UPDATE`、`DELETE`、`CREATE`、…）、
  `CALL`、`PRAGMA`、`COPY`、`EXPLAIN` 自体、`WITH` の背後に隠れた書き込み
  （`WITH s AS (…) INSERT …`）、明示的な `IN (…)` リストのない `PIVOT`。

拒否された文には *読み取りを行う文だけをプロファイルできます（SELECT、WITH、FROM…）：プロファイルは文を実行します。*
と表示されます。これを判断するのは DuckDB 自身のパーサーであり、実行前に
行われ、最初のキーワードによるものではありません。

プロファイルにはクエリと同じ時間に、計測のコストが加わります。**停止**
（または **⌘.**）で、実行時と同様に中断できます。

## 自動補完

補完メニューはカタログを認識します。候補は次の順にランク付けされます。

1. スキーマからのテーブルと列（最大 35 項目）
2. DuckDB の関数名
3. SQL のキーワード

最大 50 項目が提示されます。照合はカーソルのすぐ左にある識別子に対する、大文字と小文字を
区別しない **前方一致** なので、`sel` は `SELECT` に補完されますが、`elect` は
何にも補完されません。関数は名前と開き括弧を挿入します。スペースや特殊文字を
含む識別子は、二重引用符で囲んで挿入されます。

キーワードと関数のリストは厳選されたサブセットであり、すべての DuckDB
関数が表示されるわけではありません。

## キーボードショートカット

Windows と Linux では、全体を通じて **⌘** を **Ctrl** として読んでください。

DuckLocal 自身のショートカットは、すべてメニューバーに一覧されています。

| ショートカット | 動作 |
| --- | --- |
| ⌘↵ | クエリを実行 |
| ⌘. | 実行中のクエリを停止 |
| ⌘T | 新しいクエリタブ |
| ⌘W | タブを閉じる |
| Ctrl+Tab / Ctrl+Shift+Tab | 次 / 前のタブ（Mac でも Ctrl） |
| ⌘1 … ⌘9 | その位置のタブへ移動。⌘9 は最後 |
| ⌘O | データを開く |
| ⌘S | ダッシュボードのソースをソースビューで保存 |
| ⌘B | サイドバーの表示 / 非表示 |
| ⌘+ / ⌘− / ⌘0 | インターフェースを大きく / 小さく / デフォルトサイズに — [インターフェースのサイズ](settings-and-data.md#interface-size) を参照 |
| ⌘Q | 終了 |

エディタ自身のショートカットは、他のテキストフィールドと同じように動作します。

| ショートカット | 動作 |
| --- | --- |
| ⌘F / ⇧⌘F | エディタ内で検索 / 置換 |
| ⌘Z / ⇧⌘Z | 元に戻す / やり直す |
| ⌘A | すべて選択 |
| ⌘C / ⌘X / ⌘V | コピー / 切り取り / 貼り付け |
| ⌥⌘↑ / ⌥⌘↓ | 上 / 下にカーソルを追加 |
| ⌘← / ⌘→ / ⌥← / ⌥→ | 行 / 単語単位で移動 |
| ⌘↑ / ⌘↓ | ドキュメントの先頭 / 末尾へ移動 |
| ⌘⌫ / ⌥⌫ | 行頭 / 前の単語まで削除 |

## メニュー

メニューバーには、すべてのウィンドウコマンドがショートカットとともに含まれています。

| メニュー | コマンド |
| --- | --- |
| DuckLocal | コマンドラインと AI、アップデートを確認…、起動時にアップデートを確認、ガイドを表示、ログフォルダーを開く、DuckLocal を終了 |
| ファイル | 新しいクエリ、データを開く、保存、タブを閉じる、次のタブ、前のタブ |
| 編集 | 元に戻す、やり直す、切り取り、コピー、貼り付け、すべて選択 |
| クエリ | 実行、停止 |
| 表示 | サイドバーの表示 / 非表示、インターフェースを大きく、インターフェースを小さく、デフォルトサイズ、オンラインのベースマップ（OpenStreetMap） |

Windows と Linux にはメニューバーがありません。そこでは **ガイドを表示** と
**ログフォルダーを開く** は、ステータスバー右端のバージョン表示の右クリックメニューにあります。

**オンラインのベースマップ（OpenStreetMap）** はチェック項目です。
[グラフ](results-and-charts.md#charts) を参照してください。スキーマのサイドバーの行にも
右クリックメニューがあります。[スキーマと履歴](schema-and-history.md#right-click-menu) を
参照してください。コマンドパレットはありません。
