hogql-parser-rs

What it is and what it does

hogql_parser_rs is a Rust-based HogQL query parser that emits JSON AST output compatible with PostHog's C++ ANTLR reference parser. It exposes five PyO3 entry points (`parse_expr_json`, `parse_select_json`, `parse_program_json`, `parse_order_expr_json`, `parse_full_template_string_json`) that return JSON strings; parse errors are wrapped in an error envelope that PostHog's `posthog/hogql/json_ast.py` decodes into structured exceptions.

The parser is hand-rolled using Pratt + recursive descent techniques and deliberately maintains AST shape parity with the C++ parser to enable cross-validation. It ships as a compiled Python extension via maturin, targeting Python 3.12+ across Linux (x86_64/aarch64), macOS (arm64/x86_64), and musl-based systems. The implementation includes a lexer, expression parser with binding-power precedence, and per-rule parsing modules; the C++ ANTLR parser is treated as the source of truth for grammar and AST shape, making this a performance-optimized candidate implementation rather than an independent parser.

Use it for:

• Accelerate HogQL query parsing in PostHog analytics pipelines where parse latency is a bottleneck.
• Validate HogQL syntax and generate AST for query planning or optimization without invoking the C++ parser.
• Drive parser-parity fuzzing and regression testing via the coverage-instrumented build mode (`--features coverage`).
• Embed HogQL parsing in Python applications that need fast, deterministic query expression evaluation.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Parses HogQL query expressions into JSON AST format via a hand-rolled Rust parser, delivering 15–50× performance gains over the C++ ANTLR reference implementation.

Yes, if you are using PostHog and need faster HogQL parsing. The package is actively maintained, has no known vulnerabilities, and delivers substantial performance gains (15–50×) over the C++ reference. Install friction is moderate due to compiled wheels, but prebuilt binaries cover common platforms. The MIT license is permissive. Only caveat: you must run Python 3.12+, and the parser is designed as a PostHog internal tool—verify that your use case aligns with its role as a C++ parser candidate rather than a standalone HogQL implementation.

Install

hogql-parser-rs on PyPI

pip install hogql-parser-rs

uv add hogql-parser-rs

poetry add hogql-parser-rs

Installing hogql-parser-rs

Before you install

Medium install friction due to compiled Rust wheels; prebuilt binaries exist for Linux (x86_64/aarch64, manylinux 2_28 + musllinux 1_2) and macOS (arm64/x86_64), all targeting Python 3.12+. Active maintenance with recent releases.

License in practice

MIT license permits unrestricted use, modification, and distribution with minimal attribution requirements.

Quickstart

import hogql_parser_rs
result = hogql_parser_rs.parse_expr_json('1 + 2')
print(result)

Requires Python 3.12 or later; prebuilt wheels available for common platforms but local Rust toolchain needed if building from source.

Verify before relying

• Whether the parser handles all HogQL grammar features or only a subset of the C++ reference implementation.
• Performance benchmarks against the C++ parser on real-world PostHog query workloads beyond the synthetic `parse_expr` and `parse_select` tests.
• Stability guarantees for the JSON AST shape across minor version updates.

Package facts

Evidence: hogql_parser_rs-1.3.108-cp312-abi3-macosx_10_12_x86_64.whl; hogql_parser_rs-1.3.108-cp312-abi3-macosx_11_0_arm64.whl; hogql_parser_rs-1.3.108-cp312-abi3-manylinux_2_28_aarch64.whl; hogql_parser_rs-1.3.108-cp312-abi3-manylinux_2_28_x86_64.whl; hogql_parser_rs-1.3.108-cp312-abi3-musllinux_1_2_aarch64.whl; hogql_parser_rs-1.3.108-cp312-abi3-musllinux_1_2_x86_64.whl

Tags

More Text Processing packages