JavaScript Quickstart

Installation

npm install flyql

Requirements: Node.js 16+. All imports use ES modules.

Parse a Query

import { parse } from 'flyql'

const result = parse("status = 200 and active")
console.log(result.root)

parse() returns a ParseResult object with a root node representing the AST. It throws a ParserError on invalid input:

import { parse, ParserError } from 'flyql'

try {
    const result = parse("status = 200 and active")
    console.log(result.root)
} catch (err) {
    if (err instanceof ParserError) {
        console.error(`Parse error: ${err.message}`)
    }
}

Generate SQL

Use a generator to turn the AST into a WHERE clause. Each database dialect is a separate subpath import.

ClickHouse

import { parse } from 'flyql'
import { generateWhere, newColumn } from 'flyql/generators/clickhouse'

const result = parse("status >= 400 and host like 'prod%'")

const columns = {
    status: newColumn({ name: 'status', type: 'UInt32' }),
    host: newColumn({ name: 'host', type: 'String' }),
}

const sql = generateWhere(result.root, columns)
console.log(sql)

Other Dialects

PostgreSQL and StarRocks generators follow the same pattern:

import { generateWhere, newColumn } from 'flyql/generators/postgresql'
import { generateWhere, newColumn } from 'flyql/generators/starrocks'

All three dialect newColumn factories share the same options-object shape: newColumn({ name, type, values? }). Columns that store JSON in a text/varchar field are declared with type: "jsonstring".

Match In-Memory

Evaluate a query against a data record without generating SQL:

import { match } from 'flyql/matcher'

const data = {
    status: 200,
    active: true,
    host: "prod-api-01",
}

const matches = match("status = 200 and active", data)
console.log(`Matches: ${matches}`) // true

Parse Column Expressions

Parse a columns expression into structured data with segments, transformers, and aliases:

import { parse, parseToJson } from 'flyql/columns'

// Parse basic columns (transformers disabled by default)
const parsed = parse("message, status")
for (const col of parsed) {
    console.log(`${col.name} (display: ${JSON.stringify(col.displayName)}, segments: ${col.segments})`)
}

// Enable transformers via capabilities
const withTransforms = parse("message|chars(25) as msg, status", { transformers: true })

// Or serialize directly to JSON for API responses
const json = parseToJson("message, status|upper", { transformers: true })
console.log(json)

Parameterized Queries

Use $name and $1 placeholders, then resolve them at runtime with bindParams():

import { parse, bindParams } from 'flyql'
import { generateWhere, newColumn } from 'flyql/generators/clickhouse'

// Parse a query with parameter placeholders
const result = parse("status = $code and env in [$env, 'staging']")

// Bind concrete values to the parameters
bindParams(result.root, { code: 200, env: 'prod' })

// Generate SQL
const columns = {
    status: newColumn({ name: 'status', type: 'Int32' }),
    env: newColumn({ name: 'env', type: 'String' }),
}
const sql = generateWhere(result.root, columns)
console.log(sql)

See Parameters for the full reference.

Transformers in Queries

Parse a query with transformers and generate SQL:

import { parse } from 'flyql'
import { generateWhere, newColumn } from 'flyql/generators/clickhouse'

// Parse a transformer query
const result = parse("message|upper = 'ERROR'")

// Generate SQL for ClickHouse
const columns = { message: newColumn({ name: 'message', type: 'String' }) }
const sql = generateWhere(result.root, columns)
console.log(sql) // equals(upper(message), 'ERROR')

See Transformers for the full syntax reference.

Available Subpath Imports

Import Path	Contents
flyql	Core parser (parse, ParserError, operators, constants)
flyql/core	Core parser module directly
flyql/columns	Column expression parser
flyql/generators/clickhouse	ClickHouse SQL generator
flyql/generators/postgresql	PostgreSQL SQL generator
flyql/generators/starrocks	StarRocks SQL generator
flyql/matcher	In-memory record matcher
flyql/transformers	Transformer registry and built-ins
flyql/highlight	HTML syntax highlighter (wraps tokenize)
flyql/tokenize	Pure tokenizer primitive — flat typed tokens for custom formatters

What’s Next

• Syntax Reference — all operators, boolean logic, patterns, and more