hogql-parser

What it is and what it does

HogQL Parser is a native C++ extension for Python that parses HogQL query expressions, SELECT statements, and Hog programs into abstract syntax trees. It wraps an ANTLR4-based parser shared with a WebAssembly version for JavaScript. The package is designed for internal PostHog use and supports Python 3.10 through 3.13 on macOS and Linux platforms.

The parser accepts HogQL syntax—a SQL-like query language—and produces structured ASTs that can be consumed by downstream tools. It has no runtime dependencies and installs via prebuilt wheels for supported architectures, though Windows is not supported. The package is actively maintained and has seen recent releases.

Use it for:

• Parse HogQL expressions in PostHog analytics pipelines to validate or transform user queries
• Build development tools or IDE plugins that need to understand HogQL syntax and structure
• Integrate HogQL query parsing into backend services running on Linux or macOS infrastructure
• Generate ASTs for query optimization or analysis in analytics platforms

Worth the install?

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

Parses HogQL query expressions and Hog programs into abstract syntax trees, available as a native C++ extension for Python on macOS and Linux.

Yes, if you are building on PostHog or need to parse HogQL syntax on macOS or Linux. The package is actively maintained, has no known vulnerabilities, uses a permissive MIT license, and ranks in the top 5000 PyPI packages by downloads. Install friction is moderate due to platform and architecture constraints—Windows users cannot use it. Verify that the Python API matches your needs before committing.

Install

hogql-parser on PyPI

pip install hogql-parser

uv add hogql-parser

poetry add hogql-parser

Installing hogql-parser

Before you install

Medium install friction due to platform-specific prebuilt wheels; requires macOS or Linux with x86_64 or arm64 architecture. Active maintenance with recent releases and no known vulnerabilities.

License in practice

MIT license permits unrestricted use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart

pip install hogql_parser

from hogql_parser import parse_expr

ast = parse_expr('1 + 2')
print(ast)

Requires macOS or Linux; Windows is not supported. Python 3.10 or later required.

Verify before relying

• Exact API surface and return types for Python parse functions (description shows npm API but Python equivalents not detailed)
• Whether parse functions return JSON strings or native Python objects in the Python package
• Error handling behavior in Python (whether errors are raised or returned as objects like the npm version)

Package facts

Evidence: hogql_parser-1.3.83-cp310-cp310-macosx_14_0_arm64.whl; hogql_parser-1.3.83-cp310-cp310-macosx_15_0_x86_64.whl; hogql_parser-1.3.83-cp310-cp310-manylinux_2_28_aarch64.whl; hogql_parser-1.3.83-cp310-cp310-manylinux_2_28_x86_64.whl; hogql_parser-1.3.83-cp311-cp311-macosx_14_0_arm64.whl; hogql_parser-1.3.83-cp311-cp311-macosx_15_0_x86_64.whl; hogql_parser-1.3.83-cp311-cp311-manylinux_2_28_aarch64.whl; hogql_parser-1.3.83-cp311-cp311-manylinux_2_28_x86_64.whl; hogql_parser-1.3.83-cp312-cp312-macosx_14_0_arm64.whl; hogql_parser-1.3.83-cp312-cp312-macosx_15_0_x86_64.whl; hogql_parser-1.3.83-cp312-cp312-manylinux_2_28_aarch64.whl; hogql_parser-1.3.83-cp312-cp312-manylinux_2_28_x86_64.whl; hogql_parser-1.3.83-cp313-cp313-macosx_14_0_arm64.whl; hogql_parser-1.3.83-cp313-cp313-macosx_15_0_x86_64.whl; hogql_parser-1.3.83-cp313-cp313-manylinux_2_28_aarch64.whl; hogql_parser-1.3.83-cp313-cp313-manylinux_2_28_x86_64.whl

Tags

More Text Processing packages