:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
HogQL Parser
ANTLR4-based parser for HogQL and Hog, available as both a Python C++ extension and a WebAssembly module for JavaScript/TypeScript.
Packages
| Package | Runtime | Registry |
|---|---|---|
hogql_parser |
CPython (native C++ extension) | PyPI |
@posthog/hogql-parser |
Any JS environment (WebAssembly) | npm |
Both packages share the same C++ parser core and ANTLR4 grammar, so they produce identical ASTs.
npm package (@posthog/hogql-parser)
Installation
npm install @posthog/hogql-parser
Usage
import createHogQLParser from '@posthog/hogql-parser'
const parser = await createHogQLParser()
// Parse a HogQL expression
const exprAST = JSON.parse(parser.parseExpr('1 + 2'))
// Parse a SELECT statement
const selectAST = JSON.parse(parser.parseSelect('SELECT event FROM events WHERE timestamp > now()'))
// Parse a Hog program
const programAST = JSON.parse(parser.parseProgram('let x := 42; return x;'))
All parse functions return JSON strings. On failure they return a JSON error object instead of throwing:
const result = JSON.parse(parser.parseExpr('!!!'))
if ('error' in result) {
console.error(result.type, result.message) // e.g. "SyntaxError ..."
}
API
| Method | Description |
|---|---|
parseExpr(input, isInternal?) |
Parse a HogQL expression |
parseSelect(input, isInternal?) |
Parse a SELECT statement |
parseOrderExpr(input, isInternal?) |
Parse an ORDER BY expression |
parseProgram(input, isInternal?) |
Parse a Hog program |
parseFullTemplateString(input, isInternal?) |
Parse a template string (f'...') |
parseStringLiteralText(input) |
Unquote a string literal |
Setting isInternal to true omits position information from the AST.
Python package (hogql_parser)
Installation
pip install hogql_parser
The Python package is a native C++ extension and requires a platform with prebuilt wheels (macOS and Linux, x86_64 and arm64).
Local development
pip install ./common/hogql_parser
Building from source
Python
pip install ./common/hogql_parser
WebAssembly
Requires the Emscripten toolchain and Ninja.
cd common/hogql_parser
npm run build
This compiles the parser to WASM and places the output in dist/.