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

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

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

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

一、同步查询：SQLQuery 函数

1. 核心定位

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

2. 语法与参数详解

javascript 复制代码

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. 实战示例（完整可复用）

javascript 复制代码

// 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. 实战示例（完整可复用）

javascript 复制代码

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

四川·绵阳