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

在 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 等待结果

非阻塞式，回调接收结果

适用场景

简单查询、结果需立即使用的场景

大数据量查询、非阻塞业务流程

代码复杂度

低，线性执行

稍高，需处理回调逻辑

性能影响

数据量大时阻塞后续逻辑

不阻塞，资源利用率更高

总结SQLQuery是同步查询函数，语法简单、结果获取直接，适合小数据量、强顺序依赖的查询场景，使用时需加await；AsynSQLQuery是异步查询函数，非阻塞、性能更优，适合大数据量或无需立即等待结果的场景，结果需在回调函数中处理；两个函数的错误码规则一致，失败时需结合 KingFusion 日志排查数据源、SQL 语法、超时时间等问题。

掌握这两个函数的核心差异和用法，就能根据实际业务场景灵活选择，高效完成 KingFusion 中关系库的数据查询操作～

2026-01-20

四川·绵阳