common/hogql_parser/README.md
ANTLR4-based parser for HogQL and Hog, available as both a Python C++ extension and a WebAssembly module for JavaScript/TypeScript.
| 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.
@posthog/hogql-parser)npm install @posthog/hogql-parser
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 ..."
}
| 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.
hogql_parser)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).
pip install ./common/hogql_parser
pip install ./common/hogql_parser
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/.