データソース
DuckLocal はファイルをメモリ上の DuckDB 接続内のビューに変えます。データベースファイルを開いている場合は、そのファイル内のビューになります。他のデータベースをその隣に置くこともできます。設定するものは何もありません。ファイルから SQL、グラフ、エクスポートへ進む簡潔な道筋については、ローカルデータ分析のワークフロー を参照してください。
データを開く方法
どれも同じ解決ルールを通ります。
- コマンドラインのパス —
ducklocal ./logs/ billing.parquet - タイトルバーの 開く メニュー:ファイルを開く、フォルダーを開く、または パスまたは glob を入力。最後の項目は データを開く ダイアログを開き、 入力したパス、またはネイティブのピッカーで選んだパスを扱います
- ウィンドウのどこかにファイルやフォルダーをドロップする
- Mac では、Finder が DuckLocal に渡すファイル — Finder から開く を参照
開いているデータベースを置き換えるのではなく隣にデータベースを追加するには、 開く → データベースをアタッチ… を使います — アタッチしたデータベース を参照してください。
macOS では、Finder で Parquet ファイルや DuckDB ファイルをダブルクリックして開けます。また、DuckLocal を起動せずにスペースキーを押すと、Quick Look で Parquet、DuckDB、CSV、TSV、JSON Lines ファイルの先頭の行をプレビューできます。
対応するファイル形式
拡張子は大文字と小文字を区別せずに照合されます。
| 拡張子 | 読み込み方法 |
|---|---|
.csv、.tsv、.txt | read_csv_auto ビュー |
.parquet | read_parquet ビュー |
.json、.ndjson、.jsonl | read_json_auto ビュー |
.xlsx、.xls、.xlsb、.ods | シートごとにテーブルとしてインポート |
.json.gz や .csv.gz のような gzip 圧縮されたテキストもデータファイルとして数えられ、schema、source のブロックやファイルをアタッチするときに扱われます。logs.json.gz は logs という名前のビューになります。0.4.0 より前の ducklocal schema は、そのようなファイルをデータベースとして試していました。古いバージョンでは、SQL で read_json または read_csv を使って読んでください。
それ以外はデータファイルではありません — データベースファイル を参照してください。
ワークブックだけはビューではなく テーブル になり、しかも すべてのシート を インポートする唯一の形式です。最初のシートはファイルのステム(拡張子を除いた ファイル名)を名前として使い、それ以外のシートは {stem}_{sheet name} という名前に なります。空のシートはスキップされます。列の型はセルから推論されます — 整数は BIGINT、 整数と浮動小数点の混在は DOUBLE、日付は TIMESTAMP、混在していたり 認識できないものは VARCHAR になり、空のセルは NULL としてインポートされます。
フォルダーとパターン
ディレクトリ は再帰的に走査され、内部のすべてのデータファイルが ビューになります。走査には 2 つのルールが適用されます。
- 隠しエントリ(
.で始まる名前)はスキップされ、そのサブツリーには 入りません。 - シンボリックリンクはたどりません。ツリーを上へさかのぼるリンクをたどると 終了しなくなり、リンク先のディレクトリは通常、実際に存在する場所で 走査されるためです。
ファイルはソートされた順序でアタッチされるため、同じフォルダーからは常に 同じワークスペースが生まれます。
パターン には *(任意の長さの文字列)と ?(ちょうど 1 文字)を使えます。 照合はパスの構成要素ごとにファイルシステムに対して行われるため、パターンは ディレクトリをまたげます。
ducklocal './data/2026-0*/*.parquet'エスケープ文字はありません。** は特別ではなく、単一の * と同じように動作し、 再帰しません。ディレクトリに一致するパターンはそのディレクトリをスキップします。 アタッチされるのはファイルだけです。ここでも隠しエントリはスキップされます。
クォートされていないパターンは、DuckLocal が受け取る前にシェルによって展開されます。 それで問題ありません。パターンをクォートするのは、DuckLocal に展開させたいときだけです。 たとえば、シェルが一致を見つけられず、エラーになってしまうような場合です。
一度に多数の CSV ファイル
DuckLocal がアタッチする各ファイルは、それぞれ独自にスニッフィングされたスキーマを持つ 独立したビューになるため、内容が食い違う 2 つの CSV が互いを壊すことはありません。 落とし穴が現れるのは、1 つの SQL の読み込みが多数のファイルにまたがるときです。
SELECT * FROM read_csv('data/*.csv', union_by_name = true)型のスニッフィングはファイル間で食い違うことがあります。 リーダーはサンプルから列の 型を推論します。どこでも数値だった列が、あるファイルで
'NULL'という 文字列を 1 つ含んでいると、読み込み全体が変換エラーで失敗します。また、SELECTリスト内のキャストは遅すぎます — 読み込み自体がエラーになるからです。 代わりにすべての列をテキストとして読み、SQL でキャストしてください。sqlSELECT try_cast(amount AS DOUBLE) AS amount FROM read_csv('data/*.csv', union_by_name = true, all_varchar = true)union_by_name = trueを使うと、列の集合が異なるファイルも許容されます。文字列
'NULL'はNULLではありません。 CSV 内のリテラル'NULL'(または'N/A'、'null')はただのテキストなので、WHERE amount IS NOT NULLでは 除外できません。NULLIF(amount, 'NULL')かWHERE amount <> 'NULL'を使ってください。
2 つの修正は組み合わせられます:try_cast(NULLIF(amount, 'NULL') AS DOUBLE)。
データベースファイル
DuckLocal が同時に持てる メインデータベース は 1 つだけです。メモリ上か、開いた DuckDB ファイルです。データファイルはメインデータベース内のビューになります。 他のデータベースをその隣にアタッチする こともできます。
存在する パスでデータファイルではないものは、ビューとしてアタッチされるのではなく、 メインデータベースとして開かれます。拡張子は関係ありません。 .db、.duckdb、さらには .md のパスもデータベースとして扱われ、実際に開けるかどうかは DuckDB が判断します。
知っておく価値のある結果がいくつかあります。
- 新しいデータベースは「データを開く」ダイアログからのみ作成されます。
.duckdbで 終わる存在しないパスを入力すると、DuckLocal は不足している親フォルダーとともに データベースを作成します。それ以外の場所 — コマンドライン、ピッカー、ドロップ、Finder — では、 存在しないパスはFile not foundと報告されます。 - データベースを開くとメインのデータベースが置き換わります。 登録済みのファイルと アタッチしたデータベースは、新しい接続に再度アタッチされます。S3 の 認証情報は引き継がれないため、S3 を再度設定してください。
- ファイルを開けない場合、DuckLocal はその理由を伝えます (後述)。起動時は、起動に失敗するのではなく メモリ上のワークスペースにフォールバックします。実行中は、 それまでのワークスペースがそのまま維持されます。
- すでにアタッチされているファイル をメインデータベースの隣から開く場合、 まずデタッチされ、次にメインデータベースとして開かれます。そのオープンに失敗した場合は、 アタッチが元に戻ります。すでにメインデータベースであるファイルを開いた場合は、 それが再利用されます。
データベースファイルを開いている間にデータファイルをアタッチすると、 それらのビューがそのデータベースファイルに書き込まれ、セッション内だけでなく そこに永続化されます。
データベースを開けないとき
DuckDB がファイルを拒否したとき、DuckLocal はファイルの先頭バイトを自分で読み、 それが失敗を説明するものであれば、理由と対処法を DuckDB 自身の メッセージの上に表示します。DuckDB のメッセージは正確なエラーとしてその下に残ります。 説明はインターフェースの言語で表示されます。
| ファイルの種類 | DuckLocal が伝える内容 |
|---|---|
| DuckLocal に組み込まれたものより 新しい DuckDB で書かれた DuckDB ファイル | 両方のバージョンと、DuckLocal が読める形式にファイルをコピーするために新しい DuckDB で実行する SQL(後述) |
| v0.9 以前 の DuckDB ファイル | そのファイルを書いた DuckDB で EXPORT DATABASE 'dir' を実行し、次に DuckLocal で IMPORT DATABASE 'dir' を実行してください |
| SQLite データベース | DuckDB ファイルではありません。代わりにアタッチしてください — データベースをアタッチ…、または INSTALL sqlite; ATTACH '…' (TYPE sqlite); |
| DuckDB ファイルではない その他のもの | 代わりに CSV、Parquet、JSON、Excel ファイルをデータファイルとして開いてください |
新しい DuckDB のファイルの場合、メッセージにはファイルのパスと DuckLocal の DuckDB バージョンが埋め込まれます。ファイルを作成した DuckDB でそれを実行し、次に compat.duckdb を開いてください。
ATTACH '/path/to/file.duckdb' AS src (READ_ONLY);
ATTACH 'compat.duckdb' AS dst (STORAGE_VERSION 'v2.0.0');
COPY FROM DATABASE src TO dst;DuckDB v1.2 より前に書かれたファイルには、どのリリースで作成されたかが記録されていません。 その他の失敗 — 別のプログラムがロックしているファイル、読み取り権限のないファイル — は、 DuckDB のメッセージだけが表示されます。 トラブルシューティング を参照してください。
どの DuckDB がデータベースを読めるか
データベースファイルを開いているとき、ステータスバーにそのパスが表示されます。その上にマウスを置くと、 ファイルのストレージ形式 — それを読める最も古い DuckDB、たとえば ストレージ形式:DuckDB v1.0.0+ で読み取り可能 — と、ファイルに記録があれば 作成したリリース(DuckDB v1.4.3 で作成)が表示されます。古い DuckDB を使っている人に ファイルを渡す前に、これを確認してください。
DuckLocal は DuckDB 2.0 を実行しますが、作成するデータベースファイルは DuckDB 1.x が 書いた形式(DuckDB v1.0.0+ で読み取り可能)で書き込まれるため、DuckDB 1.x 上の duckdb CLI、Python、DBeaver でも開けます。他のプログラムが DuckDB 2.0 独自の 形式(v2.0.0+)で書いたファイルも開けますが、その形式のまま維持されます。1.x では読めません。
アタッチしたデータベース
メインデータベースの隣に別の DuckDB ファイルや SQLite ファイルをアタッチして、 それらをまたいでクエリできます — たとえば、今日のデータの隣にスナップショットを置くような場合です。
- タイトルバーの 開く メニューを開き、データベースをアタッチ… を選びます。
- パスを入力するか、参照 をクリックしてファイルを選びます。
- ファイルを変更するつもりがない限り、読み取り専用 はチェックしたままにします。 デフォルトでチェックされています。
- アタッチ をクリックします。
データベースにはファイル名から エイリアス が付き、そのテーブルを alias.table(または alias.schema.table)としてクエリできます。
-- snap-2026-10-01.duckdb attached as snap_2026_10_01
SELECT t.id, t.amount, s.amount AS amount_last_week
FROM orders t
JOIN snap_2026_10_01.orders s USING (id);エイリアスの作り方:
- ASCII の英字または数字ではないすべての文字を
_に置き換えた ファイルステム。 - 英字で始まらない場合は前に
db_を付けます:2026-10 logs.duckdbはdb_2026_10_logsになります。 - 名前がすでに使われている場合はカウンター:
snap、次にsnap_2。mainは決して 使われません。 - 後で同じファイルを再度アタッチすると、以前と同じエイリアスが割り当てられるため、 それに対して書かれた SQL はそのまま動作します。
詳細:
- SQLite ファイル は内容で識別され、DuckDB の
sqlite拡張機能を通じて アタッチされます。 - 読み取り専用のチェックを外すと、書き込み用としてファイルがアタッチされます。存在しない DuckDB のパスは、そのとき新しい空のデータベースとして作成されます。読み取り専用では、 代わりにアタッチが失敗します。
- 同じファイルは 2 回アタッチされません。 すでに開いているファイル — メインデータベースとしてでもアタッチメントとしてでも — をアタッチしようとすると、 このデータベースはすでに開いています:… と表示されます。
サイドバーで
すべてのデータベースがスキーマツリーに表示されます。メインのものもアタッチしたものも、 空のデータベースも含まれます。データベースには、該当する場合に名前の横へ 読み取り専用 または sqlite が表示され、ツールチップにそのファイルが表示されます。
データベースを右クリックすると次の操作ができます。
- デフォルトデータベースとして使用 —
USEを実行するため、データベース名を省略した テーブル名はそこで解決されます。ステータスバーに現在の解決先が表示されます。 - データベースをデタッチ — デタッチして記憶から削除するため、次回は 復元されません。デフォルトデータベースだった場合は、セッションがまずメイン データベースに戻ります。ファイル自体は変更されません。
このメニューの残りの項目は スキーマブラウザーと履歴 で説明しています。
接続をまたいで保持される
アタッチしたデータベースは、エイリアスと読み取り専用設定とともに DuckLocal 自身の 履歴データベースに保存され、新しい接続ごとに再アタッチされます。 次回の起動時、別のデータベースを開いた後、そして メモリ内データベースを 新規作成 の後です。
- ファイルが 見つからない データベースは静かにスキップされます。登録は 保持されるため、ファイルが戻れば復元されます — DuckLocal が代わりに 空のデータベースを作成することは決してありません。
- すでに開いている データベースは、メインデータベースであれそれ以外であれ、 2 回目はアタッチされません。
- 新しいメインデータベースにそのエイリアスのデータベースがすでにある場合、DuckLocal は アタッチできませんでした:名前 … は開いているデータベース内で使用されています。 と表示します。
Finder から開く
Mac では、Finder から直接 DuckLocal にファイルを渡せます。
| ファイル | ダブルクリック | 「このアプリケーションで開く」、または Dock アイコンへのドロップ |
|---|---|---|
.parquet | DuckLocal で開く | 可 |
.duckdb、.ddb | DuckLocal で開く | 可 |
.dash | DuckLocal で開く | 可 |
.csv、.tsv、.json、.jsonl、.ndjson、.xlsx、.xls | すでにそれらを開くアプリ(Numbers、Excel、テキストエディタ)のまま | 可 |
DuckLocal は、Mac 上で他に名乗り出るアプリがない形式についてのみ、自分自身をデフォルトとして 登録します。他のアプリがすでに Parquet や DuckDB ファイルを引き継いでいる場合は、 このアプリケーションで開く で DuckLocal を選ぶか、Finder の 情報を見る → このアプリケーションで開く → すべてを変更… を使ってデフォルトに設定してください。
Finder から渡されたファイルは、ウィンドウへのドロップとまったく同じように扱われます。データファイルは 現在のワークスペース内のビューになり、データベースファイルはメイン データベースとして開かれ、.dash ファイルは ダッシュボード タブとして開かれます。 DuckLocal が実行中でない場合は、まず起動し、自身の起動処理が終わってから ファイルを開きます。
Quick Look プレビュー
Mac では、Finder でデータファイルを選択して スペース を押すと、何も開かずにその列と 先頭の行を確認できます。プレビューは DuckLocal.app 内に同梱されており、 別途インストールするものはありません。アプリと同様に macOS 12 以降が必要です。
| ファイル | プレビューが表示する内容 |
|---|---|
.parquet | 列と型、先頭 50 行、そしてファイルのフッターから行数、行グループ、圧縮方式、書き込み元 |
.duckdb、.ddb | テーブル数、ストレージ形式(DuckDB … で読み取り可能)、および最大 5 つのテーブル(それぞれ推定行数と先頭 50 行付き) |
.csv、.tsv | スニッフィングされた型を持つ列と先頭 50 行 — 生のテキストではなくテーブルとして |
.jsonl、.ndjson | 列と先頭 50 行 |
プレーンな .json ファイルと Excel ファイルは、macOS 標準のプレビューに任されます。
プレビューが行うことと行わないこと:
- 書き込みは一切しません。データベースは読み取り専用でアタッチされます。
- ファイル全体をスキャンしません。行は
LIMITで取得し、行数が表示されるのは 形式が行数を保持している場合(Parquet のフッター、データベースの推定値)だけです。 - 何もダウンロードしません。DuckDB の拡張機能はインストールも読み込みもされません。
- 200 文字を超えるセルは切り捨てられます。ページのテキストは英語です。
- 読み取れないファイルには、その理由を示すページが表示されます。
スペースキーを押しても DuckLocal のプレビューが表示されない場合:
- DuckLocal が アプリケーション フォルダーにあることを確認し、一度起動します。macOS は アプリを初めて認識したときにプレビューを登録します。
- ターミナルで Quick Look をリセットします:
qlmanage -r。その後もう一度試してください。 - システム設定の拡張機能設定の Quick Look で DuckLocal Preview がオンに なっていることを確認します。
命名
ファイルのビューはファイルステムにちなんで命名され、有効な識別子になるように 整形されます。その名前が接続内ですでに使われている場合、DuckLocal はカウンターを付けます: events、次に events_2、events_3。したがって、異なるディレクトリにある同じステムを 持つ 2 つのファイルは、別々のビューになります。
重複の検出は書かれたとおりのパス文字列で行われるため、./a.csv と a.csv は 2 つの異なるファイルとして扱われます。
制限
- 1 回の開く要求あたり 256 個のデータファイル。 この上限はフォルダーごとではなく、 1 回の要求内のすべてのパスを合わせたものに適用されます — 誤ってホームディレクトリを ドロップしたときに接続が数分間占有されないようにするためのものです。上限に 達すると、DuckLocal はその旨を伝え、最初の 256 ファイルをアタッチします。
- 前回のセッションから起動時に再アタッチされるファイルは、この上限の 対象外です。
登録済みソースの管理
登録済みのファイルはサイドバーの ローカルファイル グループに表示され、それぞれ ビュー名、ファイル名、行数が付きます。ファイルを選択すると、そのための SELECT 文が生成されます。
ファイル行の × をクリックすると、確認ダイアログの後に削除されます。削除は ビューを落として登録を忘れるものであり、元のファイルは変更されません。
スキーマを更新 はカタログと登録済みファイルを再読み込みします。
記憶される内容
登録済みファイルのリスト — そのパス、ビュー名、種類 — は DuckLocal 自身の 履歴データベースに保存され、次回の起動時に再アタッチされるため、終了時の ワークスペースがそのまま戻ります。アタッチしたデータベース も同様です。 メインデータベースのファイルは記憶 されません。データベースを指定しない限り、 起動のたびにメモリ上から始まります。
ディスク上の保存場所については 設定とアプリデータ を参照してください。
