Skip to main content

SQL API Reference

v1.1.19+

The SQL API allows you to execute custom SQL queries configured on the Lovrabet platform.

Version Requirement

This feature is supported from SDK v1.1.19 onwards.

Beginner's Guide

If this is your first time using custom SQL, it's recommended to read the Custom SQL Tutorial first. This document serves as an API reference only.

When to Use SQL API?​

ScenarioRecommended API
Simple CRUD operationsDataset API
Cross-table join queriesSQL API ✅
Complex aggregation statisticsSQL API ✅
Custom reportsSQL API ✅

API Methods​

executeSql()​

Execute a custom SQL query configured on the platform.

Method Signature​

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

Parameters​

ParameterTypeRequiredDescription
sqlCodestring | number✅SQL code, format: "xxxxx-xxxxx" or numeric ID
paramsRecord<string, any>❌SQL parameter object for parameterized queries

Return Value​

interface SqlExecuteResult<T> {
  execSuccess: boolean; // Whether SQL execution succeeded
  execResult?: T[]; // Query result array (only present on success)
}
Important

The SDK returns an object containing execSuccess and execResult, not a direct array.

The application layer must check execSuccess before using execResult.

Quick Start​

Basic Usage​

import { LovrabetClient, AuthMode } from "@lovrabet/sdk";

// 1. Create client
const client = new LovrabetClient({
  authMode: AuthMode.AccessKey,
  accessKey: process.env.LOVRABET_ACCESS_KEY,
  appCode: "your-app-code",
});

// 2. Execute SQL
const result = await client.api.executeSql("xxxxx-xxxxx");

// 3. Process results
if (result.execSuccess && result.execResult) {
  console.log(`Query successful, returned ${result.execResult.length} records`);
  result.execResult.forEach((row) => {
    console.log(row);
  });
} else {
  console.error("SQL execution failed");
}

Parameterized Queries​

// Use #{paramName} to define parameters in SQL
// Example: SELECT * FROM users WHERE id = #{userId} AND status = #{status}

const result = await client.api.executeSql("xxxxx-xxxxx", {
  userId: 123,
  status: "active",
});

if (result.execSuccess && result.execResult) {
  console.log("Query results:", result.execResult);
}

TypeScript Type Support​

// Define result type
interface UserStat {
  id: number;
  name: string;
  login_count: number;
}

// Use generics
const result = await client.api.executeSql<UserStat>("xxxxx-xxxxx");

if (result.execSuccess && result.execResult) {
  result.execResult.forEach((user) => {
    console.log(`${user.name}: ${user.login_count} logins`);
  });
}

Error Handling​

Complete Error Handling​

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

try {
  const result = await client.api.executeSql("xxxxx-xxxxx");

  // Check business execution result
  if (!result.execSuccess) {
    console.error("SQL execution failed");
    return;
  }

  // Check if data exists
  if (!result.execResult || result.execResult.length === 0) {
    console.log("Query returned no results");
    return;
  }

  // Process successful result
  console.log(result.execResult);
} catch (error) {
  // Handle HTTP request errors
  if (error instanceof LovrabetError) {
    console.error("Request failed:", error.message);
    console.error("Error code:", error.code);
  } else {
    console.error("Unknown error:", error);
  }
}

Common Error Codes​

Error CodeDescriptionSolution
401Authentication failedCheck AccessKey or re-login
404SQL not foundCheck if SQL Code is correct
500Server errorRetry later or contact support

FAQ​

Why is execSuccess false?​

execSuccess: false indicates that the SQL execution failed on the platform. Common reasons:

  • SQL syntax error
  • Referenced table or field doesn't exist
  • SQL parameter passing error or type mismatch
  • Database connection issue

Solution: Test the SQL execution first on the platform's custom SQL management page.

How to debug SQL queries?​

Enable SDK debug mode:

const client = new LovrabetClient({
  appCode: "your-app",
  accessKey: process.env.ACCESS_KEY,
  debug: true, // Enable debug logging
});

Which SQL operations are supported?​

  • ✅ SELECT queries: Fully supported
  • ⚠️ UPDATE/DELETE: Partially supported (requires admin permission configuration)
  • ❌ INSERT: Not recommended (please use Dataset API)
  • ❌ DDL operations: Not supported (CREATE/DROP TABLE, etc.)

How to handle large datasets?​

  1. Use LIMIT in SQL

    SELECT * FROM large_table LIMIT 1000

  2. Use pagination parameters

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

  3. Use background tasks: For large data processing, use scheduled tasks instead of real-time queries

Last updated: 2025-11-12