---

SQL API 参考

v1.1.19+

SQL API 允许你执行在 Lovrabet 平台上配置的自定义 SQL 查询。

ℹ️ 版本要求此功能从 SDK v1.1.19 版本开始支持。

💡 新手指南如果你是第一次使用自定义 SQL，建议先阅读 自定义 SQL 使用教程，本文档仅作为 API 参考。

什么时候使用 SQL API？

场景	推荐 API
简单的 CRUD 操作	Dataset API
跨表关联查询	SQL API ✅
复杂的聚合统计	SQL API ✅
自定义报表	SQL API ✅

API 方法

execute() - 推荐方式 v1.2.0+

使用 client.sql 命名空间执行 SQL 查询。

方法签名

client.sql.execute<T>({ sqlCode, params }: SqlExecuteParams): Promise<SqlExecuteResult<T>>
client.sql.execute<T>(sqlCode: string | number, params?: Record<string, any>): Promise<SqlExecuteResult<T>>

参数

参数	类型	必填	说明
sqlCode	string | number	✅	SQL 代码，格式："xxxxx-xxxxx" 或数字 ID
params	Record<string, any>	❌	SQL 参数对象，用于参数化查询

返回值

interface SqlExecuteResult<T> {
  execSuccess: boolean; // SQL 执行是否成功
  execResult?: T[]; // 查询结果数组（仅成功时存在）
}

⚠️ 重要SDK 返回的是包含 execSuccess 和 execResult 的对象，不是直接返回数组。

应用层必须先检查 execSuccess 再使用 execResult。

executeSql() - 兼容方式

使用 client.api 命名空间（向后兼容，不推荐）。

client.api.executeSql<T>(sqlCode: string | number, params?: Record<string, any>): Promise<SqlExecuteResult<T>>

快速开始

基础调用（推荐方式）

import { createClient, sqlSafe } from "@lovrabet/sdk";

// 1. 创建客户端
const client = createClient({
  accessKey process.env.LOVRABET_ACCESS_KEY,
  appCode: "your-app-code",
});

// 2. 执行 SQL - 使用 sqlSafe 语法糖（推荐）
const { data, error } = await sqlSafe(() =>
  client.sql.execute({ sqlCode: "xxxxx-xxxxx" })
);

// 3. 处理结果（一次检查）
if (error) {
  console.error("查询失败:", error.message);
  return;
}

// data 直接是查询结果数组
console.log(`查询成功，返回 ${data.length} 条数据`);
data.forEach((row) => console.log(row));

传统方式（不推荐）

// 不使用 sqlSafe：需要手动检查 execSuccess
const result = await client.sql.execute({ sqlCode: "xxxxx-xxxxx" });

if (result.execSuccess && result.execResult) {
  console.log(`查询成功，返回 ${result.execResult.length} 条数据`);
  result.execResult.forEach((row) => console.log(row));
} else {
  console.error("SQL 执行失败");
}

参数化查询

// SQL 中使用 #{paramName} 定义参数
// 例如：SELECT * FROM users WHERE id = #{userId} AND status = #{status}

// 推荐方式：对象参数
const result = await client.sql.execute({
  sqlCode: "xxxxx-xxxxx",
  params: {
    userId: 123,
    status: "active",
  }
});

// 或直接传参
const result = await client.sql.execute("xxxxx-xxxxx", {
  userId: 123,
  status: "active",
});

if (result.execSuccess && result.execResult) {
  console.log("查询结果:", result.execResult);
}

TypeScript 类型支持

// 定义结果类型
interface UserStat {
  id: number;
  name: string;
  login_count: number;
}

// 使用 sqlSafe + 泛型
const { data, error } = await sqlSafe<UserStat>(() =>
  client.sql.execute({ sqlCode: "xxxxx-xxxxx" })
);

if (error) {
  console.error("查询失败:", error.message);
  return;
}

// data 是 UserStat[]，类型安全
data.forEach((user) => {
  console.log(`${user.name}: ${user.login_count} 次登录`);
});

错误处理

使用 sqlSafe（推荐）

import { sqlSafe } from "@lovrabet/sdk";

// 一次检查处理所有错误
const { data, error } = await sqlSafe(() =>
  client.sql.execute({ sqlCode: "xxxxx-xxxxx" })
);

if (error) {
  // 区分错误类型
  if (error.code === 'SQL_ERROR') {
    // 业务逻辑失败（execSuccess = false）
    console.error('SQL 执行失败:', error.cause);
  } else {
    // HTTP 错误（404、500 等）
    console.error('请求失败:', error.message, error.status);
  }
  return;
}

// data 直接是查询结果数组
console.log(`查询到 ${data.length} 条记录`);

区分错误类型

const { data, error } = await sqlSafe(() =>
  client.sql.execute({ sqlCode: 'user-stats' })
);

if (error) {
  // 业务错误：execSuccess = false
  if (error.code === 'SQL_ERROR') {
    const originalResult = error.cause;  // 原始 SqlExecuteResult
    console.error('业务失败:', originalResult);
  }
  // HTTP 错误：404、500 等
  else if (error.status) {
    console.error('HTTP 错误:', error.status, error.message);
  }
  // 其他错误
  else {
    console.error('未知错误:', error.message);
  }
  return;
}

// 使用数据
data.forEach(row => console.log(row));

常见错误码

错误码	说明	解决方案
401	认证失败	检查 AccessKey 或重新登录
404	SQL 不存在	检查 SQL Code 是否正确
500	服务器错误	稍后重试或联系技术支持

常见问题

execSuccess 为 false 是什么原因？

execSuccess: false 表示 SQL 在平台执行失败，常见原因：

• SQL 语法错误
• 引用的表或字段不存在
• SQL 参数传递错误或类型不匹配
• 数据库连接问题

解决方案：在平台的自定义 SQL 管理页面先测试 SQL 是否能正常执行。

如何调试 SQL 查询？

启用 SDK 调试模式：

const client = createClient({
  appCode: "your-app",
  accessKey: process.env.ACCESS_KEY,
  options: {
    debug: true, // 启用调试日志
  },
});

如何处理大数据量？

1. 在 SQL 中使用 LIMIT
2. 使用分页参数
3. 使用后台任务：对于大数据量处理，建议使用定时任务而非实时查询

支持哪些 SQL 操作？

• ✅ SELECT 查询：完全支持
• ⚠️ UPDATE/DELETE：部分支持（需要管理员权限配置）
• ❌ INSERT：不建议使用（请使用 Dataset API）
• ❌ DDL 操作：不支持（CREATE/DROP TABLE 等）

Backend Function 中的差异

如果你在 Lovrabet 平台的 Backend Function (BFF) 中使用 SQL，返回值结构与前端 SDK 不同：

返回值对比

环境	调用方式	返回值	数据获取方式
前端 SDK	client.sql.execute()	{ execSuccess, execResult }	需检查 execSuccess，从 execResult 取数据
Backend Function	context.client.sql.execute()	直接返回数组 [{ col: val }, ...]	直接使用结果，无 execResult 字段

Backend Function 用法示例

// BFF 环境中
export default async function myEndpoint(params, context) {
  // 直接返回数组，无需检查 execSuccess
  const rows = await context.client.sql.execute({
    sqlCode: "user-stats",
    params: { userId: params.userId }
  });

  // rows 就是查询结果数组
  return { data: rows };
}

⚠️ 注意区别BFF 中不存在 execResult 字段，以下写法是错误的：

错误处理

前端 SDK：检查 execSuccess 或使用 sqlSafe

const result = await client.sql.execute({ sqlCode: 'xxx' });
if (!result.execSuccess) {
  throw new Error('查询失败');
}

Backend Function：执行失败直接抛异常，用 try-catch 捕获

try {
  const rows = await context.client.sql.execute({ sqlCode: 'xxx' });
  return { data: rows };
} catch (error) {
  throw new Error(`查询失败: ${error.message}`);
}

相关文档

• 自定义 SQL 使用教程 - 完整的 step by step 教程
• 快速开始 - SDK 安装和配置
• 认证方式 - 三种认证模式详解
• API 使用指南 - Dataset API 参考
• 故障排查 - 常见问题解决

---

最后更新：2025-11-12