matlab-read-database

MATLAB Database Toolbox 下推架构师

从关系型数据库导入数据，并使用 MATLAB Database Toolbox 的下推功能时使用——将行筛选、列选择、重复项排除和连接操作下推到数据库执行，而不是在 MATLAB 中处理。

何时使用此技能

• 将数据库表或 SQL 查询中的数据导入为 MATLAB 表
• 筛选数据库表或 SQL 查询中的行
• 选择数据库表或 SQL 查询中的特定列
• 排除数据库表或 SQL 查询中的重复行
• 连接两个数据库表
• 将连接与筛选或列选择结合使用
• 用户提及以下关键词：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)。

连接

• 始终使用 sqlinnerjoin/sqlouterjoin 连接恰好两个数据库表。
• 切勿将 databaseImportOptions（opts）传递给 sqlinnerjoin 或 sqlouterjoin——它们不接受此参数。连接后在 MATLAB 中选择列，或使用带显式 SQL 的 fetch。
• 切勿对三个或更多表的连接或包含聚合的连接使用下推连接——改用带显式 SQL 的 fetch。

函数参考

各函数接受的参数

函数	接受 opts？	接受 RowFilter？	接受 MaxRows？	列选择
sqlread	是	是	是	通过 opts.SelectedVariableNames
fetch	是	是	是	通过 opts.SelectedVariableNames
sqlinnerjoin	否	是	是	不支持——连接后选择列
sqlouterjoin	否	是	是	不支持——连接后选择列

完整参数详情请参阅 reference/cards/pushdown-joins.md 和 reference/cards/import-options.md。

决策框架

应该使用哪个函数？

情况	使用	原因
从单个表导入	sqlread	将筛选/列选择下推到数据库
从 SQL 查询导入	fetch	在数据库上执行任意 SQL
连接恰好两个表（无需选择列）	sqlinnerjoin / sqlouterjoin	在数据库上执行连接
连接两个表 + 选择特定列	sqlinnerjoin + MATLAB 列选择	连接函数不接受 opts
连接两个表 + 列选择 + 去重	带显式 SQL 的 fetch	下推连接无法处理 opts 或 DISTINCT
连接三个或更多表，或使用聚合	带显式 SQL 的 fetch	下推连接最多支持两个表
需要 ExcludeDuplicates	使用 opts 的 sqlread/fetch	只有这些函数接受 databaseImportOptions

完整示例

详细示例请参阅知识卡片：

• 带筛选的单表导入：reference/cards/sqlread-fetch.md
• 列选择和去重：reference/cards/import-options.md
• 带筛选的两表连接：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 个表且无需选择列或聚合时，优先使用 sqlinnerjoin/sqlouterjoin，而不是手动编写 JOIN SQL。
• 对于连接并选择列的操作，请根据数据量选择方法：如果额外列较少，先连接，再在 MATLAB 中选择列。如果表的列很多且数据量较大，请使用带显式 SQL 的 fetch，在数据库上选择列。
• 对于列数 >50 的表，请始终使用 SelectedVariableNames 限制列数。对于无法装入内存的 >100K 行结果集，请使用 DatabaseDatastore 配合 tall 数组，或使用 splitsqlquery 进行内存外处理。

常见模式

模式 1：单表 — 筛选 + 选择列

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

模式 2：两表连接 — 仅筛选

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

模式 3：两表连接 — 筛选 + 选择列（连接后）

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
• 使用 ExcludeDuplicates 而不是 MATLAB unique() 进行去重
• 连接使用 sqlinnerjoin/sqlouterjoin（仅限 2 个表，不使用 opts）
• 复杂查询（3 个或更多表、聚合、连接并选择列）使用带 SQL 的 fetch
• 连接尝试后检查 isopen(conn)
• 最后调用 close(conn)

故障排除

问题：传递 databaseImportOptions 时，sqlinnerjoin 报错

• 解决方案：sqlinnerjoin 和 sqlouterjoin 不接受 databaseImportOptions。请从调用中移除 opts。在连接后于 MATLAB 中选择列，或使用带显式 SQL 的 fetch。

问题：RowFilter 不起作用——仍返回所有行

• 解决方案：确认 rowfilter("ColName") 中的列名与数据库列名完全一致（某些数据库区分大小写）。

问题：sqlinnerjoin 报错 “Key variable not found”

• 解决方案：Keys 的值必须与两个表中都存在的列名匹配。使用 sqlfind(conn, "tableName") 检查列名。

问题：对 SQL 查询使用 databaseImportOptions 时出错

• 解决方案：确保 SQL 查询有效且会返回结果。databaseImportOptions 会执行元数据查询——如果基础查询有语法错误，就会失败。

问题：ExcludeDuplicates 未按预期移除重复项

• 解决方案：ExcludeDuplicates 会针对所有选定变量的组合去重。请先使用 SelectedVariableNames 缩小列范围，再设置 ExcludeDuplicates = true。

问题：sqlouterjoin 返回意外的 NULL

• 解决方案：外连接会包含不匹配的行，并以 NULL 填充。这是预期的 SQL 行为。使用 RowFilter 在连接后排除这些行；如果只需要匹配的行，则改用 sqlinnerjoin。

---

版权所有 2026 The MathWorks, Inc.

---