matlab-use-duckdb

DuckDB 向け MATLAB Database Toolbox インターフェイス

Database Toolbox を使用して MATLAB から DuckDB データベースを操作する場合に使用します。DuckDB は組み込み型の分析データベースエンジンで、R2026a 以降、Database Toolbox に付属しています。外部データベースサーバーの設定なしで、SQL ベースのファイル分析、メモリに収まらないデータの前処理、移植可能な開発用データベースを利用できます。

このスキルを使用する場合

• DuckDB データベース（メモリ内またはファイルベース）に接続する
• 開発ワークフロー用に新しい DuckDB データベースファイルを作成する
• CSV、Parquet、JSON ファイルを SQL で直接クエリする
• 分析前に大規模なデータを削減またはプロファイリングする
• DuckDB を数値計算以外の操作エンジンとして使用する（フィルタリング、集計、重複排除、文字列のクリーンアップ、型変換、ソート、サンプリング）
• DuckDB 拡張機能をインストールして使用する
• ファイルデータを .duckdb ファイルに保存し、繰り返しクエリする
• ユーザーが次のキーワードに言及する場合：DuckDB、duckdb()、分析エンジン、組み込みデータベース、大規模 CSV、大規模 Parquet/JSON、readtable では大きすぎるファイル、データソースでのフィルタリング／集計、重複排除、分析前の削減、大規模ファイルのプロファイリング、永続ファイルへのインポート、CSV に対する SQL、Parquet に対する SQL、JSON に対する SQL、SQL で CSV をクエリ、SQL で Parquet をクエリ、ファイルに対する SQL の実行、ファイルに対する SQL クエリ、ファイルの直接クエリ、データベースなしでの SQL、プロセス内 SQL

使用しない場合

• メモリに収まる単一ファイル — MATLAB のネイティブ I/O（readtable／readmatrix）を使用します
• 複数ファイルのワークフロー — まず datastore／tall を使用します。DuckDB の glob は代替手段であり、既定の方法ではありません
• データがメモリを超え、SQL による削減でも収まらない場合 — ストリーミングには datastore／tall を使用します
• 数学的処理が中心の操作や数値的に高い精度が求められる操作（正規化、ウィンドウ統計、外れ値検出） — データを削減した後、MATLAB に引き継ぎます
• MySQL、PostgreSQL、SQLite、その他の外部データベースへの接続 — 各データベースのネイティブインターフェイスまたは JDBC/ODBC を使用します
• オブジェクトリレーショナルマッピング — ORM（Mappable クラスを使用する ormread／ormwrite）を使用します
• MongoDB、Cassandra、Neo4j — Database Toolbox 専用のインターフェイスを使用します

読み込み時のプロトコル

既存のコードがあるセッションにこのスキルを読み込んだ場合：

1. データパイプラインを監査する — データがワークフローにどのように取り込まれるかを特定します：

   • MATLAB I/O（readtable、readmatrix、readcell、readtimetable、parquetread、xlsread、csvread）を使用してデータを読み込んでいますか？
   • その後、クエリの前に sqlwrite を使ってデータを DuckDB に書き込んでいますか？
   • 該当する場合、これは読み込んでからクエリするアンチパターンです。DuckDB なら、read_csv、read_parquet、または read_xlsx（excel 拡張機能）を介して、ソースファイルを直接読み込める可能性があります。

2. 次の判断基準に照らして、各データソースを評価する：

   • DuckDB はこのファイル形式を直接読み込めますか？（CSV、Parquet、JSON、拡張機能を介した Excel）
   • フィルタリング／集計を SQL の読み込み処理にプッシュできますか？
   • MATLAB I/O の手順がパフォーマンスのボトルネックになっていますか？

3. アーキテクチャの変更を提案する — API の正しさだけにレビューを限定しないでください。readtable／xlsread + sqlwrite + クエリの連鎖を、fetch(conn, "SELECT ... FROM read_csv/read_parquet/read_xlsx(...)") に置き換えることを提案します。

このスキルで最も価値の高いパターンは、アーキテクチャに関するものです。ファイル分析をプッシュダウンすることでパイプラインの段階全体をなくし、10 倍以上の高速化につながる可能性があります。

事前確認

DuckDB を使用する方針を決める前に、ファイル形式によるメモリ内での展開を考慮して、ファイルサイズと利用可能な RAM の比率を見積もり、適切な方法に振り分けます。

条件	方法	根拠
単一ファイル、比率 < 0.5	MATLAB のネイティブ I/O	メモリに収まるため、DuckDB を使うと不必要に複雑になります
複数ファイル、またはファイルごとの処理	datastore／tall（代替手段：DuckDB glob）	ストリーミングは複数ファイルを扱う際の基本パターンです
単一ファイル、比率 ≥ 0.5、SQL で表現できる削減処理がある	DuckDB：プロファイリング → 操作 → 終了	DuckDB を使う価値があります
単一ファイル、比率 ≥ 0.5、SQL による削減処理が適用できない	datastore／tall	削減できない場合、DuckDB を使う利点はありません

操作メニュー

DuckDB の SQL で行うこと

操作	SQL の例
行をフィルター	WHERE status = 'active'
集計	GROUP BY region、SUM(revenue)、COUNT(*)、AVG(price)
重複を除去	SELECT DISTINCT ... または ROW_NUMBER() OVER (PARTITION BY ...)
文字列をクリーンアップ	TRIM()、LOWER()、REPLACE()、REGEXP_REPLACE()
型変換	TRY_CAST(col AS DATE)、CAST(col AS DOUBLE)
並べ替え	ORDER BY timestamp
サンプリング	USING SAMPLE 10000 または TABLESAMPLE RESERVOIR(10%)
プロファイル	COUNT(*)、MIN/MAX、APPROX_COUNT_DISTINCT
件数を制限	LIMIT 50000

DuckDB の SQL で行わないこと

操作	避ける理由
正規化／z スコア	母集団の情報が必要です
ウィンドウ統計（移動平均、累積和）	セマンティクスが不安定で、NULL の処理も異なります
外れ値の検出	統計的な判断を要します
補間／リサンプリング	ドメイン固有のロジックです
信号処理	SQL の用途ではありません
機械学習の特徴量	モデルに依存します

SQL の操作は、MATLAB のセマンティクス（NULL の処理、並べ替え順、重複の除去）と必ずしも一致しません。既知の不一致については reference/cards/reduce-large-data.md を参照してください。

データ削減のワークフロー

事前チェックで DuckDB を使うことになった場合は、reference/cards/reduce-large-data.md にある「プロファイル → 操作 → クローズ」のパターンに従ってください。

DuckDB はデータを選択、変形、クリーンアップ、削減します。データがメモリに収まり、接続を閉じたら、DuckDB の役割は完了です。

DuckDB とは何か、そして Database Toolbox に含まれている理由

DuckDB は組み込み型のサーバーレス分析データベースエンジンです。MySQL や PostgreSQL とは異なり、サーバーも設定も不要で、MATLAB 内のプロセスで実行されます。

Database Toolbox に含まれている理由（R2026a+）：

• 設定不要のデータベース — conn = duckdb() を実行するだけで、すぐに完全な SQL エンジンを利用できます。
• ファイル向け分析エンジン — CSV、Parquet、JSON ファイルをメモリに読み込まずに、SQL で直接クエリできます。
• メモリに収まらないデータの前処理 — メモリより大きなデータセットをフィルター、集計、結合、並べ替えしてから、結果だけを MATLAB に取り込めます。
• ポータブルな開発用データベース — .duckdb または .db ファイルは、Database Toolbox があればどのマシンでも動作します。データベースのセットアップは不要です。
• AI エージェントのメリット — エージェントの SQL に関する知識を、強力な分析クエリにそのまま活用できます。

DuckDB は MATLAB のファイル入出力（readtable など）や datastore／tall を置き換えるものではありません。データがメモリを超え、かつタスクを SQL で表現できる操作に削減できる場合に、高性能な代替手段となります。削減が適用できない場合は、引き続き datastore／tall が適切な方法です。

重要なルール

事前チェックのゲート

• DuckDB のコードを書く前に、必ず事前にサイズと RAM の比率を確認してください。比率が 0.5 未満の場合は、そこで中止してネイティブの MATLAB 入出力を使用してください。DuckDB のパターンで処理を続けないでください。

接続

• 接続には必ず duckdb() を使用してください。database()、JDBC、ODBC は使用しないでください。
• 必ず isopen(conn) で接続を確認し、close(conn) で閉じてください。

API の範囲

• 標準関数はすべて動作します：sqlread、fetch、execute、sqlwrite、sqlfind、sqlinnerjoin、sqlouterjoin、commit、rollback。
• DuckDB は databasePreparedStatement をサポートしていません。代わりに execute または sqlwrite を使用してください。
• データベーステーブルから読み込む場合（sqlread を使用）、databaseImportOptions で ExcludeDuplicates を使用してください。ファイルを直接クエリする場合（fetch 経由の read_csv／read_parquet）、SQL で SELECT DISTINCT を使用してください。

名前付きテーブルとファイルクエリ

• 名前付きデータベーステーブルの単純な行フィルターには、必ず fetch と WHERE を使うのではなく、RowFilter を指定した sqlread を使用してください。rowfilter オブジェクトを作成し、RowFilter の名前と値の引数で渡してください。
• 名前付きテーブルの集計、結合、または複雑なクエリには、SQL を指定した fetch を使用してください。
• ファイルのクエリには、必ず sqlread ではなく fetch を使用してください。SELECT * FROM read_csv('file.csv') のような SQL 構文が必要です。
• SQL 内のファイルパスは、必ずシングルクォートで囲んでください：read_csv('data.csv')。

接続モード

目的	接続	理由
ファイルに対する分析クエリ	duckdb()	永続化が不要で、ファイルを直接クエリできます
一時的なワークスペース	duckdb()	高速で、閉じると破棄されます
ポータブルな開発用データベース	duckdb("mydata.duckdb")	.duckdb または .db ファイルを作成し、どのマシンでも動作します
既存のデータベースを開く	duckdb("existing.db")	既存の .db または .duckdb ファイルへの読み書きアクセス
読み取り専用の共有データベース	duckdb("shared.duckdb", ReadOnly=true)	誤った書き込みを防止します

よくあるパターン

パターン 1：ファイル上の分析エンジン

conn = duckdb();
result = fetch(conn, "SELECT region, SUM(revenue) as total " + ...
    "FROM read_parquet('sales.parquet') " + ...
    "GROUP BY region ORDER BY total DESC");
close(conn);

パターン 2：メモリに収まらないデータの前処理

conn = duckdb();
summary = fetch(conn, "SELECT date, AVG(value) as avg_val " + ...
    "FROM read_csv('huge_dataset.csv') " + ...
    "WHERE status = 'valid' " + ...
    "GROUP BY date ORDER BY date");
close(conn);
% summary fits in memory — continue with MATLAB analysis

パターン 3：RowFilter を使用して名前付きテーブルを読み取る

conn = duckdb("inventory.duckdb", ReadOnly=true);
rf = rowfilter("quantity");
data = sqlread(conn, "products", RowFilter=rf.quantity < 10);
close(conn);

パターン 4：開発用データベース

conn = duckdb("dev.duckdb");
sqlwrite(conn, "experiments", experimentData);
rf = rowfilter("score");
results = sqlread(conn, "experiments", RowFilter=rf.score > 0.8);
close(conn);

パターン 5：Glob を使用した複数ファイルのクエリ

datastore／tall が適さない場合（例：ファイル間の SQL 集計）に使用します。ファイルごとに順次処理する場合は、datastore を優先してください。

conn = duckdb();
data = fetch(conn, "SELECT * FROM read_parquet('data/year=2024/*.parquet') " + ...
    "WHERE category = 'A'");
close(conn);

パターン 6：拡張機能

conn = duckdb();
execute(conn, "INSTALL httpfs");
execute(conn, "LOAD httpfs");
data = fetch(conn, "SELECT * FROM read_parquet('https://example.com/data.parquet') LIMIT 1000");
close(conn);

Excel ファイルには、空間データ用の st_read ではなく、read_xlsx と excel 拡張機能を使用してください。

conn = duckdb();
execute(conn, "INSTALL excel");
execute(conn, "LOAD excel");
data = fetch(conn, "SELECT * FROM read_xlsx('report.xlsx')");
close(conn);

パターン 7：ファイルからの永続的なインポート

conn = duckdb("analytics.duckdb");
execute(conn, "CREATE TABLE events AS SELECT * FROM read_parquet('raw_events.parquet')");
% Future sessions: query by table name (no file re-read)
result = sqlread(conn, "events");
close(conn);

詳しい例については、以下を参照してください。

• ファイル分析とメモリに収まらないデータの前処理：reference/cards/file-analytics.md
• 開発用データベースのワークフロー：reference/cards/development-database.md
• DuckDB 拡張機能：reference/cards/extensions.md

よくある間違い

% WRONG — using database() or JDBC to connect to DuckDB
conn = database("", "", "", "org.duckdb.DuckDBDriver", "jdbc:duckdb:");
% CORRECT
conn = duckdb();

% WRONG — using sqlread for file queries (expects a table name)
data = sqlread(conn, "read_csv('data.csv')");
% CORRECT — use fetch with SQL
data = fetch(conn, "SELECT * FROM read_csv('data.csv')");

% WRONG — double quotes for file paths in SQL
data = fetch(conn, "SELECT * FROM read_csv(""data.csv"")");
% CORRECT — single quotes
data = fetch(conn, "SELECT * FROM read_csv('data.csv')");

% WRONG — loading huge file into MATLAB then filtering
data = readtable("huge.parquet"); filtered = data(data.val > 100, :);
% CORRECT — let DuckDB filter on disk
conn = duckdb();
filtered = fetch(conn, "SELECT * FROM read_parquet('huge.parquet') WHERE val > 100");
close(conn);

% WRONG — using databasePreparedStatement (not supported)
pstmt = databasePreparedStatement(conn, "INSERT INTO t VALUES(?, ?)");
% CORRECT — use sqlwrite
sqlwrite(conn, "t", data);

% WRONG — using st_read from spatial extension for Excel files
data = fetch(conn, "SELECT * FROM st_read('file.xlsx')");
% CORRECT — use excel extension with read_xlsx
execute(conn, "INSTALL excel");
execute(conn, "LOAD excel");
data = fetch(conn, "SELECT * FROM read_xlsx('file.xlsx')");

% WRONG — MATLAB table column named with SQL reserved keyword
data = table(1, "A", 'VariableNames', {'id','group'});
sqlwrite(conn, "t", data);  % Parser error: "group" is reserved
% CORRECT — rename column before writing
data = renamevars(data, 'group', 'experiment_group');
sqlwrite(conn, "t", data);

チェックリスト

DuckDB のコードを確定する前に、以下を確認してください。

• パイプラインの確認：DuckDB がファイルを直接読み取れる場合に、不要な MATLAB のファイル I/O（例：readtable、xlsread、parquetread）と sqlwrite の連鎖がない
• database() や JDBC ではなく、duckdb() または duckdb("file.duckdb")／duckdb("file.db") で接続している
• 接続後に isopen(conn) を確認している
• ファイルのクエリには、sqlread ではなく SQL を指定した fetch を使用している
• SQL 内のファイルパスをシングルクォートで囲んでいる
• メモリに収まらないデータを MATLAB にインポートする前に、DuckDB で前処理している
• databasePreparedStatement を使用していない（サポートされていません）
• 処理が終わったら close(conn) を呼び出している

トラブルシューティング

問題：duckdb 関数が見つからない

• 解決策：Database Toolbox を含む R2026a 以降が必要です。ver('database') で確認してください。

問題：ファイルのクエリで sqlread がエラーになる

• 解決策：fetch(conn, "SELECT * FROM read_csv('file.csv')") を使用してください。sqlread が受け取るのはテーブル名のみです。

問題：ReadOnly 接続でアクセスが拒否される

• 解決策：ReadOnly を指定せずに再接続してください：conn = duckdb("file.duckdb")。

問題：大きなファイルのクエリでメモリ不足になる

• 解決策：SQL に WHERE、GROUP BY、LIMIT または集計を追加して、結果が MATLAB に取り込まれる前にサイズを減らしてください。

問題：read_csv／read_parquet でファイルパスが見つからない

• 解決策：パスは pwd からの相対パスです。絶対パスを使用するか、dir('file.csv') で確認してください。

問題：拡張機能のインストールに失敗する

• 解決策：初回のインストールにはインターネット接続が必要です（以降はキャッシュされます）。https://duckdb.org/docs/current/core_extensions/overview を参照してください。

問題：sqlwrite が列名の「syntax error at or near」で失敗する

• 解決策：列名が SQL の予約語（group、order、select、table など）です。書き込む前に renamevars(data, 'group', 'experiment_group') で名前を変更してください。

問題：sqlwrite で型が一致しない

• 解決策：DuckDB は豊富な型（ARRAY、LIST、STRUCT、MAP）をサポートしています。sqlfind(conn, "tableName") を使用して列の型を確認してください。

---

Copyright 2026 The MathWorks, Inc.

---