# スキーマブラウザーと履歴

> DuckLocal のスキーマサイドバーでデータベース、テーブル、列を閲覧し、SELECT クエリを生成し、DuckDB の拡張機能を管理して過去のクエリを再利用する方法。

Source: https://ducklocal.app/docs/ja/schema-and-history

サイドバーには **スキーマ**、**履歴**、**拡張機能** の 3 つのタブがあります（中国語では **表结构**、**查询历史**、**扩展**）。タイトルバー左端のボタン、または **⌘B** でサイドバーを隠したり再び表示したりできます。ボタンはどちらの状態でも同じ位置にあります。サイドバーを隠したかどうかは記憶されます。

## スキーマツリー

ツリーは上から順に、**ローカルファイル**、**ダッシュボード**、**指標**、**S3** をグレーの小さなセクション見出しとして表示し、その下にデータベースを太字の行として表示します:

- **ローカルファイル** — 登録したデータファイル。それぞれビュー名で表示され、行数が付きます。子要素はそのビューの列です。
  - ビュー名とファイル名が異なる場合にだけ、ビュー名の横にファイル名が表示されます（`sales.csv` の `sales_2`）。
  - 2 つのファイルが同じビュー名を共有する場合、フォルダーが表示されます。
  - 行にカーソルを合わせるとフルパスが表示されます。
- **ダッシュボード** — 最近開いた `.dash` ダッシュボード。名前順に並ぶので、クリックしても行の位置は変わりません。
  - クリックすると、ファイルと同じようにタブとして開き直せます。
  - 同じ名前のダッシュボードが 2 つある場合は、その横にフォルダーが表示されます。同じファイルに 2 通りのパス表記（`E:\Proj` と `E:\proj`、または相対パスと絶対パス）で到達した場合は 1 つのエントリになり、1 つのタブで開きます。
  - ホバー時に表示される × を押すとリストから外れますが、ファイルや開いているタブには影響しません。
  - パスが存在しなくなったエントリはリストから削除されます。
- **指標** — これらのダッシュボードのそばに `model.ossie.yaml` があると表示されます。指標ごとに 1 行で、クリックするとクエリエディタにコンパイルされて実行されます。[セマンティック指標](metrics.md#sidebar) を参照してください。0.4.1 より新しい機能です。
- **S3** — [S3 を設定](s3.md)すると表示されます。遅延読み込みします。
- 各データベース、そのスキーマ、テーブルとビュー、列の順に並びます。ウィンドウを開いたときのデータベースが最初に来て、[その横にアタッチした](data-sources.md#attached-databases)データベースが続きます。そのようにアタッチした場合は `read-only` と表示されます。

テーブルには推定行数が表示されますが、ビューには表示されません。列のエントリには DuckDB のデータ型が表示されます。システムデータベースと `information_schema`、`pg_catalog`、`system` スキーマは非表示です。

ツリー上部の検索ボックス（**テーブルと列を検索**）は、名前に入力した文字列を含む行（大文字小文字は区別しません）と、その上の行だけを残します。名前に一致したテーブルはすべての列が残り、一致した列のために残されたテーブルは、その列を表示するように展開されます。ボックスをクリアするとツリー全体に戻ります。

### データベース {#databases}

開いているデータベースが最初に来て、次に[アタッチしたデータベース](data-sources.md#attached-databases)がそれぞれ独立したグループとして、名前にテーブル数とともに表示されます。

- アタッチしたデータベースは空でも表示されます。開いているデータベースは、テーブルがない間は表示されません。新しいインメモリセッションはこの状態で始まります。
- 名前の横の控えめなヒントに **read-only** と表示され、DuckDB でない場合はファイルの種類（**sqlite**）も表示されます。
- 名前にカーソルを合わせると、データベースファイルのパスが表示されます。

データベースを右クリックすると、デフォルトに設定したりデタッチしたりできます。[右クリックメニュー](#right-click-menu) を参照してください。

タブの横の更新ボタン（**スキーマを更新**）は、カタログと登録済みファイルのリストを再読み込みします。

## SELECT の生成

以下のクリックはすべて、アクティブなタブの**バッファー全体を置き換えます**。カーソル位置に挿入するのではありません。履歴のエントリをクリックした場合も同じです。大事な内容は、あちこちクリックする前に保存してください。

クリックするとアクティブなエディタに入力される内容:

| クリック | 生成される SQL |
| --- | --- |
| テーブルの再生ボタン | `SELECT * FROM db.schema.table LIMIT 100;` |
| 列のチェックボックス、またはその名前 | `SELECT col FROM db.schema.table LIMIT 100;` |
| 同じテーブルのさらに多くの列 | `SELECT a, b FROM db.schema.table LIMIT 100;` |
| データファイルである S3 オブジェクト | `SELECT * FROM 's3://bucket/key' LIMIT 100;` |

テーブル、ビュー、ローカルファイルの各列にはチェックボックスがあります。列にチェックを入れるか、その名前をクリックすると（チェックが入ります）、チェックした列から `SELECT` を組み立てます。順序はチェックした順ではなく、テーブルの列順です。最後のチェックを外すと `SELECT *` になります。チェックは 1 つのテーブルに属します。別のテーブルの列にチェックを入れると、そちらで最初からやり直しになります。

生成される SQL は 3 行にわたります（`SELECT …`、`FROM …`、`LIMIT 100;`）。テーブル名は、現在のデフォルトデータベースとスキーマで許される範囲で短く書かれます。デフォルトスキーマのテーブルなら `orders`、同じデータベースの別スキーマなら `main.orders`、それ以外は `database.schema.table` です。`snap` で **デフォルトデータベースとして使用** を選ぶと、そのテーブルのプレビューは `FROM orders` になります。最初のクエリが実行されるまでは、名前は完全修飾されます。

名前が二重引用符で囲まれるのは、英字、数字、アンダースコア以外の文字を含む場合だけです。

## 右クリックメニュー {#right-click-menu}

行のホバーボタンで提供されるコマンドは、すべて右クリックメニューにもあるので、ホバーせずにコマンドを見つけられます:

| 行 | メニュー |
| --- | --- |
| テーブルまたはビュー | SELECT クエリを生成、列の概要、名前をコピー、テーブル情報をコピー |
| 列 | SELECT クエリを生成、名前をコピー、データ型を変更…（テーブルの列のみ） |
| アタッチしたデータベース | デフォルトデータベースとして使用、データベースをデタッチ |
| S3 バケットリスト | バケットを更新 |
| 最近のダッシュボード | リストから削除 |
| ローカルファイル | SELECT クエリを生成、列の概要、名前をコピー、テーブル情報をコピー、ローカルファイルから削除 |

**名前をコピー** は名前そのもの（テーブル、列、ビューの名前だけ）をコピーします。データベースやスキーマで修飾されず、引用符も付きません。

**テーブル情報をコピー** はテーブル全体を Markdown としてコピーします。チャット、Issue、AI エージェントのプロンプトにそのまま貼り付けられます。クエリで使う名前、種類、サイズ、そしてすべての列とその型が含まれます:

```md
memory.main.orders (table, ~224 rows, 3 columns)

| column | type |
|---|---|
| date | DATE |
| channel | VARCHAR |
| revenue | DOUBLE |
```

**列の概要** はアクティブなエディタのテキストを `FROM <table>;` に置き換えて実行し、結果パネルの **概要** タブを開きます。テーブル全体のすべての列をまとめて要約します。NULL、個別値の数、範囲、値の小さなグラフです。[列の概要](results-and-charts.md#overview) を参照してください。

**デフォルトデータベースとして使用** はそのデータベースで `USE` を実行するので、データベースを指定しないテーブル名はそこで解決され、生成されるクエリは短くなります（上記参照）。すでにデフォルトになっているデータベースでは表示されません。

**データベースをデタッチ** はアタッチしたデータベースをデタッチして忘れるので、次回はアタッチされません。それがデフォルトだった場合は、先にセッションが別のデータベースに移ります。ファイルには何も変更が加えられません。開いているデータベース自体はデタッチできないため、そのメニューにこの項目はありません。詳しくは [アタッチしたデータベース](data-sources.md#attached-databases) を参照してください。

## 列のデータ型の変更

列の行にはデータ型のアクションがあります（ビューの列では使えないため、アタッチした CSV や Parquet の列を型変換することはできません）。これを選ぶとフリーテキストのダイアログが開き、現在の型が事前入力された状態で次が実行されます:

```sql
ALTER TABLE db.schema.table ALTER COLUMN col SET DATA TYPE <what you typed>
```

ここではテーブル名は常に完全修飾され、列名は必要な場合にだけ引用符で囲まれます。

選択肢の一覧も検証リストもありません。`DECIMAL(10,2)` のようなパラメーター付きの型も含め、任意の DuckDB の型文字列が使えます。無効な型はエラー通知として返ります。成功するとカタログが再読み込みされます。

列の名前変更や削除、列のコメントの編集はできません。

## 登録済みファイルの削除

ファイル行の **×** は確認を求めてからビューを削除し、登録を忘れます。**ディスク上のファイルには何も変更が加えられません。**

複数の登録をまとめて削除するには、**ローカルファイル** の下でそれらの行を選択します:

- macOS では **⌘-クリック**、Windows/Linux では **Ctrl-クリック** で、選択にファイルを 1 つ追加または削除します。
- **Shift-クリック** で連続した範囲を選択します。
- 選択したファイルの **×** をクリックするか、右クリックの削除アクションを使うと、選択した登録の削除を確認できます。メニューには削除されるファイルの数が表示されます。

これによりビューと登録が削除され、元のファイルはディスク上に残ります。この方法でファイルを選択しても、データベースのテーブルやダッシュボードのフィルターは選択されません。

## 拡張機能 {#extensions}

**拡張機能** タブには、エンジンが認識しているすべての DuckDB 拡張機能が一覧表示されます。読み込み済み、インストール済み、その他の順に、それぞれ名前順で並びます。

各行に表示される内容:

- 拡張機能の名前とステータスタグ（**読み込み済み**、**インストール済み**、**未インストール**）
- DuckDB による 1 行の説明
- バージョンと入手元（**組み込み**、またはインストール元のリポジトリ: `core`、`community`、または URL）

ステータスの意味:

| ステータス | 意味 |
| --- | --- |
| 読み込み済み | 現在の接続で有効です。関数、リーダー、型が今のクエリで使えます |
| インストール済み | このマシンにダウンロードされていますが、この接続では読み込まれていません |
| 未インストール | DuckDB は認識していますが、このマシンにはまだありません |

**組み込み** 拡張機能は DuckLocal にコンパイルされており、たとえば `parquet` と `json` はどちらも最初から読み込まれています。インストールや更新は行われません。

コミュニティ拡張機能も同じ方法でインストールします。0.4.1 以降、このタブは DuckDB のコアリポジトリだけでなくコミュニティリポジトリにも接続するため、`mssql`（SQL Server）のような拡張機能もアプリを離れずにインストールして読み込めます。その行のリポジトリのタグは `community` と表示されます。

各行には、その行に該当するアクションが表示されます:

| ボタン | 表示条件 | 実行内容 |
| --- | --- | --- |
| **インストール** | 未インストール | `INSTALL name` |
| **読み込み** | インストール済みで未読み込み | `LOAD name` |
| **更新** | リポジトリからインストール済み | `UPDATE EXTENSIONS (name)` |

- **インストール** と **更新** は DuckDB の拡張機能リポジトリからダウンロードするため、ネットワークが必要です。**読み込み** はインストール済みのファイルを読むだけで、ネットワークは不要です。
- インストールしても読み込まれません。その後で **読み込み** をクリックするか、`LOAD name` を実行してください。
- インストールした拡張機能はインストール済みのまま残ります。DuckDB 独自の拡張機能フォルダーにある、ディスク上のファイルだからです。読み込みは現在の接続の間だけ有効です。
- そのフォルダーは DuckDB のリリースごとに分かれています（`~/.duckdb/extensions/v2.0.0/…`）。更新によって DuckLocal が新しい DuckDB リリースに移ると（0.3.0 が DuckDB 2.0 に移ったときのように）、以前使っていた拡張機能は再度インストールするまで **未インストール** と表示されます。
- アクションは 1 つずつ実行され、その間は他のボタンが無効になります。通知には *インストールしました…*、*読み込みました…*、*更新しました…* のいずれか、または失敗した理由が表示されます。
- 読み込みまたは更新の後、スキーマツリーが再読み込みされます。拡張機能がテーブルや関数を伴ってくる場合があるためです。

このリストは、タブを開くたび、各アクションの後、タブを開いたまま接続が変わったとき、そしてタブの横の更新ボタン（**拡張機能を更新**）をクリックしたときに、`duckdb_extensions()` から読み取られます。そのため、別の方法で読み込まれた拡張機能（クエリタブで入力した `LOAD` や、DuckDB 自身による読み込み）も表示されます。

v0.2.1 以降、クエリが必要としたときに不足している拡張機能を、ウィンドウも CLI も自動ではダウンロードしません。**拡張機能** で明示的にインストールするか、`INSTALL name` を実行してください。このマシンにすでにインストールされている拡張機能は、従来どおり自動で読み込めます。

### DuckDB UI を開く {#duckdb-ui}

[DuckDB UI](https://duckdb.org/2025/03/12/duckdb-ui) は、MotherDuck が開発した DuckDB 自身のブラウザーノートブックで、他の拡張機能と同じように扱えるため、DuckLocal の中でも動作します:

1. **拡張機能** タブで `ui` の行の **インストール** をクリックし、次に **読み込み** をクリックします。
2. クエリタブで次を実行します:

   ```sql
   CALL start_ui();
   ```

   ブラウザーが `http://localhost:4213` で UI を開きます。ブラウザーを開かずにサーバーを起動するには、代わりに `CALL start_ui_server();` を実行します。

![ui 拡張機能を読み込んだ状態の拡張機能タブ](../assets/duckdb-ui.png)

UI は起動元の DuckDB インスタンス（ここでは DuckLocal のもの）で動作します。いくつか注意点があります:

- **ネットワークが必要です。** `ui` のインストールは、他の拡張機能と同様にダウンロードを伴います。また起動のたびに、拡張機能のローカルサーバーが `https://ui.duckdb.org` から UI 自身のファイルを取得します。クエリとデータは引き続きローカルで実行されます。
- **DuckLocal が終了するまで有効です。** DuckLocal を終了すると DuckDB インスタンスが閉じられ、サーバーも一緒に終了します。`CALL stop_ui_server();` で早めに停止できます。
- **ノートブックは DuckLocal ではなく拡張機能が保存します。** 保存先は `~/.duckdb/extension_data/ui/` です。DuckLocal のクエリ履歴には、UI で実行した内容は含まれません。
- **読み取り専用のデータベースでは直接実行できません。** 代わりにノートブックから `ATTACH '…' (READ_ONLY)` でそのデータベースをアタッチしてください。

[DuckDB UI と DuckLocal の比較](https://ducklocal.app/blog/duckdb-ui-vs-ducklocal/) では、両者を比較し、どちらをいつ使うかを説明しています。

## クエリ履歴 {#query-history}

すべての実行が、成功も失敗も記録されます。ローカル時刻のタイムスタンプ、ミリ秒単位の実行時間、行数（DML の場合は影響を受けた行数）、失敗した場合はエラーテキストが含まれます。失敗したエントリは赤字で *失敗* タグ付きで表示されます。

リストには最新の **200** 件が表示されます。行をクリックすると、アクティブなエディタがその SQL で埋められ、フォーカスされます（それまでの内容は置き換えられます）。

保持ポリシーも削除処理もありません。履歴テーブルは無制限に増え続け、UI は単に直近 200 件を表示します。検索、フィルター、エクスポートもなく、インターフェースからエントリを削除する方法もありません。

履歴は開いているデータベースではなく DuckLocal 自身のデータベースファイルに保存されるため、データベースを切り替えたりワークスペースを失ったりしても残ります。保存場所は [設定とアプリデータ](settings-and-data.md) を参照してください。
