Skip to main content

SQL Operations

The Boltic Tables SDK provides powerful SQL capabilities that allow you to interact with your database using natural language and execute complex queries. The SQL module transforms how you work with data by enabling natural language to SQL conversion and providing a streamlined interface for query execution with built-in safety measures and performance optimization.

import { createClient } from "@boltic/sdk";

const client = createClient("your-api-key");

// All SQL operations
const sqlOperations = client.sql;

What are SQL Operations?​

SQL operations in Boltic Tables provide comprehensive database interaction capabilities:

  • Text-to-SQL Conversion: Transform natural language descriptions into SQL queries using AI
  • Raw SQL Execution: Execute custom SQL queries with full control and safety measures
  • Query Optimization: Built-in performance optimization and automatic LIMIT handling
  • Result Streaming: Stream large query results efficiently

Key Concepts​

Natural Language to SQL​

The textToSQL function uses advanced AI to convert natural language prompts into executable SQL queries. This feature:

  • Understands Context: Analyzes your database schema and relationships
  • Generates Optimized Queries: Creates efficient SQL based on your data structure
  • Supports Refinement: Allows iterative improvement of generated queries
  • Streams Results: Provides real-time query generation for better user experience

Query Execution​

The executeSQL function provides a safe and efficient way to execute SQL queries:

  • Structured Results: Returns data in a consistent, predictable format
  • Pagination Support: Handles large result sets with built-in pagination
  • Default Limits: Automatically applies LIMIT 100 to SELECT queries for safety

Response Structure​

All SQL operations follow the Boltic API Response Structure:

interface SQLResponse {
    data: [
        Record<string, unknown>[], // Query result rows
        unknown, // Metadata (count, execution info, etc.)
    ];
    pagination?: {
        total_count: number;
        total_pages: number;
        current_page: number;
        per_page: number;
        type: string;
    };
    message?: string; // Optional message
}

Core Functions​

textToSQL​

Convert natural language descriptions into SQL queries with streaming support:

// Basic usage
const sqlStream = await client.sql.textToSQL("Show me all users from California");

// With query refinement
const refinedStream = await client.sql.textToSQL("Add ORDER BY clause and limit to 5 results", {
    currentQuery: "SELECT * FROM users WHERE state = 'CA'",
});

executeSQL​

Execute SQL queries and retrieve structured results:

// Execute a query
const result = await client.sql.executeSQL("SELECT * FROM users LIMIT 10");

// Access the data
const [rows, metadata] = result.data;
console.log(`Found ${rows.length} users`);