Install & Compatibility
Where this runs
tested against v1.3.84 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.11
✕ build_error
✓ 2.3s
py 3.12
✕ build_error
✓ 2.4s
py 3.13
✕ build_error
✓ 1.9s
py 3.9
✕ build_error
✕ build_error
38MB installed
● package 38MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse_expr
✓ from hogql_parser.libs import parse_expr
✗ from hogql_parser.libs import parse_expr
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}")
Debug
Known issues
breakingThe `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.fixReplace `count(field)` with `countDistinct(field)` in your HogQL queries.
affects: < 1.0.0 (PostHog internal beta prior to June 2023)
gotchaThis 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.fixRely on this library with caution for external projects. Monitor PostHog's GitHub repository for changes if integrating deeply.
affects: All versions
gotchaThe 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.fixEnsure your deployment environment matches a supported platform for prebuilt wheels, or be prepared to handle C++ compilation toolchains.
affects: All versions
gotchaHogQL 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.fixKeep informed about PostHog's official HogQL documentation and announcements for potential changes.
affects: All versions
gotchaThe 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.fixRegularly review PostHog's schema documentation and test your HogQL queries against new PostHog versions.
affects: All versions
Upgrade
Version history
1.3.84latest on PyPI · released Aug 17, 2026
Audit
Dependencies
No dependency data recorded yet.