当前位置：首页 > news >正文

KingFusion 关系库查询核心：SQLQuery 与 AsynSQLQuery 函数全解析

news 2026/5/12 6:22:11

哈喽，你好啊，我是雷工！

在 KingFusion 中操作关系型数据库时，SQLQuery（同步查询）和AsynSQLQuery（异步查询）是最核心的两个基础函数，分别适配不同的业务场景需求。

今天就从语法、参数、实战示例和场景选型等维度，把这两个函数讲透，新手也能快速上手～

一、同步查询：SQLQuery 函数

1. 核心定位

SQLQuery是 KingFusion 中同步执行的关系库查询函数，调用后会阻塞后续代码执行，直到查询完成（成功 / 超时 / 失败），适合对执行顺序有强依赖的简单查询场景。

2. 语法与参数详解

let ret = await SQLQuery(dataSourceName , sqlString , recordSet , timeout);

参数名	类型	入参 / 出参	核心说明
dataSourceName	String	入参	已配置的 SQL 数据源名称（需与 KingFusion 后台数据源配置完全一致，区分大小写）
sqlString	String	入参	要执行的 SQL 查询语句（如SELECT * FROM zsytable），支持标准 SQL 语法
recordSet	JSON 对象数组	出参	存储查询结果，数组中每个对象对应数据库一行数据，字段名与数据库列名一致
timeout	Number	入参	查询超时时间（单位：毫秒），超出时间未返回则判定为失败

3. 返回值规则

执行成功：返回 0；
执行失败：返回对应错误码（如数据源不存在、SQL 语法错误、超时等，具体错误原因需查看 KingFusion 日志中关系库接口的详细信息）。

4. 实战示例（完整可复用）

// 1. 定义查询参数 var dataSource = "pgzsy"; // 数据源名称 var sqlQuery = 'SELECT * FROM zsytable'; // 查询SQL var retArray = []; // 用于接收查询结果的数组（出参） var timeout = 3000; // 超时时间3秒 // 2. 调用同步查询函数 var ret = await SQLQuery(dataSource, sqlQuery, retArray, timeout); // 3. 处理查询结果 if(ret === "0"){ Trace("PG同步查询成功"); // 输出查询数据条数 var num = retArray.length; Trace("查询到的数据个数：" + num); // 示例：对查询结果做数据类型转换（字段3转为整型） for(var k=0; k<num; k++){ retArray[k].字段3=parseInt(retArray[k].字段3); } // 打印处理后的完整结果 Trace("处理后的查询结果：", retArray); }else{ Trace("PG同步查询失败，错误码："+ ret); // 失败时建议补充日志定位问题 Trace("错误排查提示：检查数据源名称、SQL语法或数据库连接状态"); }

5. 使用注意事项

同步特性：调用后会等待查询完成，若查询数据量大 / 网络慢，会阻塞后续业务逻辑，不建议用于超大表查询；
异步关键字：函数前需加await，否则无法正确获取返回值；
结果处理：recordSet是输出参数，无需手动赋值，函数执行后会自动填充数据。

二、异步查询：AsynSQLQuery 函数

1. 核心定位

AsynSQLQuery是 KingFusion 中异步执行的关系库查询函数，调用后不会阻塞后续代码，查询结果通过回调函数返回，适合大数据量查询、非阻塞式业务流程场景。

2. 语法与参数详解

var ret = AsynSQLQuery(dataSourceName, sqlString, callback, timeout)

参数名	类型	入参 / 出参	核心说明
dataSourceName	String	入参	同 SQLQuery，已配置的 SQL 数据源名称
sqlString	String	入参	同 SQLQuery，要执行的 SQL 查询语句
callback	Function	出参	查询完成后的回调函数，接收errorCode（错误码）和recordSet（查询结果）
timeout	Number	入参	同 SQLQuery，查询超时时间（毫秒）

回调函数参数补充

// 回调函数声明格式callback(errorCode, recordSet)

errorCode：成功返回0，失败返回对应错误码（同 SQLQuery 错误码规则）；
recordSet：同 SQLQuery 的recordSet，存储查询结果的 JSON 对象数组。

3. 返回值规则

与 SQLQuery 一致：

成功返回0，

失败返回对应错误码

（注：此返回值仅代表 “函数调用请求发送成功”，不代表查询执行成功，最终结果需看回调函数的errorCode）。

4. 实战示例（完整可复用）

Trace('=======PG测试异步查询函数==========='); // 1. 定义查询参数 var dbName = 'pgzsy'; // 数据源名称 var sqlQue = 'SELECT * FROM zsytable'; // 查询SQL var timeout = 3000; // 超时时间3秒 // 2. 调用异步查询函数 var ret = AsynSQLQuery(dbName, sqlQue, function(err, retArray){ // 3. 回调函数中处理查询结果 if(err === 0){ Trace("PG异步查询执行成功"); var num = retArray.length; Trace("查询到的数据个数：" + num); // 示例：转换字段类型 for(var k=0; k<num; k++){ retArray[k].字段3=parseInt(retArray[k].字段3); } Trace("处理后的查询结果：", retArray); }else{ Trace('PG异步查询执行失败，错误码：'+ err); Trace("错误排查提示：检查SQL语法、数据源连接或超时时间设置"); } }, timeout); // 4. 异步特性验证（此代码会先于回调函数执行） Trace("异步查询请求已发送，返回值："+ ret);

5. 核心优势与注意事项

非阻塞：调用后立即返回，后续代码可正常执行，适合高并发 / 大数据量场景；
回调时机：回调函数仅在查询完成（成功 / 失败）后触发，需在回调内处理结果；
返回值误区：函数本身的返回值ret仅代表 “请求发送成功”，真正的查询结果需看回调的err和retArray。

三、两个函数的核心区别与场景选型

维度	SQLQuery（同步）	AsynSQLQuery（异步）
执行方式	阻塞式，await 等待结果	非阻塞式，回调接收结果
适用场景	简单查询、结果需立即使用的场景	大数据量查询、非阻塞业务流程
代码复杂度	低，线性执行	稍高，需处理回调逻辑
性能影响	数据量大时阻塞后续逻辑	不阻塞，资源利用率更高