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

   SELECT * FROM large_table LIMIT 1000

2. 使用分页参数

   const result = await client.sql.execute({
     sqlCode: "xxxxx-xxxxx",
     params: {
       offset: 0,
       limit: 100,
     }
   });

3. 使用后台任务：对于大数据量处理，建议使用定时任务而非实时查询

支持哪些 SQL 操作？

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

如何处理大数据量？

1. 在 SQL 中使用 LIMIT

   SELECT * FROM large_table LIMIT 1000

2. 使用分页参数

   const result = await client.api.executeSql("sqlCode", {
     offset: 0,
     limit: 100,
   });

3. 使用后台任务：对于大数据量处理，建议使用定时任务而非实时查询

相关文档

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

---

最后更新：2025-11-12