Skip to content

: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.

3.0 KB
Raw Blame

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/.