feat(hogql): add native compiler frontend

core/docker/Dockerfile

@@ -50,6 +50,20 @@ RUN \
 FROM registry.access.redhat.com/hi/core-runtime:latest
 ARG JDK_VERSION
 ARG ARCH
+ARG TRINO_SOURCE_REVISION
+ARG HOGQL_LANGUAGE_VERSION
+ARG HOGQL_CATALOG_PROTOCOL_VERSION
+ARG HOGQL_CATALOG_SCHEMA_VERSION
+ARG TRINO_SERVER_SHA256
+ARG TRINO_CLI_SHA256
+LABEL org.opencontainers.image.revision="${TRINO_SOURCE_REVISION}" \
+      io.posthog.trino.ducklake.revision="${TRINO_SOURCE_REVISION}" \
+      io.posthog.trino.hogql.compiler-build="${TRINO_SOURCE_REVISION}" \
+      io.posthog.trino.hogql.language-version="${HOGQL_LANGUAGE_VERSION}" \
+      io.posthog.trino.hogql.catalog-protocol-version="${HOGQL_CATALOG_PROTOCOL_VERSION}" \
+      io.posthog.trino.hogql.catalog-schema-version="${HOGQL_CATALOG_SCHEMA_VERSION}" \
+      io.posthog.trino.server-sha256="${TRINO_SERVER_SHA256}" \
+      io.posthog.trino.cli-sha256="${TRINO_CLI_SHA256}"
 ENV JAVA_HOME="/usr/lib/jvm/${JDK_VERSION}"
 ENV PATH=$PATH:$JAVA_HOME/bin
 ENV LANG=C.UTF-8

core/docker/build.sh

@@ -32,6 +32,15 @@ TEMURIN_RELEASE=$("${SOURCE_DIR}/mvnw" -f "${SOURCE_DIR}/pom.xml" --quiet help:e
 TEMURIN_DOWNLOAD_URL="https://api.adoptium.net/v3/binary/version/{release_name}/linux/{arch}/jdk/hotspot/normal/eclipse?project=jdk"
 
 SKIP_TESTS=false
+EXPLICIT_TRINO_SOURCE_REVISION="${TRINO_SOURCE_REVISION:-}"
+TRINO_SOURCE_REVISION="${EXPLICIT_TRINO_SOURCE_REVISION}"
+if [ -z "${TRINO_SOURCE_REVISION}" ] && git -C "${SOURCE_DIR}" rev-parse HEAD >/dev/null 2>&1; then
+    TRINO_SOURCE_REVISION="$(git -C "${SOURCE_DIR}" rev-parse HEAD)"
+fi
+TRINO_SOURCE_REVISION="${TRINO_SOURCE_REVISION:-unknown}"
+HOGQL_LANGUAGE_VERSION="${HOGQL_LANGUAGE_VERSION:-1.0.0}"
+HOGQL_CATALOG_PROTOCOL_VERSION="${HOGQL_CATALOG_PROTOCOL_VERSION:-1}"
+HOGQL_CATALOG_SCHEMA_VERSION="${HOGQL_CATALOG_SCHEMA_VERSION:-2}"
 
 while getopts ":a:h:r:p:t:j:x" o; do
     case "${o}" in
@@ -72,13 +81,26 @@ while getopts ":a:h:r:p:t:j:x" o; do
 done
 shift $((OPTIND - 1))
 
+if [ -n "${TRINO_VERSION}" ] && [ -z "${EXPLICIT_TRINO_SOURCE_REVISION}" ]; then
+    echo >&2 "TRINO_SOURCE_REVISION must be set when building downloaded release artifacts"
+    exit 1
+fi
+
 function check_environment() {
     if ! command -v jq &> /dev/null; then
         echo >&2 "Please install jq"
         exit 1
     fi
 }
 
+function sha256_file() {
+    if command -v sha256sum &> /dev/null; then
+        sha256sum "$1" | awk '{print $1}'
+    else
+        shasum -a 256 "$1" | awk '{print $1}'
+    fi
+}
+
 function temurin_download_uri() {
   local RELEASE_NAME="${1}"
   local ARCH="${2}"
@@ -112,6 +134,8 @@ else
     trino_server="${SOURCE_DIR}/core/${SERVER_ARTIFACT}/target/${SERVER_ARTIFACT}-${TRINO_VERSION}.tar.gz"
     trino_client="${SOURCE_DIR}/client/trino-cli/target/trino-cli-${TRINO_VERSION}-executable.jar"
 fi
+TRINO_SERVER_SHA256="$(sha256_file "${trino_server}")"
+TRINO_CLI_SHA256="$(sha256_file "${trino_client}")"
 
 echo "🧱 Preparing the image build context directory"
 WORK_DIR="$(mktemp -d)"
@@ -138,11 +162,39 @@ for arch in "${ARCHITECTURES[@]}"; do
         --build-arg ARCH="${arch}" \
         --build-arg JDK_VERSION="${TEMURIN_RELEASE}" \
         --build-arg JDK_DOWNLOAD_LINK="${JDK_DOWNLOAD_LINK}" \
+        --build-arg TRINO_SOURCE_REVISION="${TRINO_SOURCE_REVISION}" \
+        --build-arg HOGQL_LANGUAGE_VERSION="${HOGQL_LANGUAGE_VERSION}" \
+        --build-arg HOGQL_CATALOG_PROTOCOL_VERSION="${HOGQL_CATALOG_PROTOCOL_VERSION}" \
+        --build-arg HOGQL_CATALOG_SCHEMA_VERSION="${HOGQL_CATALOG_SCHEMA_VERSION}" \
+        --build-arg TRINO_SERVER_SHA256="${TRINO_SERVER_SHA256}" \
+        --build-arg TRINO_CLI_SHA256="${TRINO_CLI_SHA256}" \
         --platform "linux/$arch" \
         -f Dockerfile \
         -t "${TAG}-$arch"
 done
 
+function require_image_label() {
+    local image="$1"
+    local name="$2"
+    local expected="$3"
+    local actual
+    actual="$(docker image inspect --format "{{index .Config.Labels \"${name}\"}}" "${image}")"
+    if [ "${actual}" != "${expected}" ]; then
+        echo >&2 "Image label ${name} is ${actual}, expected ${expected}"
+        exit 1
+    fi
+}
+
+for arch in "${ARCHITECTURES[@]}"; do
+    image="${TAG}-${arch}"
+    require_image_label "${image}" "org.opencontainers.image.revision" "${TRINO_SOURCE_REVISION}"
+    require_image_label "${image}" "io.posthog.trino.hogql.language-version" "${HOGQL_LANGUAGE_VERSION}"
+    require_image_label "${image}" "io.posthog.trino.hogql.catalog-protocol-version" "${HOGQL_CATALOG_PROTOCOL_VERSION}"
+    require_image_label "${image}" "io.posthog.trino.hogql.catalog-schema-version" "${HOGQL_CATALOG_SCHEMA_VERSION}"
+    require_image_label "${image}" "io.posthog.trino.server-sha256" "${TRINO_SERVER_SHA256}"
+    require_image_label "${image}" "io.posthog.trino.cli-sha256" "${TRINO_CLI_SHA256}"
+done
+
 echo "🧹 Cleaning up the build context directory"
 rm -r "${WORK_DIR}"
 
@@ -157,4 +209,3 @@ else
       docker image inspect -f '🚀 Built {{.RepoTags}} {{.Id}}' "${TAG}-$arch"
   done
 fi
-

core/trino-hogql-compiler/README.md

@@ -0,0 +1,220 @@
+# Native HogQL compiler
+
+This module compiles HogQL directly to Trino's public SQL AST. It deliberately
+does not render an intermediate SQL string or add HogQL nodes to Trino's
+analyzer and planner.
+
+The implementation is split into two modules:
+
+- `trino-hogql-parser` owns the HogQL grammar and a private, source-located
+  parser AST. It has no dependency on Trino's SQL tree.
+- `trino-hogql-compiler` is the only translation boundary. It converts every
+  parser node into an `io.trino.sql.tree` node.
+
+The coordinator submits the resulting statement through the standard Trino
+analysis, planning, scheduling, paging, and cancellation paths. The original
+HogQL text remains the query text used by limits, history, and resource-group
+selection.
+
+## M0 contract
+
+M0 accepts a deliberately small grammar:
+
+```text
+SELECT <projection> [, ...] [FROM <qualified physical table>]
+```
+
+Projections can be `*`, qualified column references, integers, strings,
+booleans, or `NULL`. Identifiers can be unquoted, double quoted, or backquoted.
+The parser rejects unsupported clauses and multiple statements instead of
+silently interpreting them as SQL.
+
+## M1 syntax contract
+
+`HogQlParser.parseSyntax` accepts the complete canonical read-only query entry
+point and returns an immutable, source-located tree containing grammar rules,
+ANTLR alternative labels when present, and tokens. The tree contains no ANTLR
+or Trino SQL objects. It classifies declarative HogQLX separately from read-only
+queries.
+
+This syntax contract is intentionally independent from executable lowering.
+`HogQlParser.parseStatement` and `HogQlCompiler.compile` continue to return an
+explicit error for valid constructs that do not yet have a stock Trino AST
+mapping. Adding syntax support therefore cannot silently claim semantic or
+execution parity.
+
+## Executable contract
+
+The MVP lowers a frozen, fail-closed subset directly to stock Trino AST nodes:
+
+- logical `events` and `persons` tables supplied by a pinned Duckgres manifest;
+- scalar VARCHAR JSON property reads and the `events.person` lazy relationship;
+- parameters, CTEs, subqueries, joins, set operations, arrays, maps, rows,
+  intervals, grouping, ordering, limits, and windows that have exact stock
+  Trino representations;
+- `LIMIT BY` over explicit projected outputs, lowered through a partitioned
+  `row_number` query while preserving global ordering and pagination;
+- numeric/conditional/string functions (`abs`, `coalesce`, `if`, `lower`, `upper`, `length`,
+  `concat`, `replace`), collection functions (`map`, `arraySort`,
+  `arrayDistinct`, `arrayFlatten`, `arrayStringConcat`), date functions
+  (`dateAdd`, `dateDiff`, `dateTrunc`), aggregates (`count`, `sum`, `min`,
+  `max`, `avg`, `any`, `argMin`, `argMax`, `array_agg`), and windows
+  (`first_value`, `rank`, `row_number`).
+
+The compatibility extension also lowers conditional aggregates (`countIf`,
+`sumIf`, `minIf`, `maxIf`, `avgIf`, `anyIf`, `argMaxIf`, `groupArrayIf`,
+`uniqIf`, `uniqExactIf`, and `groupUniqArrayIf`), distinct aggregates
+(`uniqExact`, `countDistinct`, and `groupUniqArray`), and `multiIf` directly to
+stock Trino aggregate filters, DISTINCT aggregates, and searched CASE
+expressions.
+Aggregate rewrites preserve `OVER` specifications when the target Trino
+aggregate is used as a window function.
+JSON extraction lowers literal and runtime string/integer segments to Trino
+JSON paths with HogQL-compatible defaults. The compatibility profile also
+supports the corpus's typed map and key/value extraction forms through checked
+JSON-to-map casts.
+Date/time compatibility includes calendar arithmetic, interval-day values,
+epoch conversion, timezone attachment/conversion, formatting, and checked
+best-effort timestamp parsing.
+Array-form membership and the nullish operator lower to stock `IN`, `IF`, and
+`COALESCE` nodes, including nullable empty-membership behavior.
+Function-form boolean/comparison operators and common string/math aliases
+lower to their equivalent stock operators and functions. Checked/defaulting
+float conversions, Decimal64 casts, and integer division lower to stock casts
+and arithmetic.
+Literal regex extraction preserves HogQL's capture-group and empty-default
+behavior; matching and replace-all lower to Trino regex functions.
+The extended profile also lowers extract-all and first-match replacement, plus
+boolean, unsigned-integer, raw-array, and nested raw-map JSON extraction.
+Common array transforms, predicates, indexing, summation, ranges, tuple
+indexing, splitting, and membership lower to Trino higher-order functions.
+Map key/value constructors and `mapUpdate` lower to stock map construction and
+last-map-wins concatenation.
+The row-expanding `arrayJoin` function is hoisted to a generated lateral
+`CROSS JOIN UNNEST`; repeated calls remain independent row expansions.
+Range and membership rewrites preserve empty-range and null-search behavior.
+Typed defaults for out-of-range and no-match element lookups require resolved
+element types and remain outside the frozen compatibility subset.
+Expression-form comparison, arithmetic, membership, tuples, nullability
+assertions, string splitting, month arithmetic, and common window aliases also
+lower to stock Trino nodes.
+Additional scalar coverage includes array slicing/enumeration, UUID and integer
+conversion, JSON existence/value/serialization, hashing, powers, UTF-8
+substrings, banker-rounding aliases, and conditional median aggregation.
+Simple floor, calendar-part, map construction, and null-predicate aliases are
+mapped to their stock equivalents. Two-bound ranges, comparison and
+subtraction aliases, calendar month/year extraction, ceiling aliases, narrow
+integer casts, and JSON object-key extraction also lower to stock expressions.
+The static-ID, single-choice `getSurveyResponse(index, question_id)` macro
+prefers the modern response property and falls back to the legacy index key.
+Parametric quantiles lower to Trino percentile aggregates, and limited
+conditional group arrays lower to filtered `array_agg` plus `slice`.
+Algorithm-level parity for `quantileExact` remains a compatibility-validation
+item even though its query shape has a stock AST lowering.
+
+Function aliases are resolved before Trino analysis. Unknown functions fail as
+HogQL resolution errors. The corpus compatibility extension also accepts every
+logical table declared by the pinned manifest and expands declarative actions
+by name or ID into stock predicates or relation membership. Cohorts, saved
+queries, explicit modifiers without an enabled behavior, HogQLX,
+PIVOT/UNPIVOT execution, unsupported ClickHouse clauses, and complete
+type/function parity remain outside the endpoint profile.
+
+Set `hogql.enabled=true` on the coordinator to register `POST /v1/hogql`. The
+request body is the versioned JSON envelope containing the raw HogQL query,
+language/protocol versions, and optional typed bindings. The response uses
+Trino's existing statement protocol. Follow-up result and cancellation URIs
+remain under `/v1/statement`.
+The endpoint is absent when the property is false, which is the default.
+Production compilation uses a dedicated fixed-size executor with a bounded
+queue and the `hogql.compilation-timeout` wall-time limit. Saturation and
+timeout return retryable insufficient-resource errors; standard SQL bypasses
+the compiler executor.
+
+Development is based on the fork's `ducklake-connector` integration branch. At
+the start of this milestone its head was `posthog-484-ducklake.9`, commit
+`3065d56e4d5e256962c8297b4299909db8301c0a`.
+
+Charts `main` still provides the deployment compatibility baseline:
+`posthog-484-ducklake.6` at commit
+`3bb054e5b80bc6ad740b26f6748b7b3f5548ff32`, published as
+`ghcr.io/posthog/trino:484-ducklake.6`. Its linux/arm64 digest is
+`sha256:85d2b37dfb7c966a1bfe7b0470efaa6a0116c86cb6a05d14a6bdc8c02f7a6787`.
+
+## Fork maintenance
+
+The `ducklake-connector` branch's common ancestor with `trinodb/trino` is
+`67f588f0c81b21b425e1a43b05d70f9cf8798d6c`. The first nine PostHog commits
+produce the Charts `main` `.6` baseline:
+
+1. `a002cc56980` adds the DuckLake connector and PostHog image workflow.
+2. `4cd0573a57f` adds column-name mapping.
+3. `500cdf40aa3` fixes Parquet millisecond timestamp reads.
+4. `c03df89358a` reads fully visible partial files.
+5. `6ef914e4149` splits large data files.
+6. `09690b4fc8b` pools metadata connections and supports password files.
+7. `e6c3fbd9d83` adds the PostgreSQL catalog store.
+8. `0bab82c7520` counts rows from catalog metadata.
+9. `3bb054e5b80` reads Parquet footers using the recorded size.
+
+The rolling integration branch continues through `.7`-`.9` with the DuckLake
+write path, Trino views and schema evolution, partitioned-table reads, field-ID
+based reads, and missing-file-column handling. Merge commits and CI maintenance
+also live on this line; inspect the exact range from the upstream common
+ancestor rather than assuming the release-tag history is linear.
+
+Keep native HogQL changes as a separate ordered stack above those commits:
+parser/compiler modules, coordinator submission seam, metadata provider,
+optional functions, then packaging and tests. During an upstream update, fetch
+`trinodb/trino`, identify the new common ancestor, rebase the DuckLake series,
+then rebase the HogQL series onto `ducklake-connector`. Resolve AST API changes
+in `TrinoAstFactory` and submission conflicts in `QueuedStatementResource`,
+`DispatchManager`, and `QueryPreparer`; do not introduce HogQL branches into
+later execution stages.
+Run the unchanged SQL/coordinator suites, the complete DuckLake suite, and the
+HogQL suite before creating a release tag.
+
+`.github/workflows/docker-publish-posthog.yml` publishes linux/arm64 images.
+Pushing `posthog-<image-tag>` builds the complete distribution and publishes
+`ghcr.io/posthog/trino:<image-tag>`; a manual workflow dispatch accepts the same
+image-tag without the `posthog-` prefix. The workflow intentionally skips tests
+and checks, so its source commit must already have passed the suites above.
+
+## Validation
+
+On a fresh checkout, install their reactor dependencies without running tests:
+
+```shell
+./mvnw -pl :trino-hogql-parser,:trino-hogql-compiler,:trino-main -am install \
+    -DskipTests
+```
+
+Then run the parser, compiler, and coordinator tests together:
+
+```shell
+./mvnw -pl :trino-hogql-parser,:trino-hogql-compiler,:trino-main test \
+    -Dtest=TestHogQlParser,TestHogQlCompiler,TestQueryPreparer,TestHogQlConfig,TestHogQlStatementResource \
+    -Dsurefire.failIfNoSpecifiedTests=false
+```
+
+The compiler tests compare the shared SQL subset with Trino's SQL parser,
+format and reparse the generated tree, verify source locations, and assert that
+no private HogQL AST node crosses the compiler boundary.
+
+Measure the standard SQL preparation path with and without the compiler
+available using `BenchmarkQueryPreparer`. On JDK 25, enable annotation
+processing when generating the JMH benchmark index:
+
+```shell
+./mvnw -pl :trino-main clean test-compile exec:exec \
+    -Dmaven.compiler.proc=full \
+    -Dexec.executable=java \
+    -Dexec.classpathScope=test \
+    -Dexec.args='-cp %classpath io.trino.execution.BenchmarkQueryPreparer'
+```
+
+On 2026-08-26, one linux/arm64 Temurin 25 fork measured standard SQL
+preparation at `3.792 ± 0.096 us/op` with the HogQL compiler available and
+`3.708 ± 0.066 us/op` without it. The confidence intervals overlap; this M0
+sample does not show a distinguishable unused-path regression. Retain the
+benchmark for repeated measurements on release hardware.