Skip to main content

​
Core API Reference

Complete API documentation for the Text2SQL core classes.

​
Text2Sql Class

The main class for natural language to SQL conversion.

​
Constructor

new Text2Sql(config: Text2SqlConfig)

​
Text2SqlConfig

interface Text2SqlConfig {
  // Required
  version: string;               // Schema version for cache invalidation
  model: AgentModel;            // AI model from Vercel AI SDK
  adapter: Adapter;              // Database adapter
  store: ContextStore;          // Context storage
  
  // Optional
  teachingsOptions?: TeachingsOptions;
  tools?: Record<string, Tool>;  // Additional tools
  transform?: StreamTextTransform | StreamTextTransform[];
  filesystem?: IFileSystem;      // File system implementation
}

​
TeachingsOptions

interface TeachingsOptions {
  date?: 'strict' | false;  // Date clarification behavior
  fragments?: ContextFragment[];  // Custom teachables
}

​
Methods

​
toSql()

Generate SQL from natural language: 
async toSql(input: string): Promise<string>
Parameters:
  • input - Natural language question
Returns:
  • Promise resolving to SQL query string
Example: 
const sql = await text2sql.toSql('Show me top 10 customers by revenue');
console.log(sql);
// SELECT * FROM customers ORDER BY total_revenue DESC LIMIT 10

​
chat()

Start or continue a conversational session: 
async chat(
  messages: ChatMessage[],
  options?: ChatOptions
): Promise<UIMessageStream>
Parameters:
  • messages - Array of chat messages
  • options - Optional chat configuration
ChatMessage: 
interface ChatMessage {
  role: 'user' | 'assistant';
  content: string;
  id?: string;
  metadata?: Record<string, unknown>;
}
ChatOptions: 
interface ChatOptions {
  chatId?: string;          // Conversation ID
  userId?: string;          // User ID
  abortSignal?: AbortSignal;  // For cancellation
}
Returns:
  • Promise resolving to UIMessageStream
Example: 
const stream = await text2sql.chat([
  { role: 'user', content: 'Show me all customers' }
], {
  chatId: 'conversation-123',
  userId: 'user-456'
});

for await (const chunk of stream) {
  if (chunk.type === 'text') {
    console.log(chunk.content);
  }
}

​
index()

Manually trigger database introspection: 
async index(): Promise<ContextFragment[]>
Returns:
  • Promise resolving to array of context fragments
Example: 
const schemaFragments = await text2sql.index();
console.log(schemaFragments);

​
toPairs()

Generate training data pairs using a producer factory: 
async toPairs<T extends PairProducer>(
  factory: (adapter: Adapter) => T
): Promise<ExtractedPair[]>
Parameters:
  • factory - Function that creates a pair producer
Returns:
  • Promise resolving to array of question-SQL pairs
Example: 
import { SqlExtractor } from '@deepagents/text2sql/synthesis';

const sqls = [
  'SELECT * FROM customers WHERE status = "active"',
  'SELECT COUNT(*) FROM orders WHERE created_at >= NOW() - INTERVAL 7 DAY'
];

const pairs = await text2sql.toPairs(
  (adapter) => new SqlExtractor(sqls, adapter, { validateSql: true })
);

console.log(pairs);
// [
//   { question: "Show active customers", sql: "SELECT * FROM customers WHERE status = 'active'" },
//   { question: "Count orders from last week", sql: "SELECT COUNT(*) ..." }
// ]

​
Adapter Abstract Class

Base class for all database adapters.

​
Abstract Properties

abstract class Adapter {
  abstract readonly grounding: GroundingFn[];
  abstract readonly formatterLanguage: SqlLanguage;
  abstract readonly defaultSchema: string | undefined;
  abstract readonly systemSchemas: string[];
}

​
Abstract Methods

​
execute()

abstract execute(sql: string): Promise<any[]> | any[];
Execute SQL and return results.

​
validate()

abstract validate(sql: string): Promise<string | void> | string | void;
Validate SQL without executing. Returns error message or void.

​
runQuery()

abstract runQuery<Row>(sql: string): Promise<Row[]> | Row[];
Run introspection query.

​
quoteIdentifier()

abstract quoteIdentifier(name: string): string;
Quote identifier (table/column name) for safe use in SQL. Examples: 
// PostgreSQL, SQLite
adapter.quoteIdentifier('my_table');  // "my_table"

// SQL Server
adapter.quoteIdentifier('my_table');  // [my_table]

// MySQL, BigQuery
adapter.quoteIdentifier('my_table');  // `my_table`

​
escape()

abstract escape(value: string): string;
Escape string value for safe use in SQL.

​
buildSampleRowsQuery()

abstract buildSampleRowsQuery(
  tableName: string,
  columns: string[] | undefined,
  limit: number
): string;
Build a SELECT query to sample rows from a table.

​
Concrete Methods

​
introspect()

async introspect(ctx?: GroundingContext): Promise<ContextFragment[]>
Introspect database schema and return context fragments.

​
format()

format(sql: string): string
Format SQL according to database dialect. Example: 
const formatted = adapter.format(
  'SELECT * FROM customers WHERE status="active"'
);

console.log(formatted);
// SELECT
//   *
// FROM
//   customers
// WHERE
//   status = 'active'

​
toNumber()

toNumber(value: unknown): number | undefined
Convert unknown database value to number.

​
parseTableName()

parseTableName(name: string): { schema: string; table: string }
Parse qualified table name into schema and table parts.

​
escapeString()

escapeString(value: string): string
Escape string value for use in SQL string literals.

​
Types

​
Table

interface Table {
  name: string;
  schema?: string;
  rawName?: string;
  columns: Column[];
  rowCount?: number;
  sizeHint?: 'tiny' | 'small' | 'medium' | 'large' | 'huge';
  indexes?: TableIndex[];
  constraints?: TableConstraint[];
}

​
Column

interface Column {
  name: string;
  type: string;
  kind?: 'LowCardinality' | 'Enum';
  values?: string[];
  isIndexed?: boolean;
  stats?: ColumnStats;
}

​
ColumnStats

interface ColumnStats {
  min?: string;
  max?: string;
  nullFraction?: number;      // 0.0 to 1.0
  nDistinct?: number;         // Estimated distinct values
  correlation?: number;       // -1.0 to 1.0 (PostgreSQL)
}

​
Relationship

interface Relationship {
  table: string;
  from: string[];              // Source columns
  referenced_table: string;
  to: string[];                // Target columns
}

​
ExtractedPair

interface ExtractedPair {
  question: string;
  sql: string;
  metadata?: Record<string, unknown>;
}

​
Utility Functions

​
toTeachings()

Auto-generate teachables from schema: 
async function toTeachings(
  input: { schema: string; context?: string },
  options?: GenerateToTeachingsOptions
): Promise<ContextFragment[]>
Parameters:
  • input.schema - Schema as string (JSON or text)
  • input.context - Optional additional context
  • options.model - Optional AI model (default: groq)
Returns:
  • Promise resolving to teachable fragments
Example: 
import { toTeachings } from '@deepagents/text2sql';

const fragments = await text2sql.index();
const teachables = await toTeachings({
  schema: JSON.stringify(fragments),
  context: 'E-commerce database'
});

console.log(teachables);
// [
//   term('SKU', 'stock keeping unit'),
//   hint('status uses lowercase values'),
//   guardrail({ rule: 'Never expose credit_card column' })
// ]

​
Next Steps

Teachables API

Teachable fragment types

Adapters API

Adapter interface details

Build docs developers (and LLMs) love

Get started for freeTalk to us