---
id: hogql-parser-rs
version: "1.3.108"
license: MIT
license_treatment: permissive
maintenance: active
---

# hogql-parser-rs — Hand-rolled Rust HogQL parser with C++-parity AST output

License: permissive · Maintenance: active · Downloads: 2.1M/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 2.1M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

HogQL parser, query expression parsing, Rust parser Python extension, AST JSON output, fast SQL-like parser, PostHog query parsing, parser, rust-extension, query-language

[View on SkillFed](https://skillfed.io/packages/hogql-parser-rs) · [View on PyPI](https://pypi.org/project/hogql-parser-rs/)