DuckDBからExcelファイルを読み書きしてみた
2025.03.08DuckDB 1.2から、DuckDB公式のExcelコアエクステンションが大幅に強化され、Excelファイルの読み書きが格段に簡単になりました。本記事では、この新しいExcelエクステンションの基本的な使い方を解説します。
DuckDB CLIを起動して、Excelファイルに対して SELECT するだけです。
$ duckdb
v1.2.1 8e52ec4395
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
D SELECT * FROM 'test.xlsx';
┌─────────┬────────┐
│ name │ num │
│ varchar │ double │
├─────────┼────────┤
│ foo │ 1.0 │
│ bar │ 3.5 │
└─────────┴────────┘
アップデート内容
従来のExcelエクステンションは機能が限定的であったため、Excelファイルの操作には依存関係があって重厚なSpatial エクステンションが利用されていました。
DuckDB1.2からはExcelエクステンションが強化され、さらに、コアエクステンションであるため、明示的なインストールやロードなしでシームレスにExcelファイルを操作できるようになりました。
Prior to DuckDB 1.2, Excel files were only supported by the spatial extension, which is a heavyweight extension with several dependencies. Starting with 1.2, the excel extension – which was previously limited to computing a few formulas – can read and write Excel sheets.
https://duckdb.org/2025/03/06/gems-of-duckdb-1-2#excel-extension
Excelファイルの読み取り
Excelファイルを読み込むには、SQL の FROM に Excel ファイル(.xlsx) を指定するだけです。
ただし、多くの場合は、Excelファイルのシート名等も指定したいでしょう。
そのような場合は、 read_xlsx 関数で各種引数を渡します。
D SELECT *
FROM read_xlsx('test.xlsx', header = true, sheet = 'シート', range = 'A1:C3');
┌─────────┬────────┬────────────┐
│ 名前 │ 数 │ 日付 │
│ varchar │ double │ date │
├─────────┼────────┼────────────┤
│ 鈴木 │ 1.0 │ 2025-01-22 │
│ 山本 │ 3.5 │ 2025-03-06 │
└─────────┴────────┴────────────┘
sheet 引数を除外すると、先頭のシートを利用します。
また、セルを範囲指定する場合、range = 'a1:b3' というように小文字を利用すると、DuckDBは有効な範囲として認識せず、以下のような Binder Error が発生します。
大文字で A1:B3 のように記述してください。
Binder Error:
Invalid range 'a1:b3' specified
オプション一覧は以下の通りです
| オプション | タイプ | デフォルト | 概要 |
|---|---|---|---|
| header | BOOLEAN | 自動検出 | 1行目をヘッダー行として扱うか |
| sheet | VARCHAR | 自動検出 | シート名 |
| all_varchar | BOOLEAN | FALSE | Whether to read all cells as containing VARCHARs. |
| ignore_errors | BOOLEAN | FALSE | エラーセルを NULL で置き換える |
| range | VARCHAR | 自動検出 | セルの読み取り範囲(例:A1:B2) |
| stop_at_empty | BOOLEAN | 自動検出 | 空白行まで読み込む。読み取り範囲を指定する場合は、FALSE 扱い |
| empty_as_varchar | BOOLEAN | FALSE | 空白セルの型をDOUBLEではなくVARCHARとするか |
Excelファイルの書き込み
Excel ファイルに書き込むには COPY ステートメント でフォーマットに xlsx を指定するだけです。
書き込み用のデータを用意します
D CREATE TABLE t AS FROM read_xlsx('test.xlsx', header = true, sheet = 'シート');
D SELECT * FROM t;
┌─────────┬────────┬────────────┐
│ 名前 │ 数 │ 日付 │
│ varchar │ double │ date │
├─────────┼────────┼────────────┤
│ 鈴木 │ 1.0 │ 2025-01-22 │
│ 山本 │ 3.5 │ 2025-03-06 │
└─────────┴────────┴────────────┘
このテーブル t を foo.xlsx に書き込みます
D COPY t TO 'foo.xlsx' WITH (FORMAT 'xlsx', HEADER true, SHEET 'テスト');
D SELECT * FROM read_xlsx('foo.xlsx', header = true, sheet = 'テスト');
┌─────────┬────────┬────────────┐
│ 名前 │ 数 │ 日付 │
│ varchar │ double │ date │
├─────────┼────────┼────────────┤
│ 鈴木 │ 1.0 │ 2025-01-22 │
│ 山本 │ 3.5 │ 2025-03-06 │
└─────────┴────────┴────────────┘
同じデータを復元できています。
オプション一覧は以下の通りです
| オプション | タイプ | デフォルト | 概要 |
|---|---|---|---|
| header | BOOLEAN | FALSE | ヘッダー行を出力するか |
| sheet | VARCHAR | Sheet1 | シート名 |
| sheet_row_limit | INTEGER | 1048576 | 書き込む最大行 |
ファイル全体が書き込んだ1シートだけのExcelデータで上書きされます。 つまり、既存のExcelファイルにシートを追加したり、特定のシートだけを更新したりといった部分的な編集はできません。
エクステンションを手動インストール
Excelエクステンションはコアエクステンションのため、オンデマンドで自動的にロードされます(autoloading)。
手動でインストールするには、以下のコマンドを実行します。
INSTALL excel;
LOAD excel;
エクステンションを確認しましょう
$ tree $HOME/.duckdb
/Users/user/.duckdb
├── cli
│ ├── 1.2.1
│ │ └── duckdb
│ └── latest -> /Users/user/.duckdb/cli/1.2.1
└── extensions
└── v1.2.1
└── osx_arm64
├── excel.duckdb_extension
└── excel.duckdb_extension.info
7 directories, 3 files
Google Sheet
ExcelエクステンションはDuckDBの公式エクステンションです。
Google Sheetsの場合、コミュニティエクステンションの gsheets を利用すると、簡単に読み書きできます。
詳細は以下の通りです
まとめ
DuckDB 1.2で強化されたExcelエクステンションを使うことで、シームレスにでExcelファイルを操作できるようになりました。
主なポイントは以下の通りです
- DuckDB 1.2 以降は Excel エクステンションだけでExcelファイルを読み書きできるようになり、重厚なSpacial エクステンションは不要になりました
.xlsx形式のみ対応し、xls形式には対応していません- 書き込み時にはExcelファイル全体が書き換えられ、既存ファイルへのシート追記のような部分的な更新はできません
- Excelエクステンションはコアアクエステンションのため自動的にロードされ、明示的なインストール・ロードは不要です
