跳到主要内容

SQL API

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