HogQL Parser

1.3.37 · active · verified Sun Apr 12

HogQL parser is an ANTLR4-based parser for HogQL and Hog, primarily developed for internal use within the PostHog analytics platform. HogQL itself is a SQL-like query language for PostHog, acting as a translation layer over ClickHouse SQL with custom enhancements for event and person data. The `hogql-parser` package provides a Python C++ extension to convert HogQL strings into Abstract Syntax Tree (AST) nodes. While available on PyPI at version 1.3.37, its development is tightly coupled with PostHog's rapid, often bi-weekly, release cadence, meaning its API can evolve with PostHog's internal needs.

Warnings

breaking The `count(thing)` aggregation was renamed to `countDistinct(thing)` for better alignment with SQL and to differentiate from other count functions. Early adopters of HogQL will need to update their queries.
Fix: Replace `count(field)` with `countDistinct(field)` in your HogQL queries.
gotcha This library is primarily 'for internal PostHog use,' and its accompanying documentation often states it's 'intended only for development of PostHog itself.' External users should be aware that API stability might not be guaranteed and breaking changes could occur without explicit deprecation warnings typically found in public-facing APIs.
Fix: Rely on this library with caution for external projects. Monitor PostHog's GitHub repository for changes if integrating deeply.
gotcha The Python package is a native C++ extension and currently requires prebuilt wheels for macOS and Linux (x86_64 and arm64). Installation on other platforms or architectures may fail or require building from source, which can be complex.
Fix: Ensure your deployment environment matches a supported platform for prebuilt wheels, or be prepared to handle C++ compilation toolchains.
gotcha HogQL was launched as a public beta in June 2023. While the parser itself may be stable, the broader HogQL language features, behavior, and API response formats (if interacting with the PostHog API) may still be subject to changes.
Fix: Keep informed about PostHog's official HogQL documentation and announcements for potential changes.
gotcha The underlying HogQL database schema, which informs how queries are structured, is described as 'in flux.' This means queries relying on specific table or field names might require adjustments as the schema evolves.
Fix: Regularly review PostHog's schema documentation and test your HogQL queries against new PostHog versions.

Install

pip install hogql-parser Install latest version

Imports

parse_expr
```
from posthog.hogql.parser import parse_expr
```
Despite the PyPI package name, the core parsing functions are exposed via `posthog.hogql.parser`.
parse_select
```
from posthog.hogql.parser import parse_select
```
Used for parsing full HogQL SELECT statements.
ast
```
from posthog.hogql import ast
```
Provides AST node types for programmatic query construction and manipulation.

Quickstart

Demonstrates parsing a HogQL expression, a full SELECT statement, and using placeholders with AST constants to build queries.

from posthog.hogql import ast
from posthog.hogql.parser import parse_expr, parse_select

# Parse a simple HogQL expression
expr_ast = parse_expr("event = 'pageview' AND properties.$browser = 'Chrome'")
print(f"Expression AST: {expr_ast}")

# Parse a full SELECT statement
select_ast = parse_select("SELECT event, timestamp FROM events WHERE timestamp > now() - INTERVAL 7 DAY LIMIT 10")
print(f"Select Statement AST: {select_ast}")

# Example with placeholders and constants (as shown in PostHog docs)
num_last_days = 2
stmt_with_placeholder = parse_select(
    "SELECT event, timestamp FROM events WHERE {where} LIMIT 100",
    {
        'where': parse_expr(
            'timestamp > now() - INTERVAL {days} DAY',
            {'days': ast.Constant(value=num_last_days)}
        )
    }
)
print(f"Select Statement with Placeholder AST: {stmt_with_placeholder}")

view raw JSON →