# はじめに

> macOS、Windows、Linux に DuckLocal をインストールし、ducklocal CLI を追加して CSV、Parquet、JSON、Excel ファイルを開き、最初の DuckDB SQL クエリを実行する方法を説明します。

Source: https://ducklocal.app/docs/ja/getting-started

DuckLocal は、自分のマシン上にあるデータファイルに SQL で問い合わせるための
デスクトップアプリです。動かすサーバーも、設定する接続も、アカウントもありません。
ファイルを指定すれば、すぐにクエリを始められます。このページでは、ダウンロードから
最初の結果が得られるまでを約 5 分で案内します。

## 1. インストール {#install}

DuckLocal は macOS、Windows、Linux で動作します。以下のリンクから `dl.ducklocal.app` の最新リリースをダウンロードできます。同じファイルとリリースノートは [GitHub](https://github.com/JetSquirrel/DuckLocal/releases/latest) でも公開されています。

このガイドは、2026 年 11 月 15 日にリリースされた [v0.4.1](https://github.com/JetSquirrel/DuckLocal/releases/tag/v0.4.1) に合わせて更新されています。バージョン 0.4.0 では[エージェントワークフロー](agent-workflows.md)が追加されました。制限付き SQL、ウィンドウへの確認済みハンドオフ、ダッシュボードの提案、分析記録、持ち運べるプロジェクトが含まれます。バージョン 0.4.1 では、複数選択できるフィルター、ダッシュボードのタイムゾーンとタイムライングラフ、共有する SQL を 1 か所にまとめる `view` ブロック、拡張機能タブでの `mssql` などのコミュニティ拡張機能、インメモリデータベースで作ったテーブルを保存するかどうかの確認が追加されました。0.3.0 より前のバージョンから更新する場合は、拡張機能を再インストールしてください。そのリリースで DuckLocal は DuckDB 2.0 に移行しました。

### macOS

**Apple silicon（M1 以降）上の macOS 12 以降**が必要です。

1. [`ducklocal-macos-arm64.dmg`](https://dl.ducklocal.app/latest/ducklocal-macos-arm64.dmg) をダウンロードします。
2. 開いて、**DuckLocal** を **アプリケーション** にドラッグします。
3. アプリケーションまたは Spotlight から DuckLocal を起動します。

ディスクイメージは Apple による署名と公証が済んでいるため、Gatekeeper を
回避する操作をしなくてもそのまま開けます。

### Windows

**64 ビットの Windows 10 以降**が必要です。

1. [`ducklocal-windows-x86_64.zip`](https://dl.ducklocal.app/latest/ducklocal-windows-x86_64.zip) をダウンロードして解凍します。
2. 解凍したフォルダーの `ducklocal.exe` を実行します。このビルドはまだ
   コード署名されていないため、初回起動時に **Windows によって PC が保護されました**
   と表示されることがあります。**詳細情報** を選び、**実行** をクリックしてください。

### Linux

**x86_64** のシステムと **glibc 2.35 以降**（Ubuntu 22.04、Debian 12、Fedora 36 以降）、
および Vulkan をサポートするグラフィックスドライバーが必要です。

```bash
curl -LO https://dl.ducklocal.app/latest/ducklocal-linux-x86_64.tar.gz
tar -xzf ducklocal-linux-x86_64.tar.gz
./ducklocal-linux-x86_64/ducklocal
```

::: details 代わりにソースからビルドする
Rust stable 1.85.1 以降と C++ ツールチェーン（Xcode Command Line Tools）が必要です。
DuckDB は同梱のソースからコンパイルされるため、最初のビルドには数分と数 GB の
ディスク容量がかかります。

```bash
git clone https://github.com/JetSquirrel/DuckLocal
cd DuckLocal
cargo build --release
./target/release/ducklocal
```

バイナリは `./target/release/ducklocal` です。このガイドで `ducklocal` と書かれている
箇所はこれに置き換えてください。`.app` のパッケージ化については[開発](development.md)を参照してください。
:::

## 2. `ducklocal` コマンドを追加する（任意） {#add-command}

アプリ内の機能はすべてターミナルなしで使えます。さらにコマンドラインからデータを
開きたい場合や、AI エージェントに [CLI](cli.md) でデータを分析させたい場合は、
アプリからコマンドを追加します:

1. タイトルバーのロボットボタンをクリックするか、メニューバーから
   **DuckLocal → コマンドラインと AI…** を選びます。
2. **コマンドをインストール** をクリックします。Mac では、`/usr/local/bin` に書き込むために
   システムがパスワードを求めます。
3. 新しいターミナルを開いて確認します: `ducklocal --version`。

このコマンドはアプリへのリンクなので、DuckLocal を更新すればコマンドも更新されます。
更新するには、ステータスバーの右端に表示されるバージョンをクリックします。新しい
リリースがダウンロードされ、再起動時にインストールされます（[アップデートの確認](settings-and-data.md#update-check)を参照）。Mac では `/usr/local/bin`、Linux では `~/.local/bin` に配置されます。
Windows ではアプリのフォルダーが `Path` に追加されます。

同じダイアログで、**Claude Code に追加** をクリックすると DuckLocal のスキルがインストールされ、
Claude Code がファイルへのクエリ方法を理解できるようになります。**概要をコピー** は短い説明を
コピーするので、ほかの AI エージェントに貼り付けて使えます。
詳しくは [AI CLI と公式スキル](cli.md#install-the-official-skill)を参照してください。

::: details 手動で追加する
```bash
sudo mkdir -p /usr/local/bin
sudo ln -sf /Applications/DuckLocal.app/Contents/MacOS/ducklocal /usr/local/bin/ducklocal
```

削除するには `sudo rm /usr/local/bin/ducklocal` を実行します。Linux では解凍した
バイナリを `~/.local/bin` にリンクし、Windows では解凍したフォルダーを `Path` に追加します。
:::

## 3. データを開く

初回起動時には、アヒルが案内する短いガイドが表示されます。AI エージェントの接続、
データを開くこと、サイドバー、クエリの実行、結果の読み方などを順に紹介します。
**スキップ** をクリックすればいつでも閉じられます。もう一度見るには、Mac では
**DuckLocal** メニューの **ガイドを表示** を選ぶか、ステータスバー右端のバージョンの
右クリックメニューから選びます。

その背後にあるのが **データをここにドロップ** という画面です。ここでは次のいずれかの方法で
データを取り込めます:

- CSV、TSV、Parquet、JSON、Excel ファイル、またはフォルダー全体を
  ウィンドウに**ドラッグ**します。
- **ファイルを開く** または **フォルダーを開く** をクリックします。
- Mac では、Finder で `.parquet` または `.duckdb` ファイルを**ダブルクリック**するか、
  CSV、JSON、Excel ファイルの場合は **このアプリケーションで開く** から DuckLocal を選びます。
  [Finder から開く](data-sources.md#open-from-finder)を参照してください。
- ターミナルからはパスを指定します:

  ```bash
  ducklocal ./sales.csv         # 1 つのファイル
  ducklocal ./logs/             # フォルダー以下のすべてのデータファイルを再帰的に
  ducklocal './data/*.parquet'  # パターン。シェルに先に展開されないよう引用符で囲む
  ducklocal warehouse.duckdb    # 既存の DuckDB データベース
  ```

各ファイルはファイル名にちなんだ名前のビューになります（`sales.csv` は `sales` に）。
サイドバーの **ローカルファイル** に列と行数とともに表示されます。DuckLocal はファイルを
その場所のまま読み込み、コピーもアップロードもしません。

開いたファイルは記憶されるので、次回起動時も同じワークスペースから始まります。
形式、フォルダー、パターン、データベースの詳細は[データソース](data-sources.md)にあります。

Mac では、ファイルを開く前に中身をのぞくこともできます。Finder でファイルを選択して
**スペース** キーを押してください。DuckLocal の[クイックルックのプレビュー](data-sources.md#quick-look)が
Parquet、DuckDB、CSV、TSV、JSON Lines ファイルの列と先頭の行を表示します。

::: tip 手元にデータがない場合は？
[最初の 10 分のチュートリアル](tutorial.md)で、小さなサンプルファイルを使いながら
手順を追って確認できます。
:::

## 4. クエリを実行する

**新しいクエリ** をクリックします（データを開いたときはエディターが自動的に表示されます）。
SQL を入力して **⌘↵**（Cmd+Enter。Windows と Linux では Ctrl+Enter）を押します:

```sql
SELECT * FROM sales LIMIT 20;
```

`sales` の部分は、サイドバーにある任意のビュー名に置き換えてください。

結果はエディターの下のパネルに表示されます。**グラフ** に切り替えれば概要を素早く把握でき、
CSV や Parquet としてエクスポートもできます。エディター上部のツールバーには
**実行**、**整形**、**EXPLAIN** があります。

覚えておきたいショートカットがあります。サイドバーでテーブルの横の再生ボタンをクリックすると
`SELECT * … LIMIT 100` がすぐに入り、列名をクリックするとその列だけを選択できます。

## 次に読むもの

- [最初の 10 分](tutorial.md) — サンプルデータを使ったガイドツアー
- [データソース](data-sources.md) — 形式、フォルダー、パターン、データベース、Finder とクイックルック
- [SQL エディター](sql-editor.md) — タブ、ショートカット、自動補完、EXPLAIN
- [結果とグラフ](results-and-charts.md) — フィルタリング、エクスポート、グラフ、列の概要
- [ダッシュボード（.dash）](dashboards.md) — テキストファイルとしてのダッシュボードと、AI エージェントによるレビュー
- [トラブルシューティング](troubleshooting.md) — 動作がおかしいとき
