自定义 SQL：当标准查询不够用时，把复杂查询交给数据库
很多业务系统在早期都能靠标准的数据集 API 跑起来，但一旦进入报表、分析、跨表查询这些场景，问题就会马上出现：前端要发多次请求，后端要写很多拼装代码，最后只是为了拿到一张统计表或一个排行榜。
自定义 SQL 想解决的，就是这类“标准查询不够用，但又不值得为此重写一套后端”的问题。它让开发者把复杂查询直接交给数据库完成，再通过 Lovrabet 平台统一管理和调用。
自定义 SQL 是什么
自定义 SQL 是 Lovrabet 提供的数据查询扩展能力。你可以在平台中保存一段 SQL，并在前端、服务端或 Backend Function 里按需调用它。
它不是用来替代标准 API，而是补上标准 API 不擅长的那部分能力，比如：
- 跨表关联查询
- 聚合统计和分组分析
- 多条件组合筛选
- 排行榜、趋势图、经营报表
换句话说，标准 API 负责常规的数据读写，自定义 SQL 负责更复杂、更贴近分析场景的数据查询。
它主要解决什么问题
企业里真正让人头疼的，往往不是“查一条数据”，而是“把多张表里的业务信息一次查明白”。
常见场景包括：
- 订单列表里，除了订单本身，还要带出客户名、商品名、支付状态
- 销售报表里，要按时间、地区、商品做汇总统计
- 运营分析里，要根据日期范围、状态、关键词等多个条件灵活组合查询
如果只靠标准 API，这类需求通常意味着多次请求、前端拼装、重复计算。逻辑一复杂，代码会迅速膨胀，查询性能也容易变差。
而自定义 SQL 的做法更直接：让数据库一次把结果查好，应用层只负责展示和使用结果。
为什么需要它
从产品能力上看，标准 API 已经能覆盖大量日常场景；但企业系统真正有价值的数据结果，很多都来自“关联、聚合、统计、筛选”这类复杂查询。也正因为如此，自定义 SQL 才是很多项目从“能用”走向“好用”的关键补充。
它的价值主要体现在四点：
- 查询更直接：原本需要多次请求和手动拼装的数据，可以一次拿到
- 性能更合适：聚合和关联放在数据库层执行，通常比前端或业务层拼装更高效
- 复用更容易：一段 SQL 在平台统一管理，多个页面和接口可以复用
- 边界更清晰：标准 API 处理通用读写，自定义 SQL 处理复杂查询，职责不会混在一起
所以，自定义 SQL 不是“多一种写法”，而是在复杂查询场景下，用更合适的方式解决问题。
一个最常见的 Demo
以“销售排行榜”为例。业务想要看到某个时间范围内，销量最高的商品 Top 10。
如果走普通接口，往往要先查订单、再查订单明细、再查商品信息，最后在应用层自己做汇总和排序。
如果使用自定义 SQL，这件事可以直接交给数据库：
SELECT
p.product_name,
SUM(oi.quantity) AS totalQuantity,
SUM(oi.subtotal) AS totalAmount
FROM dataset_order_items oi
JOIN dataset_orders o ON oi.order_id = o.id
JOIN dataset_products p ON oi.product_id = p.id
WHERE o.order_date >= #{startDate}
AND o.order_date <= #{endDate}
GROUP BY p.product_name
ORDER BY totalAmount DESC
LIMIT 10前端或服务端只需要调用这段 SQL：
const result = await client.sql.execute({
sqlCode: "sales-ranking",
params: {
startDate: "2024-01-01",
endDate: "2024-12-31",
},
});
if (result.execSuccess && result.execResult) {
console.log(result.execResult);
}这样，页面拿到的就已经是可直接展示的排行榜结果，而不是一堆还要继续加工的原始数据。
写在最后
很多时候，企业并不缺数据，而是缺少一种把复杂数据结果高效提取出来的方式。自定义 SQL 的意义，就在于把这部分能力从繁琐的数据拼装中解放出来，让开发者用最熟悉的 SQL，把真正有业务价值的结果直接查出来。
这篇文章只回答“它是什么、解决什么问题、为什么需要它”。如果你想继续看具体的创建方式、参数写法、动态 SQL、调用细节和排错方法，可以继续阅读后面的专题文档。
继续阅读
- 自定义 SQL 使用教程 - 从创建到调用的完整说明
- SQL API 参考 - 方法签名、参数和返回值
- 报表页：SQL 实现销售统计 - 真实业务案例
- 语法糖：sqlSafe - 简化错误处理