@polyglot-sql/sdk

Rust/Wasm-powered SQL transpiler for TypeScript. Parse, generate, transpile, format, and build SQL across more than 30 SQL dialects.

Part of the Polyglot project.

Installation

npm install @polyglot-sql/sdk
Copy

The npm package ships one full WASM build containing all supported dialects. Per-dialect subpath packages such as @polyglot-sql/sdk/clickhouse are not published. Rust/WASM consumers building from source can select individual dialects through the crate's Cargo features.

Quick Start

Transpile

import { transpile, Dialect } from '@polyglot-sql/sdk';

const result = transpile(
  'SELECT IFNULL(a, b) FROM t',
  Dialect.MySQL,
  Dialect.PostgreSQL,
);
console.log(result.sql[0]); // SELECT COALESCE(a, b) FROM t
Copy

Use unsupportedLevel: 'raise' when you want transpilation to fail instead of silently preserving known unsupported target-dialect constructs.

const strict = transpile(
  'SELECT ARRAY_AGG(x) FROM t',
  Dialect.PostgreSQL,
  Dialect.Fabric,
  { unsupportedLevel: 'raise' },
);

if (!strict.success) {
  console.error(strict.error);
}
Copy

Parse + Generate

import { parse, generate, Dialect } from '@polyglot-sql/sdk';

const result = parse('SELECT 1 + 2', Dialect.Generic);
if (!result.success) {
  throw new Error(result.error);
}

const generated = generate(result.ast, Dialect.PostgreSQL);
if (!generated.success || !generated.sql) {
  throw new Error(generated.error);
}

console.log(generated.sql[0]); // SELECT 1 + 2
Copy

Data Types

Parse and render standalone SQL data type fragments without wrapping them in a statement.

import {
  parseDataType,
  generateDataType,
  Dialect,
} from '@polyglot-sql/sdk';

const parsed = parseDataType('DECIMAL(10, 2)', Dialect.DuckDB);
if (parsed.success) {
  const rendered = generateDataType(parsed.dataType, Dialect.PostgreSQL);
  console.log(rendered.sql); // DECIMAL(10, 2)
}
Copy

generateDataType also accepts programmatically constructed data types. Named STRUCT, UNION, and structured OBJECT fields are rendered as identifiers: names such as field name or a"b are quoted and escaped for the target dialect. Existing delimited name strings remain supported. Parsed quoted field names use double-quote delimiters with doubled internal quotes in the AST; generation translates those delimiters to the target dialect. An empty struct field name continues to represent an anonymous field.

Format

import { format, Dialect } from '@polyglot-sql/sdk';

const { sql } = format('SELECT a,b FROM t WHERE x=1', Dialect.PostgreSQL);
console.log(sql[0]);
// SELECT
//   a,
//   b
// FROM t
// WHERE
//   x = 1
Copy

Format With Guard Options

Formatting guard defaults from Rust core:

• maxInputBytes: 16 * 1024 * 1024
• maxTokens: 1_000_000
• maxAstNodes: 1_000_000
• maxSetOpChain: 256

import { formatWithOptions, Dialect } from '@polyglot-sql/sdk';

const result = formatWithOptions(
  'SELECT a,b FROM t WHERE x=1',
  Dialect.PostgreSQL,
  {
    maxInputBytes: 2 * 1024 * 1024,
    maxTokens: 250_000,
    maxAstNodes: 250_000,
    maxSetOpChain: 128,
  },
);

if (!result.success) {
  // Includes one of:
  // E_GUARD_INPUT_TOO_LARGE
  // E_GUARD_TOKEN_BUDGET_EXCEEDED
  // E_GUARD_AST_BUDGET_EXCEEDED
  // E_GUARD_SET_OP_CHAIN_EXCEEDED
  console.error(result.error);
}
Copy

Fluent Query Builder

Build SQL queries programmatically with full type safety. All builder operations are backed by the Rust engine via WASM.

SQLGlot-Compatible Immutable API

An additive compat namespace provides immutable cross-language builder plans with familiar string coercion conventions. The existing TypeScript builder classes are adapters over the same plan and Rust engine.

import { compat } from '@polyglot-sql/sdk';
// Or: import * as compat from '@polyglot-sql/sdk/compat';

const base = compat
  .select('customer_id', 'COUNT(*) AS orders')
  .from_('orders')
  .where("status = 'complete'")
  .groupBy('customer_id');

const query = base.orderBy('orders DESC').limit(10);
console.log(query.sql('postgres'));
Copy

These expressions are immutable. The namespace and class facade share named function helpers, query clauses, all join and set-operation variants, windows, lateral views, hints, row locks, CTAS, CASE, and full DML including conditional MERGE. Repeated clauses append by default; pass { append: false } as the first argument to replace one.

SELECT

import { select, col, lit } from '@polyglot-sql/sdk';

const sql = select('id', 'name')
  .from('users')
  .where(col('age').gt(lit(18)))
  .orderBy(col('name').asc())
  .limit(10)
  .toSql('postgresql');

// SELECT id, name FROM users WHERE age > 18 ORDER BY name ASC LIMIT 10
Copy

Joins

const sql = select('u.id', 'o.total')
  .from('users')
  .join('orders', col('u.id').eq(col('o.user_id')))
  .leftJoin('addresses', col('u.id').eq(col('a.user_id')))
  .toSql();
Copy

GROUP BY / HAVING

const sql = select(col('dept'), count())
  .from('employees')
  .groupBy('dept')
  .having(count().gt(lit(5)))
  .toSql();
Copy

DISTINCT / QUALIFY

const sql = select('id', 'name')
  .from('users')
  .distinct()
  .qualify(col('rn').eq(lit(1)))
  .toSql('snowflake');
Copy

Expression Helpers

import { col, lit, star, sqlNull, boolean, table, sqlExpr, func } from '@polyglot-sql/sdk';

col('users.id');         // Column reference (supports dotted names)
lit('hello');            // String literal
lit(42);                 // Numeric literal
star();                  // *
sqlNull();               // NULL
boolean(true);           // TRUE
table('schema.users');   // Table reference
sqlExpr('x + 1');        // Raw SQL fragment
func('MY_FUNC', col('a'), lit(1));  // Function call
Copy

Expression Operators

import { col, lit } from '@polyglot-sql/sdk';

// Comparison
col('age').eq(lit(18));
col('age').neq(lit(0));
col('age').gt(lit(18));
col('age').gte(lit(18));
col('age').lt(lit(100));
col('age').lte(lit(100));

// Logical
col('a').and(col('b'));
col('a').or(col('b'));
col('a').not();
col('a').xor(col('b'));

// Arithmetic
col('price').mul(lit(1.1));
col('a').add(col('b'));

// Pattern matching
col('name').like(lit('%Alice%'));
col('name').ilike(lit('%alice%'));

// Predicates
col('email').isNull();
col('email').isNotNull();
col('age').between(lit(18), lit(65));
col('status').inList(lit('active'), lit('pending'));
col('status').notIn(lit('deleted'), lit('banned'));

// Transform
col('total').alias('grand_total');  // or .as('grand_total')
col('id').cast('TEXT');
col('name').asc();
col('name').desc();
Copy

Convenience Functions

import {
  // Aggregate
  count, countDistinct, sum, avg, min, max,
  // String
  upper, lower, length, trim, ltrim, rtrim, reverse, initcap,
  substring, replace, concatWs,
  // Null handling
  coalesce, nullIf, ifNull,
  // Math
  abs, round, floor, ceil, power, sqrt, ln, exp, sign, greatest, least,
  // Date/time
  currentDate, currentTime, currentTimestamp, extract,
  // Window
  rowNumber, rank, denseRank,
  // Logical
  and, or, not, cast, alias,
} from '@polyglot-sql/sdk';

// Examples
count();                          // COUNT(*)
countDistinct(col('id'));         // COUNT(DISTINCT id)
coalesce(col('a'), col('b'));     // COALESCE(a, b)
upper(col('name'));               // UPPER(name)
round(col('price'), lit(2));      // ROUND(price, 2)
extract('YEAR', col('created'));  // EXTRACT(YEAR FROM created)
Copy

CASE Expressions

import { caseWhen, caseOf, col, lit } from '@polyglot-sql/sdk';

// Searched CASE
const expr = caseWhen()
  .when(col('x').gt(lit(0)), lit('positive'))
  .when(col('x').eq(lit(0)), lit('zero'))
  .else_(lit('negative'))
  .build();

// Simple CASE
const expr2 = caseOf(col('status'))
  .when(lit('A'), lit('Active'))
  .when(lit('I'), lit('Inactive'))
  .else_(lit('Unknown'))
  .build();
Copy

INSERT

import { insertInto, lit, select } from '@polyglot-sql/sdk';

// INSERT ... VALUES
const sql = insertInto('users')
  .columns('id', 'name')
  .values(lit(1), lit('Alice'))
  .toSql();

// INSERT ... SELECT
const sql2 = insertInto('archive')
  .query(select('*').from('users').where(col('active').eq(lit(false))))
  .toSql();
Copy

UPDATE

import { update, col, lit } from '@polyglot-sql/sdk';

const sql = update('users')
  .set('name', lit('Bob'))
  .set('updated_at', sqlExpr('NOW()'))
  .where(col('id').eq(lit(1)))
  .toSql();
Copy

DELETE

import { deleteFrom, col, lit } from '@polyglot-sql/sdk';

const sql = deleteFrom('users')
  .where(col('id').eq(lit(1)))
  .toSql();
Copy

MERGE

import { mergeInto, col } from '@polyglot-sql/sdk';

const sql = mergeInto('target')
  .using('source', col('target.id').eq(col('source.id')))
  .whenMatchedUpdate({ name: col('source.name') })
  .whenNotMatchedInsert(
    ['id', 'name'],
    [col('source.id'), col('source.name')]
  )
  .toSql();
Copy

Set Operations

import { select, union, unionAll, intersect, except } from '@polyglot-sql/sdk';

const q1 = select('id').from('a');
const q2 = select('id').from('b');

union(q1, q2).toSql();
unionAll(q1, q2).orderBy(col('id').asc()).limit(10).toSql();
intersect(q1, q2).toSql();
except(q1, q2).toSql();
Copy

AST Visitor

Walk, search, and transform parsed AST nodes.

import { ast, Dialect, parse } from '@polyglot-sql/sdk';

const result = parse('SELECT a, b FROM t WHERE x > 1', Dialect.Generic);
if (!result.success) {
  throw new Error(result.error);
}

const statement = result.ast[0];

// Walk all nodes with visitor callbacks
ast.walk(statement, {
  enter: (node) => console.log('Entering:', node),
  column: (node) => console.log('Found column:', node),
});

// Search for nodes
const columns = ast.getColumns(statement);
const first = ast.findFirst(statement, (node) => ast.getExprType(node) === 'column');
const selects = ast.findByType(statement, 'select');

// Get names as strings
const colNames = ast.getColumnNames(statement);   // ['a', 'b', 'x']
const tableNames = ast.getTableNames(statement);  // ['t']

// Check for specific constructs
const hasAggs = ast.hasAggregates(statement);
const hasSubs = ast.hasSubqueries(statement);
const count = ast.nodeCount(statement);

// Transform AST nodes
const renamed = ast.renameColumns(statement, { a: 'alpha', b: 'beta' });
const renamedTables = ast.renameTables(statement, { t: 'users' });
const qualified = ast.qualifyColumns(statement, 'users');

// Modify query structure
const withLimit = ast.setLimit(statement, 100);
const withOffset = ast.setOffset(withLimit, 10);
const ordered = ast.setOrderBy(withOffset, columns[0]);
const distinct = ast.setDistinct(statement, true);
const noWhere = ast.removeWhere(statement);
Copy

Validation

Syntax Validation

import { validate } from '@polyglot-sql/sdk';

const result = validate('SELECT * FROM users', 'postgresql');
if (!result.valid) {
  for (const err of result.errors) {
    console.log(`${err.code}: ${err.message} (line ${err.line}, col ${err.column})`);
  }
}

const strictResult = validate('SELECT name, FROM employees', 'postgresql', {
  strictSyntax: true,
});
Copy

Semantic Validation

const result = validate('SELECT * FROM users', 'postgresql', { semantic: true });
// May also report warnings like "SELECT * is discouraged"
Copy

Syntax, strict-syntax checks, and semantic checks are computed by the Rust core in one WASM call. With semantic: true, invalid grouping (E230), aggregate placement/nesting (E231), and window placement/nesting (E232) make the result invalid, even with schema validation's strict: false. Quality hints W001-W004 remain warnings; W002 is reserved for uncertain grouping cases. Unknown schema and option fields are rejected, including nested schema metadata.

Schema Validation

import { validateWithSchema } from '@polyglot-sql/sdk';

const schema = {
  tables: [
    {
      name: 'users',
      columns: [
        { name: 'id', type: 'integer', primaryKey: true },
        { name: 'name', type: 'varchar' },
        { name: 'email', type: 'varchar', unique: true },
      ],
      primaryKey: ['id'],
      uniqueKeys: [['email']],
    },
    {
      name: 'orders',
      columns: [
        { name: 'id', type: 'integer', primaryKey: true },
        {
          name: 'user_id',
          type: 'integer',
          references: { table: 'users', column: 'id' },
        },
        { name: 'total', type: 'decimal' },
      ],
      foreignKeys: [
        {
          columns: ['user_id'],
          references: { table: 'users', columns: ['id'] },
        },
      ],
    },
  ],
};

const result = validateWithSchema(
  'SELECT id, total FROM orders',
  schema,
  'postgresql',
  {
    checkTypes: true,
    checkReferences: true,
    semantic: true,
  },
);
Copy

validateWithSchema supports:

• identifier checks (E200, E201) for unknown tables/columns
• optional type checks (checkTypes) for comparisons, predicates, arithmetic, assignments, and set operations
• optional reference checks (checkReferences) for schema FK integrity and query-level join/reference quality

Migration note: checkTypes and checkReferences are opt-in and default to false, so existing schema validation behavior stays backward-compatible until these options are enabled.

Common diagnostic codes:

Code	Meaning
E200	Unknown table
E201	Unknown column
E210-E217	Type incompatibilities (strict mode errors)
W210-W216	Type coercion warnings (non-strict mode)
E220	Invalid foreign key/reference metadata in schema
E221	Ambiguous unqualified column in multi-table scope
W220	Cartesian join warning
W221	JOIN predicate does not use declared FK relationship
W222	Weak reference integrity warning (non-strict mode)

// Ambiguous unqualified column in a join (E221 in strict mode)
const ambiguous = validateWithSchema(
  'SELECT id FROM users u JOIN orders o ON u.id = o.user_id',
  schema,
  'postgresql',
  { checkReferences: true },
);

// Cartesian join warning (W220)
const cartesian = validateWithSchema(
  'SELECT * FROM users u JOIN orders o',
  schema,
  'postgresql',
  { checkReferences: true },
);
Copy

Tokenize

Access the raw SQL token stream with full source position spans. Useful for syntax highlighting, custom linters, or editor integrations.

import { tokenize, Dialect } from '@polyglot-sql/sdk';

const result = tokenize('SELECT a, b FROM t', Dialect.Generic);
if (result.success) {
  for (const token of result.tokens!) {
    console.log(token.tokenType, token.text, token.span);
    // "Select" "SELECT" { start: 0, end: 6, line: 1, column: 1 }
    // "Var"    "a"      { start: 7, end: 8, line: 1, column: 8 }
    // ...
  }
}
Copy

Each token includes:

Field	Type	Description
tokenType	string	Token type name (e.g. "Select", "Var", "Comma")
text	string	Raw source text of the token
span	SpanInfo	Source position: start/end byte offsets, line/column (1-based)
comments	string[]	Leading comments attached to this token
trailingComments	string[]	Trailing comments attached to this token

Error Reporting

Parse, transpile, and tokenize errors include source position information with both line/column and byte offset ranges, making it easy to highlight errors in editors or show precise error messages.

import { parse, transpile, Dialect } from '@polyglot-sql/sdk';

const result = parse('SELECT 1 +', Dialect.Generic);
if (!result.success) {
  console.log(result.error);       // "Parse error at line 1, column 11: ..."
  console.log(result.errorLine);   // 1
  console.log(result.errorColumn); // 11
  console.log(result.errorStart);  // 10 (byte offset)
  console.log(result.errorEnd);    // 11 (byte offset, exclusive)
}
Copy

ParseResult, TranspileResult, and TokenizeResult include optional position fields:

Field	Type	Description
errorLine	number | undefined	1-based line number where the error occurred
errorColumn	number | undefined	1-based column number where the error occurred
errorStart	number | undefined	Start byte offset of the error range (0-based)
errorEnd	number | undefined	End byte offset of the error range (exclusive)

These fields are only present when success is false. On success, they are undefined.

// Use with transpile errors too
const result = transpile('SELECT FROM WHERE', Dialect.MySQL, Dialect.PostgreSQL);
if (!result.success) {
  // Pinpoint the exact location in the source SQL
  console.log(`Error at ${result.errorLine}:${result.errorColumn}: ${result.error}`);
}
Copy

Column Lineage

Trace how columns flow through SQL queries, from source tables to the result set.

import {
  lineage,
  lineageAt,
  lineageWithSchema,
  outputColumns,
  getSourceTables,
} from '@polyglot-sql/sdk';

// Trace a column through joins, CTEs, and subqueries
const result = lineage('total', 'SELECT o.total FROM orders o JOIN users u ON o.user_id = u.id');
if (result.success) {
  console.log(result.lineage.name);        // 'total'
  console.log(result.lineage.downstream);  // source nodes
}

// Schema-aware lineage (same schema format as validateWithSchema)
const schema = {
  tables: [
    { name: 'users', columns: [{ name: 'id', type: 'INT' }] },
    { name: 'orders', columns: [{ name: 'user_id', type: 'INT' }] },
  ],
};
const schemaLineage = lineageWithSchema(
  'id',
  'SELECT id FROM users u JOIN orders o ON u.id = o.user_id',
  schema,
);

// Inspect ordered outputs, including unnamed expressions and wildcards.
const output = outputColumns('SELECT 1, t.*, total FROM t');
// output.output.ordinalComplete === false

// Trace the second output slot even when set-operation branches use different
// names. Ordinals are zero-based.
const ordinalLineage = lineageAt(
  1,
  'SELECT id, total FROM current_orders UNION ALL SELECT key, amount FROM archive_orders',
);

if (!ordinalLineage.success && ordinalLineage.columnResolution) {
  console.log(ordinalLineage.columnResolution.reason);
  // 'not_found', 'indeterminate', or 'ambiguous'
}

// Get all source tables that contribute to a column
const tables = getSourceTables('total', 'SELECT o.total FROM orders o JOIN users u ON o.user_id = u.id');
if (tables.success) {
  console.log(tables.tables);  // ['orders']
}
Copy

Lineage nodes include source_kind and optional source_alias metadata. Table columns are marked as table, CTEs as cte, derived queries as derived_table, and virtual sources such as BigQuery UNNEST(...) AS alias are marked as virtual. Immediate set-operation branch roots also include optional set_branch metadata with the operator, original zero-based ordinal, and all flag. The ordinal remains stable when another branch cannot be resolved.

Compact Query Analysis

Use analyzeQuery when you need summary facts instead of the full AST or full lineage graph. relations contains sources visible in the analyzed scope; baseTables contains deduplicated physical dependencies across nested CTEs, derived tables, subqueries, and set-operation branches. With a schema, parseable detailed type strings such as DECIMAL(10,2) are preserved in projection typeHint values. cteFacts reports top-level CTE definitions, starProjections records original star projections and schema-expanded columns, and each projection includes conservative nullability: 'non_null', 'nullable', or 'unknown'. Types propagate through CTE and derived-table outputs. transformKind and castType describe the current projection, not transformations earlier in its lineage: a passthrough of a cast column is still direct, with the cast's result type in typeHint. Compact upstream references identify base dependencies; use the full lineage API to inspect intermediate CTEs and expressions. For set operations, typeHint describes the dialect's combined output type after positional or name alignment. For example, Snowflake INTEGER/FLOAT branches produce FLOAT. The combined castType is present only when every contributing branch explicitly casts to the same resolved type; branch facts retain their own casts. Unknown inputs, incompatible types, ambiguous layouts, and coercions that depend on unavailable engine settings leave typeHint unset. See set-operation typing for dialect rules and conservative limits. Each setOperations[].branches[] entry has a role: both UNION branches are 'value', while the right branch of EXCEPT and INTERSECT is 'filter'. For physical relation facts, name remains the qualified display name while catalog, schema, and table expose parsed identifier parts.

columnUses adds scoped facts for joins, filters (including aggregate FILTER), grouping, HAVING/QUALIFY, window keys/frames, ordering, and set-operation filter inputs. Each fact has context, scopePath, expressionPath, dialect-rendered expressionSql, and references. For example, SELECT o.id FROM orders o WHERE o.amount > 0 reports a filter use of orders.amount without adding it to the id projection's upstream references. Paths distinguish nested scopes and branches; they are not persistent IDs across query edits.

Optional span objects use half-open Unicode-character offsets into original SQL. To slice in JavaScript, use Array.from(sql).slice(start, end).join(''), not sql.slice(start, end). Reference spans locate occurrences, not upstream definitions; complete expression spans are omitted when unavailable. Repeated occurrences are retained. Uncertain ownership is ambiguous or unknown. The TypeScript columnUses property is optional only to accommodate older WASM runtimes; current builds always return an array.

import { analyzeQuery, Dialect } from '@polyglot-sql/sdk';

const result = analyzeQuery(
  'WITH base AS (SELECT id, amount FROM orders) SELECT * FROM base',
  {
    dialect: Dialect.Generic,
    schema: {
      tables: [
        {
          name: 'orders',
          columns: [
            { name: 'id', type: 'INT', nullable: false },
            { name: 'amount', type: 'DECIMAL(10,2)', nullable: true },
          ],
        },
      ],
    },
  },
);

if (result.success) {
  console.log(result.analysis.cteFacts[0].bodySql);                // 'SELECT id, amount FROM orders'
  console.log(result.analysis.starProjections[0].expandedColumns); // ['id', 'amount']
  console.log(result.analysis.projections[0].nullability);         // 'non_null'
  console.log(result.analysis.baseTables[0].name);                 // 'orders'
  console.log(result.analysis.baseTables[0].table);                // 'orders'
}

const duckdbSummary = analyzeQuery('SELECT 1', Dialect.DuckDB);
Copy

ValidationSchema objects use this shape:

const schema = {
  strict: true,
  tables: [
    {
      name: 'orders',
      schema: 'analytics',
      aliases: ['o'],
      primaryKey: ['id'],
      uniqueKeys: [['external_id']],
      foreignKeys: [
        {
          columns: ['customer_id'],
          references: { table: 'customers', columns: ['id'] },
        },
      ],
      columns: [
        { name: 'id', type: 'INT', nullable: false, primaryKey: true },
        { name: 'amount', type: 'DECIMAL(10,2)', nullable: true },
      ],
    },
  ],
};
Copy

Use the type key for column types. dataType / data_type are not accepted aliases in this payload.

OpenLineage Output

Generate OpenLineage-compatible JSON payloads from SQL analysis. The SDK only builds payloads; OpenLineage transport and client emission are intentionally out of scope.

Set-operation queries are supported. UNION inputs are emitted as direct dependencies; the right input of EXCEPT and INTERSECT is emitted as an indirect FILTER dependency. If the same input field has both roles, one input field contains both transformations.

import {
  openLineageColumnLineage,
  openLineageJobEvent,
  openLineageRunEvent,
} from '@polyglot-sql/sdk';

const options = {
  producer: 'https://github.com/tobilg/polyglot',
  datasetNamespace: 'postgres://warehouse',
  outputDataset: {
    namespace: 'postgres://warehouse',
    name: 'analytics.revenue',
  },
};

const columnLineage = openLineageColumnLineage(
  'SELECT order_id, amount * 100 AS amount_cents FROM raw.orders',
  options,
);

const runEvent = openLineageRunEvent('SELECT order_id FROM raw.orders', {
  ...options,
  jobNamespace: 'polyglot',
  jobName: 'orders_lineage',
  eventTime: '2026-05-18T00:00:00Z',
  runId: '3b452093-782c-4ef2-9c0c-aafe2aa6f34d',
  eventType: 'COMPLETE',
});
Copy

SQL Diff

Compare two SQL statements and get a list of edit operations using the ChangeDistiller algorithm.

import { diff, hasChanges, changesOnly } from '@polyglot-sql/sdk';

const result = diff(
  'SELECT a, b FROM t WHERE x > 1',
  'SELECT a, c FROM t WHERE x > 2',
);

if (result.success) {
  console.log(hasChanges(result.edits));     // true
  console.log(changesOnly(result.edits));    // only insert/remove/move/update edits

  for (const edit of result.edits) {
    // edit.type: 'insert' | 'remove' | 'move' | 'update' | 'keep'
    console.log(edit.type, edit.source, edit.target);
  }
}
Copy

Query Planner

Convert a SQL query into an execution plan represented as a DAG of steps.

import { plan } from '@polyglot-sql/sdk';

const result = plan('SELECT dept, SUM(salary) FROM employees GROUP BY dept');
if (result.success) {
  const { root, leaves } = result.plan;
  console.log(root.kind);       // 'aggregate'
  console.log(leaves[0].kind);  // 'scan'
  console.log(leaves[0].name);  // 'employees'
}
Copy

Class-Based API

For an object-oriented style, use the singleton Polyglot class:

import { Polyglot, Dialect } from '@polyglot-sql/sdk';

const pg = Polyglot.getInstance();
const result = pg.transpile('SELECT 1', Dialect.MySQL, Dialect.PostgreSQL);
const formatted = pg.format('SELECT a,b FROM t');
const dataType = pg.parseDataType('VARCHAR(255)', Dialect.DuckDB);
const formattedSafe = pg.formatWithOptions('SELECT a,b FROM t', Dialect.Generic, {
  maxInputBytes: 2 * 1024 * 1024,
  maxSetOpChain: 128,
});
Copy

API Reference

Core Functions

Function	Description
transpile(sql, read, write, options?)	Transpile SQL between dialects
parse(sql, dialect?)	Parse SQL into AST
generate(ast, dialect?)	Generate SQL from AST
parseDataType(sql, dialect?)	Parse one standalone SQL data type
generateDataType(dataType, dialect?)	Generate SQL from a parsed or constructed data type
format(sql, dialect?)	Pretty-print SQL
formatWithOptions(sql, dialect?, options?)	Pretty-print SQL with guard overrides
tokenize(sql, dialect?)	Tokenize SQL into a token stream with source spans
validate(sql, dialect?, options?)	Validate SQL syntax/semantics
validateWithSchema(sql, schema, dialect?, options?)	Validate against a database schema
getDialects()	List supported dialect names
getVersion()	Get library version

transpile accepts TranspileOptions with pretty, unsupportedLevel, maxUnsupported, and optional complexityGuard limits (maxParserDepth, maxInputBytes, maxTokens, maxAstNodes, maxAstDepth, maxParenthesisDepth, maxFunctionCallDepth) for recursion-heavy inputs.

maxParserDepth bounds logical nesting during parsing, before an AST exists. The shared Rust core uses a conservative default of 32 on WASM and 1024 on native targets because their available stacks differ. Omit it for the target's default, supply a nonnegative integer to override it, or use null to disable only that check. Zero rejects parsing descents. Other limits remain independent; maxAstDepth checks the constructed AST instead.

Raising or disabling this limit can permit resource exhaustion and native process termination or WASM traps. It does not increase stack space or establish a general time/memory budget. Overrides should be controlled by the application owner, not arbitrary SQL submitters. Parsing APIs without an options argument inherit the default protection.

This limit covers recursive parsing, not arbitrary programmatic AST construction or the stack use of later generation and traversal stages.

Analysis Functions

Function	Description
lineage(column, sql, dialect?, trimSelects?)	Trace column lineage through a query
lineageAt(ordinal, sql, dialect?, trimSelects?)	Trace a zero-based output ordinal
lineageAtWithSchema(ordinal, sql, schema, dialect?, trimSelects?)	Trace a zero-based output ordinal after schema expansion
lineageWithSchema(column, sql, schema, dialect?, trimSelects?)	Trace lineage with schema-based qualification
outputColumns(sql, dialect?)	Describe ordered outputs, unnamed slots, and unresolved wildcards
outputColumnsWithSchema(sql, schema, dialect?)	Describe ordered outputs after schema-aware wildcard expansion
getSourceTables(column, sql, dialect?)	Get source tables for a column
analyzeQuery(sql, optionsOrDialect?)	Return compact projection, visible relation, transitive base-table, CTE, set-operation, and upstream-reference facts
openLineageColumnLineage(sql, options)	Build an OpenLineage columnLineage facet and datasets
openLineageJobEvent(sql, options)	Build an OpenLineage JobEvent payload
openLineageRunEvent(sql, options)	Build an OpenLineage RunEvent payload
diff(source, target, dialect?, options?)	Diff two SQL statements
hasChanges(edits)	Check if diff has non-keep edits
changesOnly(edits)	Filter to only change edits
plan(sql, dialect?)	Build a query execution plan DAG

Expression Helpers

Function	Description
col(name)	Column reference
lit(value)	Literal value (string, number, boolean, null)
star()	Star (*) expression
sqlNull()	NULL literal
boolean(value)	Boolean literal
table(name)	Table reference
sqlExpr(sql)	Parse raw SQL fragment
condition(sql)	Alias for sqlExpr
func(name, ...args)	Function call
not(expr)	NOT expression
cast(expr, type)	CAST expression
alias(expr, name)	Alias expression
and(...conditions)	Chain with AND
or(...conditions)	Chain with OR

Query Builders

Builder	Constructor	Description
SelectBuilder	select(...cols)	SELECT queries
InsertBuilder	insertInto(table) / insert(table)	INSERT statements
UpdateBuilder	update(table)	UPDATE statements
DeleteBuilder	deleteFrom(table) / del(table)	DELETE statements
MergeBuilder	mergeInto(table)	MERGE statements
CaseBuilder	caseWhen() / caseOf(expr)	CASE expressions
SetOpBuilder	union() / unionAll() / intersect() / except()	Set operations

AST Walker

Function	Description
walk(node, visitor)	Walk all AST nodes with visitor callbacks
findAll(node, predicate)	Find nodes matching a predicate
findByType(node, type)	Find all nodes of a specific type
findFirst(node, predicate)	Find the first matching node
some(node, predicate)	Check if any node matches
every(node, predicate)	Check if all nodes match
countNodes(node, predicate)	Count nodes matching a predicate
getChildren(node)	Get direct children of a node
getColumns(node)	Get all column expression nodes
getTables(node)	Get all table expression nodes
getIdentifiers(node)	Get all identifier nodes
getFunctions(node)	Get all function call nodes
getAggregateFunctions(node)	Get all aggregate function nodes
getWindowFunctions(node)	Get all window function nodes
getSubqueries(node)	Get all subquery nodes
getLiterals(node)	Get all literal nodes
getColumnNames(node)	Get column names as strings
getTableNames(node)	Get table names as strings
hasAggregates(node)	Check for aggregate functions
hasWindowFunctions(node)	Check for window functions
hasSubqueries(node)	Check for subqueries
nodeCount(node)	Total number of AST nodes
getDepth(node)	Max depth of the AST tree
getParent(root, target)	Find parent of a node
findAncestor(root, target, predicate)	Find matching ancestor
getNodeDepth(root, target)	Depth of a specific node

AST Transformer

Function	Description
transform(node, config)	Immutable tree transformation with callbacks
replaceNodes(node, predicate, replacement)	Replace nodes matching a predicate
replaceByType(node, type, replacement)	Replace nodes of a specific type
renameColumns(node, mapping)	Rename columns in AST
renameTables(node, mapping)	Rename tables in AST
qualifyColumns(node, table)	Add table qualifier to columns
addWhere(node, condition, operator?)	Add/extend WHERE clause (AND/OR)
removeWhere(node)	Remove WHERE clause
addSelectColumns(node, ...columns)	Add columns to SELECT
removeSelectColumns(node, predicate)	Remove columns from SELECT
setLimit(node, limit)	Set LIMIT clause
setOffset(node, offset)	Set OFFSET clause
setOrderBy(node, orderBy)	Set ORDER BY clause
removeLimitOffset(node)	Remove LIMIT and OFFSET
setDistinct(node, distinct?)	Set SELECT DISTINCT
clone(node)	Deep clone AST
remove(node, predicate)	Remove nodes matching a predicate

Supported Dialects

Dialect	Enum Value
Athena	Dialect.Athena
BigQuery	Dialect.BigQuery
ClickHouse	Dialect.ClickHouse
CockroachDB	Dialect.CockroachDB
DataFusion	Dialect.DataFusion
SAP HANA	Dialect.HANA
Databricks	Dialect.Databricks
Doris	Dialect.Doris
Dremio	Dialect.Dremio
Drill	Dialect.Drill
Druid	Dialect.Druid
DuckDB	Dialect.DuckDB
Dune	Dialect.Dune
Exasol	Dialect.Exasol
Fabric	Dialect.Fabric
Generic SQL	Dialect.Generic
Hive	Dialect.Hive
Materialize	Dialect.Materialize
MySQL	Dialect.MySQL
Oracle	Dialect.Oracle
PostgreSQL	Dialect.PostgreSQL
Presto	Dialect.Presto
Redshift	Dialect.Redshift
RisingWave	Dialect.RisingWave
SingleStore	Dialect.SingleStore
Snowflake	Dialect.Snowflake
Solr	Dialect.Solr
Spark	Dialect.Spark
SQLite	Dialect.SQLite
StarRocks	Dialect.StarRocks
Tableau	Dialect.Tableau
Teradata	Dialect.Teradata
TiDB	Dialect.TiDB
Trino	Dialect.Trino
TSQL	Dialect.TSQL
Vertica	Dialect.Vertica

CDN Usage

For browser use without a bundler, load the CDN ESM build. It resolves ../polyglot_sql.wasm relative to dist/cdn/polyglot.esm.js, so self-hosted deployments must serve dist/polyglot_sql.wasm alongside the CDN bundle.

<script type="module">
  import polyglot from 'https://unpkg.com/@polyglot-sql/sdk/dist/cdn/polyglot.esm.js';
  // or: https://cdn.jsdelivr.net/npm/@polyglot-sql/sdk/dist/cdn/polyglot.esm.js

  const { transpile, Dialect } = polyglot;
  const result = transpile('SELECT 1', Dialect.MySQL, Dialect.PostgreSQL);
  console.log(result.sql);
</script>
Copy

CommonJS (CJS) Usage

For Node.js projects using require(), the SDK ships a CJS build. Since WASM cannot be loaded synchronously, you must call init() before using any other function:

const { init, transpile, parse, select, col, lit, isInitialized } = require('@polyglot-sql/sdk');

async function main() {
  await init();

  // Now all functions work
  const result = transpile('SELECT IFNULL(a, b)', 'mysql', 'postgresql');
  console.log(result.sql[0]); // SELECT COALESCE(a, b)

  const parsed = parse('SELECT 1', 'generic');
  console.log(parsed.success); // true

  const sql = select('id', 'name').from('users')
    .where(col('id').eq(lit(1)))
    .toSql();
  console.log(sql); // SELECT id, name FROM users WHERE id = 1
}

main();
Copy

You can check initialization status with isInitialized():

const { init, isInitialized } = require('@polyglot-sql/sdk');

console.log(isInitialized()); // false
await init();
console.log(isInitialized()); // true
Copy

Note: The ESM build (import) auto-initializes via top-level await, so init() is not required there. The CJS build requires it because require() is synchronous.

Bundler Configuration

The SDK publishes separate browser, Node, CommonJS, CDN, and manual-loader entry points. The default browser ESM build uses top-level await and a sibling polyglot_sql.wasm asset. Node ESM and CommonJS resolve the same asset from disk. For bundlers that do not copy WASM files from new URL(..., import.meta.url) references, use the manual entry point and import @polyglot-sql/sdk/polyglot_sql.wasm explicitly.

Vite

Vite works with the default SDK import and vite-plugin-wasm. This is the setup used by the Polyglot Playground:

// vite.config.ts
import { defineConfig } from 'vite';
import wasm from 'vite-plugin-wasm';

export default defineConfig({
  plugins: [wasm()],
  build: {
    target: 'esnext', // required for top-level await
  },
  optimizeDeps: {
    exclude: ['@polyglot-sql/sdk'], // prevent esbuild from pre-bundling WASM
  },
});
Copy

Application code can use the regular entry point:

import { transpile, Dialect } from '@polyglot-sql/sdk';
Copy

esbuild

esbuild does not copy WASM files referenced only through new URL(..., import.meta.url). Use the manual entry point and import the WASM asset directly:

import wasmUrl from '@polyglot-sql/sdk/polyglot_sql.wasm';
import { init, transpile, Dialect } from '@polyglot-sql/sdk/manual';

await init({ wasmUrl });

const result = transpile('SELECT IFNULL(a, b)', Dialect.MySQL, Dialect.PostgreSQL);
console.log(result.sql?.[0]);
Copy

Configure esbuild to emit the WASM file:

import * as esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/main.ts'],
  bundle: true,
  format: 'esm',
  platform: 'browser',
  target: 'es2022',
  outdir: 'dist',
  loader: {
    '.wasm': 'file',
  },
});
Copy

Next.js

Next.js uses webpack under the hood. Use the default SDK import and enable the WebAssembly experiments in the webpack config:

// next.config.js
module.exports = {
  webpack: (config) => {
    config.experiments = {
      ...config.experiments,
      asyncWebAssembly: true,
      topLevelAwait: true,
      layers: true,
    };
    return config;
  },
};
Copy

For production SSR builds, Next.js may emit .wasm files at a different path than where it tries to load them. A common workaround is to add a plugin that fixes the output path:

// next.config.js
class WasmChunksFixPlugin {
  apply(compiler) {
    compiler.hooks.thisCompilation.tap('WasmChunksFixPlugin', (compilation) => {
      compilation.hooks.processAssets.tap(
        { name: 'WasmChunksFixPlugin' },
        (assets) =>
          Object.entries(assets).forEach(([pathname, source]) => {
            if (!pathname.match(/\.wasm$/)) return;
            compilation.deleteAsset(pathname);
            const name = pathname.split('/')[1];
            const info = compilation.assetsInfo.get(pathname);
            compilation.emitAsset(name, source, info);
          })
      );
    });
  }
}

module.exports = {
  webpack: (config, { isServer, dev }) => {
    config.experiments = {
      ...config.experiments,
      asyncWebAssembly: true,
      topLevelAwait: true,
      layers: true,
    };
    if (!dev && isServer) {
      config.output.webassemblyModuleFilename = 'chunks/[id].wasm';
      config.plugins.push(new WasmChunksFixPlugin());
    }
    return config;
  },
};
Copy

webpack 5 (standalone)

Enable the required experiments in your webpack config:

// webpack.config.js
module.exports = {
  experiments: {
    asyncWebAssembly: true,
    topLevelAwait: true,
  },
  // ...
};
Copy

topLevelAwait is enabled by default since webpack 5.83.0. asyncWebAssembly must be set explicitly.

Node.js

ESM can use the default entry point. Node resolves the "node" export to a build that loads polyglot_sql.wasm from disk:

import { transpile, Dialect } from '@polyglot-sql/sdk';

const result = transpile('SELECT IFNULL(a, b)', Dialect.MySQL, Dialect.PostgreSQL);
console.log(result.sql?.[0]);
Copy

CommonJS requires explicit initialization because require() is synchronous:

const { init, transpile, Dialect } = require('@polyglot-sql/sdk');

await init();

const result = transpile('SELECT IFNULL(a, b)', Dialect.MySQL, Dialect.PostgreSQL);
console.log(result.sql?.[0]);
Copy

CDN

The CDN ESM build expects polyglot_sql.wasm to be served next to the package dist files:

<script type="module">
  import polyglot from 'https://unpkg.com/@polyglot-sql/sdk/dist/cdn/polyglot.esm.js';

  const result = polyglot.transpile('SELECT 1', polyglot.Dialect.Generic, polyglot.Dialect.PostgreSQL);
  console.log(result.sql[0]);
</script>
Copy

Troubleshooting

If you see missing WASM, undefined exports, or Node built-in resolution errors:

1. For browser builds, ensure the bundler resolves the "browser" or "import" export, not the CommonJS build.
2. For esbuild, use @polyglot-sql/sdk/manual with the @polyglot-sql/sdk/polyglot_sql.wasm asset export.
3. For webpack-based SSR frameworks, verify the emitted .wasm file is present in both client and server build outputs.
4. Keep the build target at ES2022 or newer so top-level await is preserved.

License

MIT