matlab-read-database

MATLAB Database Toolbox のプッシュダウン設計者

MATLAB Database Toolbox のプッシュダウン機能を使ってリレーショナルデータベースからデータをインポートする場合に使用します。行のフィルター処理、列の選択、重複の除外、結合を MATLAB で処理するのではなく、データベースにオフロードします。

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

• データベーステーブルまたは SQL クエリから MATLAB テーブルとしてデータをインポートする
• データベーステーブルまたは SQL クエリから行をフィルターする
• データベーステーブルまたは SQL クエリから特定の列を選択する
• データベーステーブルまたは SQL クエリ内の重複行を除外する
• 2 つのデータベーステーブルを結合する
• 結合とフィルター処理または列の選択を組み合わせる
• ユーザーが次のキーワードに言及している場合：import、sqlread、fetch、filter、rowfilter、join、sqlinnerjoin、sqlouterjoin、duplicates、databaseImportOptions、pushdown

使用しない場合

• データベースへのデータの書き込み／挿入 — 代わりに sqlwrite／sqlupdate／execute のパターンを使用します
• データが大きすぎてメモリに収まらない — DatabaseDatastore と tall 配列、または splitsqlquery を使用します
• クラスマッピングを使用したオブジェクト指向の読み込み — ORM（Mappable クラスで ormread）を使用します
• MongoDB、Cassandra、Neo4j のクエリ — プッシュダウン関数はリレーショナルデータベースでのみ動作します

重要なルール

プッシュダウンの方針

• 必ずテーブルには sqlread、SQL クエリには fetch を使用します。
• 必ずRowFilter を使用して行のフィルター処理をデータベースにプッシュダウンします。絶対にすべての行をインポートしてから MATLAB でフィルター処理してはいけません。
• 必要な列が一部だけの場合は、必ずSelectedVariableNames を指定して databaseImportOptions を使用します。
• 操作の前に 必ず isopen(conn) で接続を確認し、完了後に close(conn) を呼び出します。

結合

• データベーステーブルをちょうど 2 つ結合する場合は、必ずsqlinnerjoin／sqlouterjoin を使用します。
• 絶対にdatabaseImportOptions（opts）を sqlinnerjoin または sqlouterjoin に渡してはいけません。これらの関数は受け付けません。結合後に MATLAB で列を選択するか、明示的な SQL を指定して fetch を使用します。
• 3 つ以上のテーブルを結合する場合や、集計を伴う結合では、絶対にプッシュダウン結合を使用してはいけません。代わりに明示的な SQL を指定して fetch を使用します。

関数リファレンス

各関数が受け付けるもの

関数	opts を受け付けるか	RowFilter を受け付けるか	MaxRows を受け付けるか	列の選択
sqlread	はい	はい	はい	opts.SelectedVariableNames で指定
fetch	はい	はい	はい	opts.SelectedVariableNames で指定
sqlinnerjoin	いいえ	はい	はい	非対応 — 結合後に列を選択
sqlouterjoin	いいえ	はい	はい	非対応 — 結合後に列を選択

パラメーターの詳細については、reference/cards/pushdown-joins.md と reference/cards/import-options.md を参照してください。

判断の指針

どの関数を使えばよいですか？

状況	使用するもの	理由
単一のテーブルからインポートする	sqlread	フィルター／列の選択を DB にプッシュダウンします
SQL クエリからインポートする	fetch	DB で任意の SQL を実行します
テーブルをちょうど 2 つ結合する（列の選択が不要）	sqlinnerjoin / sqlouterjoin	結合は DB で実行されます
2 つのテーブルを結合し、特定の列を選択する	sqlinnerjoin + MATLAB での列の選択	結合関数は opts を受け付けません
2 つのテーブルを結合し、列を選択して重複を除外する	明示的な SQL を指定した fetch	プッシュダウン結合では opts や DISTINCT を処理できません
3 つ以上のテーブルを結合する、または集計を使用する	明示的な SQL を指定した fetch	プッシュダウン結合は 2 つのテーブルに制限されます
ExcludeDuplicates が必要	opts を指定した sqlread／fetch	databaseImportOptions を受け付けるのはこれらの関数のみです

完全な例

詳しい例については、ナレッジカードを参照してください。

• フィルター処理を伴う単一テーブルのインポート：reference/cards/sqlread-fetch.md
• 列の選択と重複の除外：reference/cards/import-options.md
• フィルター処理を伴う 2 テーブルの結合：reference/cards/pushdown-joins.md
• 複雑な複数テーブルの結合：reference/cards/pushdown-joins.md（SQL へのフォールバックのセクション）

よくある間違い

% INCORRECT — passing import options to join functions (error!)
opts = databaseImportOptions(conn, "orders");
result = sqlinnerjoin(conn, "orders", "items", opts);  % Error!

% CORRECT — join first, then select columns from the result
result = sqlinnerjoin(conn, "orders", "items", Keys="order_id");
result = result(:, ["order_id", "product", "quantity", "total"]);

% INCORRECT — using fetch without pushdown (pulls all data, filters in MATLAB)
data = fetch(conn, "SELECT * FROM orders");
filtered = data(data.total > 100, :);

% CORRECT — push the filter to the database
opts = databaseImportOptions(conn, "orders");
opts.RowFilter = opts.RowFilter.total > 100;
data = sqlread(conn, "orders", opts);

ベストプラクティス

• 簡単なフィルタリングには、RowFilterを名前と値の引数としてsqlread／fetch／sqlinnerjoin／sqlouterjoinに直接指定します。列の選択や重複排除も必要な場合は、opts.RowFilterを使用します。
• fetchでSQLクエリにRowFilterを重ねると、RowFilterの条件はSQLのWHERE句に加えて適用されます。同じ条件を両方に重複して指定しないでください。
• 対象がちょうど2つのテーブルで、列の選択や集計が不要な場合は、JOIN SQLを手動で記述するよりsqlinnerjoin／sqlouterjoinを使用してください。
• JOINと列の選択を行う場合は、データ量に応じて選択してください。追加する列が少ない場合は、JOINしてからMATLABで列を選択します。テーブルの列数が多くデータ量も大きい場合は、fetchで明示的なSQLを指定して、データベース上で列を選択します。
• 列数が50を超えるテーブルでは、必ずSelectedVariableNamesを使用して列を絞り込みます。メモリに収まらない10万行を超える結果セットには、tall配列でDatabaseDatastoreを使用するか、メモリ外処理にsplitsqlqueryを使用します。

よくあるパターン

パターン1：単一テーブル — フィルター＋列の選択

opts = databaseImportOptions(conn, "orders");
opts.SelectedVariableNames = ["OrderKey", "OrderStatus"];
opts.RowFilter = opts.RowFilter.OrderPriority == "URGENT";
T = sqlread(conn, "orders", opts);

パターン2：2テーブルのJOIN — フィルターのみ

rf = rowfilter("ShipMode");
T = sqlinnerjoin(conn, "orders", "lineitem", Keys="OrderKey", RowFilter=rf.ShipMode == "AIR");

パターン3：2テーブルのJOIN — フィルター＋列の選択（JOIN後）

rf = rowfilter(["OrderPriority", "ShipMode"]);
T = sqlinnerjoin(conn, "orders", "lineitem", Keys="OrderKey", ...
    RowFilter=rf.OrderPriority == "URGENT" & rf.ShipMode == "AIR");
result = T(:, ["OrderKey", "OrderStatus"]);

パターン4：複雑なクエリではSQLに切り替える

sqlquery = "SELECT o.OrderKey, o.OrderStatus " + ...
    "FROM orders o INNER JOIN lineitem l ON o.OrderKey = l.OrderKey " + ...
    "WHERE o.OrderPriority = 'URGENT' AND l.ShipMode = 'AIR'";
T = fetch(conn, sqlquery);

パターン5：エラー処理を含む安全なインポート

try
    opts = databaseImportOptions(conn, "orders");
    opts.SelectedVariableNames = ["id", "total", "status"];
    opts.RowFilter = opts.RowFilter.total > 100;
    data = sqlread(conn, "orders", opts);
catch ME
    warning("Import failed: %s", ME.message);
    data = table.empty;
end

チェックリスト

プッシュダウンインポートのコードを仕上げる前に、次の点を確認してください。

• データベーステーブルにはsqlreadを、SQLクエリにはfetchを使用している
• 行フィルターにはRowFilterパラメーターを使用しており（データベースにプッシュダウンされる）、クライアント側でフィルタリングしていない
• databaseImportOptionsのSelectedVariableNamesを使用して、必要な列のみを選択している
• databaseImportOptionsをsqlinnerjoinまたはsqlouterjoinに渡していない
• 重複排除にはMATLABのunique()ではなくExcludeDuplicatesを使用している
• JOINにはsqlinnerjoin／sqlouterjoinを使用している（テーブルは2つまで、optsなし）
• 複雑なクエリ（テーブルが3つ以上、集計、JOINと列の選択）には、SQLを指定したfetchを使用している
• 接続の試行後にisopen(conn)を確認している
• 最後にclose(conn)を呼び出している

トラブルシューティング

問題：databaseImportOptionsを渡すとsqlinnerjoinでエラーが発生する

• 解決策：sqlinnerjoinとsqlouterjoinはdatabaseImportOptionsを受け付けません。呼び出しからoptsを削除してください。JOIN後にMATLABで列を選択するか、明示的なSQLを指定してfetchを使用します。

問題：RowFilterが反映されず、すべての行が返される

• 解決策：rowfilter("ColName")の列名がデータベースの列名と完全に一致していることを確認してください（データベースによっては大文字と小文字が区別されます）。

問題：「Key variable not found」というエラーがsqlinnerjoinで発生する

• 解決策：Keysの値は、両方のテーブルに存在する列名と一致している必要があります。sqlfind(conn, "tableName")を使用して列名を確認してください。

問題：SQLクエリでdatabaseImportOptionsのエラーが発生する

• 解決策：SQLクエリが有効で、結果を返すことを確認してください。databaseImportOptionsはメタデータクエリを実行します。基になるクエリに構文エラーがあると失敗します。

問題：ExcludeDuplicatesで想定どおりに重複が削除されない

• 解決策：ExcludeDuplicatesは、選択したすべての変数の組み合わせに適用されます。先にSelectedVariableNamesで列を絞り込んでから、ExcludeDuplicates = trueを設定してください。

問題：sqlouterjoinが想定外のNULLを返す

• 解決策：外部JOINでは、一致しない行がNULLで埋められて含まれます。これはSQLの想定された動作です。JOIN後に行を除外するにはRowFilterを使用するか、一致する行のみが必要な場合はsqlinnerjoinに切り替えてください。

---

Copyright 2026 The MathWorks, Inc.

---