Python Quickstart

Installation

FlyQL for Python is available on PyPI:

pip install flyql

This installs the flyql package along with its dependency google-re2.

Requirements: Python 3.10+

Parse a Query

from flyql import parse

result = parse("status = 200 and active")
print(result.root)

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

Generate SQL

Use a generator to turn the AST into a WHERE clause. Each database dialect has its own generator.

ClickHouse

from flyql import parse
from flyql.generators.clickhouse.generator import to_sql_where
from flyql.generators.clickhouse.column import Column

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

columns = {
    "status": Column("status", "UInt32"),
    "host": Column("host", "String"),
}

sql = to_sql_where(result.root, columns)
print(sql)

PostgreSQL and StarRocks generators follow the same pattern — import from flyql.generators.postgresql or flyql.generators.starrocks instead.

Match In-Memory

Evaluate a query against a data record without generating SQL. Python does not ship a top-level match(query, data) helper (Go and JavaScript do) — use Evaluator directly:

from flyql import parse
from flyql.matcher import Evaluator, Record

result = parse("status = 200 and active")

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

evaluator = Evaluator()
matches = evaluator.evaluate(result.root, Record(data))
print(f"Matches: {matches}")  # True

Parse Column Expressions

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

from flyql.columns import parse, parse_to_json

# Parse basic columns (transformers disabled by default)
parsed = parse("message, status")
for col in parsed:
    print(f"{col.name} (display: {col.display_name!r}, segments: {col.segments})")

# Enable transformers via capabilities
with_transforms = parse(
    "message|chars(25) as msg, status", capabilities={"transformers": True}
)

# Or serialize directly to JSON for API responses
json_str = parse_to_json("message, status|upper", capabilities={"transformers": True})
print(json_str)

Parameterized Queries

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

from flyql import parse, bind_params
from flyql.generators.clickhouse.generator import to_sql_where
from flyql.generators.clickhouse.column import Column

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

# Bind concrete values to the parameters
bind_params(result.root, {"code": 200, "env": "prod"})

# Generate SQL
columns = {
    "status": Column("status", "Int32"),
    "env": Column("env", "String"),
}
sql = to_sql_where(result.root, columns)
print(sql)

See Parameters for the full reference.

Transformers in Queries

Parse a query with transformers and generate SQL:

from flyql import parse
from flyql.generators.clickhouse.generator import to_sql_where
from flyql.generators.clickhouse.column import Column

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

# Generate SQL for ClickHouse
columns = {"message": Column("message", "String")}
sql = to_sql_where(result.root, columns)
print(sql)  # equals(upper(message), 'ERROR')

See Transformers for the full syntax reference.

What’s Next

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