feat(calcite): add VortexCalcite.connect with Babel parser for reserved-word columns

The adapter emits no SQL of its own, so it has nothing to quote — the
reserved-word problem (a column named `close`/`open`/`value` breaking
unquoted queries) is owned by the connection's parser, not the adapter.

VortexCalcite.connect(schemaName, tables) is a one-call JDBC entry point
that registers the VortexSchema and wires Calcite's Babel parser, which
accepts SQL reserved words as identifiers. `select close, open from
vtx.ohlc` now parses unquoted — the common case for columnar files. The
typed-literal keywords (date/time/timestamp/interval) stay reserved even
under Babel (they begin a literal, e.g. DATE '2020-01-01') and still need
back-tick quoting; that residual is documented and tested.

calcite-babel adds no transitive dependencies beyond calcite-core.

OhlcSqlDemoTest.connect() now delegates to the helper, dogfooding it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dfa1

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `VortexCalcite.connect(schemaName, tables)` opens a Calcite JDBC connection with the `VortexSchema` registered in one call, folding away the `DriverManager` / `unwrap` / `getRootSchema().add(...)` boilerplate. It wires the **Babel** SQL parser, so columns whose names are reserved words (`close`, `open`, `value`, `year`, …) are queryable **unquoted** — `select close, open from vtx.ohlc` — which columnar files routinely need; only the typed-literal keywords (`date`, `time`, `timestamp`, `interval`) still require back-tick quoting. ([24b64b32](https://github.com/dfa1/vortex-java/commit/24b64b32))
 - The Calcite aggregate push-down rule now **auto-registers** over a bare `jdbc:calcite:` connection: a `VortexTable` translates to a `VortexTableScan` whose `register()` installs the rules when the planner first sees it, so `SELECT MIN/MAX/COUNT/SUM` over a `VortexSchema` is answered from zone-map statistics with no caller wiring (previously the rule had to be attached to the planner by hand). `AVG` joins them — `AggregateReduceFunctionsRule` reduces it to `SUM`/`COUNT`, both of which push down, so a whole-table `AVG` also decodes no data segment. Column projection and `WHERE` chunk-skip push-down are unchanged. ([24b64b32](https://github.com/dfa1/vortex-java/commit/24b64b32))
 - The Calcite aggregate push-down rule now rewrites a whole-table `SUM(col)` to a single-row `Values` computed from the zone-map table (via `VortexTable.zoneSum`), so `SELECT SUM(col)` answers metadata-only with no data segment decoded — joining the existing `MIN`/`MAX`/`COUNT` push-down. `SUM` over an all-null (or empty) column answers the SQL `NULL`, and the rule abandons to a normal scan when a zone carries no usable sum (no zone map, or an overflowed zone) or when a `WHERE` filters the aggregate. ([24b64b32](https://github.com/dfa1/vortex-java/commit/24b64b32))
 - `ScanIterator.columnZoneStats(column)` surfaces per-zone min/max/sum/null-count from a column's `vortex.stats` zone-map table without decoding any data segment — the read side of aggregate push-down (ADR 0013 §6). `ArrayStats` gains a `sum` component, decoded from the zone-map table (where the Rust reference stores it too), so the Calcite adapter now answers `SUM`/`AVG` metadata-only when every zone carries a sum, falling back to a streaming scan only for columns without a zone map. ([05dd9204](https://github.com/dfa1/vortex-java/commit/05dd9204))

calcite/pom.xml

@@ -27,6 +27,13 @@
 			<artifactId>calcite-core</artifactId>
 			<version>${calcite.version}</version>
 		</dependency>
+		<!-- Babel SQL parser: lets reserved-word column names (date, close, open, …) be queried
+		     unquoted through VortexCalcite.connect. Adds no transitive deps beyond calcite-core. -->
+		<dependency>
+			<groupId>org.apache.calcite</groupId>
+			<artifactId>calcite-babel</artifactId>
+			<version>${calcite.version}</version>
+		</dependency>
 		<!-- testing -->
 		<dependency>
 			<groupId>io.github.dfa1.vortex</groupId>

calcite/src/main/java/io/github/dfa1/vortex/calcite/VortexCalcite.java

@@ -0,0 +1,78 @@
+package io.github.dfa1.vortex.calcite;
+
+import org.apache.calcite.jdbc.CalciteConnection;
+import org.apache.calcite.schema.SchemaPlus;
+import org.apache.calcite.sql.parser.babel.SqlBabelParserImpl;
+
+import java.nio.file.Path;
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.SQLException;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Properties;
+
+/// Entry point for querying Vortex files with SQL through Apache Calcite.
+///
+/// [#connect(String, Map)] opens a Calcite JDBC connection with a [VortexSchema] already
+/// registered, folding the `DriverManager` + `unwrap` + `getRootSchema().add(...)` boilerplate into
+/// one call:
+///
+/// ```java
+/// try (Connection conn = VortexCalcite.connect("vtx", Map.of("ohlc", path));
+///      Statement st = conn.createStatement();
+///      ResultSet rs = st.executeQuery("select min(low), max(high), sum(volume) from vtx.ohlc")) {
+///     // whole-table aggregates are answered from zone-map statistics, no data segment decoded
+/// }
+/// ```
+///
+/// The connection uses Calcite's `JAVA` lexical policy (case-sensitive identifiers, back-tick
+/// quoting, unquoted case preserved) together with the **Babel** SQL parser, which accepts most SQL
+/// reserved words as identifiers. A column whose name is a reserved word — `close`, `open`, `value`,
+/// `year`, … — can therefore be queried **unquoted**: `select close, open from vtx.ohlc`, which
+/// columnar files routinely need.
+///
+/// The exception is the handful of keywords that begin a typed literal — `date`, `time`,
+/// `timestamp`, `interval` — which stay reserved even under Babel (`date` opens `DATE '2020-01-01'`).
+/// A column with one of those names must still be back-tick quoted: `select \`date\` from vtx.ohlc`.
+public final class VortexCalcite {
+
+    private VortexCalcite() {
+    }
+
+    /// Opens a Calcite JDBC connection exposing `tables` under a schema named `schemaName`.
+    ///
+    /// Each map entry binds a SQL table name to the `.vortex` file backing it; the tables are
+    /// reachable as `schemaName.tableName`. The returned connection is the caller's to close, which
+    /// releases the schema's readers. If schema registration fails the connection is closed before
+    /// the failure propagates, so no connection leaks.
+    ///
+    /// @param schemaName the schema name the tables are registered under
+    /// @param tables     map from SQL table name to the `.vortex` file path
+    /// @return an open Calcite JDBC connection with the Vortex schema registered
+    /// @throws SQLException if the JDBC connection cannot be opened or the schema cannot be registered
+    public static Connection connect(String schemaName, Map<String, Path> tables) throws SQLException {
+        Objects.requireNonNull(schemaName, "schemaName");
+        Objects.requireNonNull(tables, "tables");
+        Properties info = new Properties();
+        // JAVA lex: case-sensitive identifiers, back-tick quoting, unquoted case preserved — so an
+        // unquoted `ohlc` matches the registered table name exactly.
+        info.setProperty("lex", "JAVA");
+        // Babel parser: accept SQL reserved words (date, close, open, value, …) as identifiers, so
+        // columnar files whose column names collide with keywords are queryable unquoted.
+        info.setProperty("parserFactory", SqlBabelParserImpl.class.getName() + "#FACTORY");
+        Connection connection = DriverManager.getConnection("jdbc:calcite:", info);
+        try {
+            SchemaPlus root = connection.unwrap(CalciteConnection.class).getRootSchema();
+            root.add(schemaName, new VortexSchema(tables));
+            return connection;
+        } catch (SQLException | RuntimeException e) {
+            try {
+                connection.close();
+            } catch (SQLException closeFailure) {
+                e.addSuppressed(closeFailure);
+            }
+            throw e;
+        }
+    }
+}

calcite/src/test/java/io/github/dfa1/vortex/calcite/OhlcSqlDemoTest.java

@@ -195,12 +195,7 @@ void filterPushDownPrunesChunksAndShowsInExplain() throws Exception {
     }
 
     private static Connection connect() throws Exception {
-        Properties info = new Properties();
-        info.setProperty("lex", "JAVA");
-        Connection conn = DriverManager.getConnection("jdbc:calcite:", info);
-        conn.unwrap(CalciteConnection.class).getRootSchema()
-                .add("vtx", new VortexSchema(Map.of("ohlc", file)));
-        return conn;
+        return VortexCalcite.connect("vtx", Map.of("ohlc", file));
     }
 
     private static SqlAggs runSql(Connection conn) throws Exception {

calcite/src/test/java/io/github/dfa1/vortex/calcite/VortexCalciteTest.java

@@ -0,0 +1,96 @@
+package io.github.dfa1.vortex.calcite;
+
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.nio.file.Path;
+import java.sql.Connection;
+import java.sql.ResultSet;
+import java.sql.Statement;
+import java.util.Map;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatNullPointerException;
+
+/// Covers [VortexCalcite#connect(String, Map)] — the one-call JDBC entry point: it registers the
+/// schema, the aggregate push-down rule auto-fires through it, and a reserved-word column is
+/// queryable when back-tick quoted.
+class VortexCalciteTest {
+
+    @TempDir
+    static Path tmp;
+    private static Path file;
+
+    @BeforeAll
+    static void writeFile() throws Exception {
+        file = tmp.resolve("ohlc.vortex");
+        // Small two-zone file; the OHLC schema includes reserved-word columns (date, open, close).
+        OhlcGenerator.write(file, 20_000, 10_000);
+    }
+
+    @Test
+    void connect_registersSchemaAndPushesAggregateWithNoScan() throws Exception {
+        // Given a connection opened through the helper (no manual DriverManager/unwrap/add)
+        try (Connection conn = VortexCalcite.connect("vtx", Map.of("ohlc", file))) {
+
+            // When a whole-table SUM is explained — the rule must auto-register via VortexTableScan
+            String plan;
+            try (Statement st = conn.createStatement();
+                 ResultSet rs = st.executeQuery("explain plan for select sum(volume) from vtx.ohlc")) {
+                rs.next();
+                plan = rs.getString(1);
+            }
+
+            // Then it is answered from zone-map stats — no data segment decoded
+            assertThat(plan).doesNotContain("TableScan");
+        }
+    }
+
+    @Test
+    void connect_reservedWordColumnsAreQueryableUnquoted() throws Exception {
+        // Given the OHLC table has columns named close and open — both SQL reserved words (CLOSE /
+        // OPEN cursor) that the stock parser rejects unquoted
+        try (Connection conn = VortexCalcite.connect("vtx", Map.of("ohlc", file))) {
+
+            // When they are selected UNQUOTED — the Babel parser accepts reserved words as identifiers
+            long rows = 0;
+            try (Statement st = conn.createStatement();
+                 ResultSet rs = st.executeQuery("select close, open from vtx.ohlc")) {
+                while (rs.next()) {
+                    rows++;
+                }
+            }
+
+            // Then the query runs and returns every row, no back-ticks needed
+            assertThat(rows).isEqualTo(20_000);
+        }
+    }
+
+    @Test
+    void connect_typeKeywordColumnStillNeedsQuoting() throws Exception {
+        // Given the `date` column: even Babel keeps DATE reserved (it begins a date literal,
+        // DATE '2020-01-01'), so it is the residual case that still needs back-ticks
+        try (Connection conn = VortexCalcite.connect("vtx", Map.of("ohlc", file))) {
+
+            // When `date` is back-tick quoted
+            long rows = 0;
+            try (Statement st = conn.createStatement();
+                 ResultSet rs = st.executeQuery("select `date` from vtx.ohlc")) {
+                while (rs.next()) {
+                    rows++;
+                }
+            }
+
+            // Then it resolves to the column and returns every row
+            assertThat(rows).isEqualTo(20_000);
+        }
+    }
+
+    @Test
+    void connect_nullArguments_throw() {
+        // Given / When / Then — both arguments are required
+        assertThatNullPointerException().isThrownBy(() -> VortexCalcite.connect(null, Map.of()));
+        assertThatNullPointerException().isThrownBy(() -> VortexCalcite.connect("vtx", null));
+    }
+}

docs/adr/0018-calcite-sql-adapter.md

@@ -122,8 +122,12 @@ Phases 0–2 are implemented and tested:
 
 Gotchas found and recorded for the production adapter:
 
-- **Reserved words.** Beyond `date`, the OHLC columns `close`/`open` (CLOSE/OPEN cursor) must be
-  quoted. A production adapter should quote all identifiers it emits.
+- **Reserved words.** Column names that are SQL keywords (`close`/`open`, `value`, `year`, …)
+  break unquoted queries under the stock parser. Resolved by `VortexCalcite.connect`, which wires
+  the Babel parser (`calcite-babel`) so reserved words parse as identifiers unquoted — the adapter
+  emits no SQL of its own, so there is nothing for it to quote; the lever is the parser, owned by
+  the connection. The residual exceptions are the typed-literal keywords (`date`, `time`,
+  `timestamp`, `interval`), which stay reserved even under Babel and still need back-tick quoting.
 - **Integer stats are `Long`.** Zone-map integer stats decode as `Long`, floats as `Double`,
   regardless of column width. A filter literal boxed at the column's natural width (`Integer` for
   `I32`) silently disables pruning because `ScanIterator.compareValues` swallows the resulting