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 Parser 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 parameterized 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=prod*")

const columns = {
    status: newColumn("status", false, "UInt32", null),
    host: newColumn("host", false, "String", null),
}

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'

Note: PostgreSQL’s newColumn has a different signature — newColumn(name, type, values) (no jsonString parameter).

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, modifiers, and aliases:

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

// Parse basic columns (modifiers 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 modifiers via capabilities
const withMods = parse("message|chars(25) as msg, status", { modifiers: true })

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

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/editor	Web editor component (requires Vue 3)

What’s Next

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