@dbsp/nql

NQL (Natural Query Language) — a human- and LLM-friendly pipe-based query language that compiles to IntentAST for @dbsp/core.

Installation

pnpm add @dbsp/nql

Quick Start

// doctest: skip — exec-only operation; compile from @dbsp/nql is not in doctest preamble and orm.from(intent).all() requires a real PostgreSQL connection
import { compile } from '@dbsp/nql';

// Compile an NQL query to IntentAST
const intent = compile(
  "users | where active = true | select name, email | order name asc | limit 20",
  schema
);

// Pass the intent to the ORM
const users = await orm.from(intent).all();

Syntax overview

-- Basic selection with filter
users | where status = 'active'

-- Computed columns and ordering
orders | select id, total, tax | order total desc | limit 10

-- Relations (auto-resolved from schema refs)
posts | include author | where published = true

-- CTEs (WITH clause)
with recent AS (orders | where createdAt > '2024-01-01')
recent | select id, total

-- Aggregation
orders | group customerId | select customerId, sum(total) as revenue

Key features

• Pipe syntax — Readable left-to-right data flow (table | filter | select | order)
• SQL-style literals — Single-quoted strings ('value'), not double-quoted
• CTE support — WITH name AS (subquery) for named subqueries
• Schema-aware — Validates column names and relation paths against ModelIR at parse time
• LLM-friendly — Concise syntax designed for AI-generated queries
• Chevrotain-based — Robust lexer + parser with structured error recovery
• Composable — Output IntentAST is the same type used by the TypeScript fluent builders

Documentation

• Guides
• Full-text search guide

License

MIT