{"id":4564,"library":"hogql-parser","title":"HogQL Parser","description":"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.","status":"active","version":"1.3.37","language":"en","source_language":"en","source_url":"https://github.com/PostHog/posthog/tree/master/common/hogql_parser","tags":["parser","PostHog","HogQL","SQL","AST"],"install":[{"cmd":"pip install hogql-parser","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"Despite the PyPI package name, the core parsing functions are exposed via `posthog.hogql.parser`.","symbol":"parse_expr","correct":"from posthog.hogql.parser import parse_expr"},{"note":"Used for parsing full HogQL SELECT statements.","symbol":"parse_select","correct":"from posthog.hogql.parser import parse_select"},{"note":"Provides AST node types for programmatic query construction and manipulation.","symbol":"ast","correct":"from posthog.hogql import ast"}],"quickstart":{"code":"from posthog.hogql import ast\nfrom posthog.hogql.parser import parse_expr, parse_select\n\n# Parse a simple HogQL expression\nexpr_ast = parse_expr(\"event = 'pageview' AND properties.$browser = 'Chrome'\")\nprint(f\"Expression AST: {expr_ast}\")\n\n# Parse a full SELECT statement\nselect_ast = parse_select(\"SELECT event, timestamp FROM events WHERE timestamp > now() - INTERVAL 7 DAY LIMIT 10\")\nprint(f\"Select Statement AST: {select_ast}\")\n\n# Example with placeholders and constants (as shown in PostHog docs)\nnum_last_days = 2\nstmt_with_placeholder = parse_select(\n    \"SELECT event, timestamp FROM events WHERE {where} LIMIT 100\",\n    {\n        'where': parse_expr(\n            'timestamp > now() - INTERVAL {days} DAY',\n            {'days': ast.Constant(value=num_last_days)}\n        )\n    }\n)\nprint(f\"Select Statement with Placeholder AST: {stmt_with_placeholder}\")","lang":"python","description":"Demonstrates parsing a HogQL expression, a full SELECT statement, and using placeholders with AST constants to build queries."},"warnings":[{"fix":"Replace `count(field)` with `countDistinct(field)` in your HogQL queries.","message":"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.","severity":"breaking","affected_versions":"< 1.0.0 (PostHog internal beta prior to June 2023)"},{"fix":"Rely on this library with caution for external projects. Monitor PostHog's GitHub repository for changes if integrating deeply.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your deployment environment matches a supported platform for prebuilt wheels, or be prepared to handle C++ compilation toolchains.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Keep informed about PostHog's official HogQL documentation and announcements for potential changes.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Regularly review PostHog's schema documentation and test your HogQL queries against new PostHog versions.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}