docs: update README to reflect SQL frontend, add SQL docs page

- Replace "Planned: SQL" with working SQL section and examples
- Remove "No SQL mode" from "What doesn't exist yet"
- Add SQL docs page with full syntax reference
- Add SQL to sidebar

Author: teamchong

README.md

@@ -193,9 +193,26 @@ const rows = await drainPipeline(sorted)
 await spill.cleanup()
 ```
 
-### Planned: SQL → AST → operators
+### SQL frontend
 
-For users who prefer SQL syntax, a future layer can parse SQL into an AST and compile it to operator composition — same zero-copy pipeline underneath, SQL is just another frontend.
+SQL is another way in — same operator pipeline underneath:
+
+```typescript
+const qm = QueryMode.local()
+const results = await qm
+  .sql("SELECT region, SUM(amount) AS total FROM orders WHERE status = 'active' GROUP BY region ORDER BY total DESC LIMIT 10")
+  .collect()
+
+// SQL and DataFrame compose — chain further operations after SQL
+const filtered = await qm
+  .sql("SELECT * FROM events WHERE created_at > '2026-01-01'")
+  .filter("country", "eq", "US")
+  .sort("amount", "desc")
+  .limit(50)
+  .collect()
+```
+
+Supports: SELECT, WHERE (AND/OR/NOT, LIKE, IN, NOT IN, BETWEEN, IS NULL), GROUP BY, HAVING, ORDER BY (multi-column), LIMIT/OFFSET, DISTINCT, CASE/CAST, arithmetic expressions, JOINs.
 
 ### Why this matters
 
@@ -226,7 +243,7 @@ npx tsx examples/nextjs-api-route.ts
 
 - **TypeScript orchestration** — Durable Object lifecycle, R2 range reads, footer caching, request routing
 - **Zig WASM engine** (`wasm/`) — column decoding, SIMD ops, SQL execution, vector search, fragment writing, compiles to `querymode.wasm`
-- **Code-first query API** — `.table().filter().select().sort().limit().exec()`, no SQL
+- **Code-first query API** — `.table().filter().select().sort().limit().exec()` or `.sql("SELECT ...")`
 - **Write path** — `TableQuery.append(rows)` with CAS-based manifest coordination via Master DO
 - **Master/Query DO split** — single-writer Master broadcasts footer invalidations to per-region Query DOs
 - **Footer caching** — table footers (~4KB each) cached in DO memory with VIP eviction (hot tables protected from eviction)
@@ -243,7 +260,6 @@ npx tsx examples/nextjs-api-route.ts
 - No deployed instance
 - No browser mode
 - No npm package published (install from source via git clone)
-- No SQL mode (planned — SQL frontend compiling to operator pipeline)
 
 ## Architecture
 ![querymode-architecture](docs/architecture/querymode-architecture.svg)

docs/astro.config.mjs

@@ -19,6 +19,7 @@ export default defineConfig({
         { label: "Why QueryMode", slug: "why-querymode" },
         { label: "Getting Started", slug: "getting-started" },
         { label: "DataFrame API", slug: "dataframe-api" },
+        { label: "SQL", slug: "sql" },
         { label: "Operators", slug: "operators" },
         { label: "Formats", slug: "formats" },
         { label: "Architecture", slug: "architecture" },

docs/src/content/docs/sql.mdx

@@ -0,0 +1,132 @@
+---
+title: SQL
+description: SQL frontend — same operator pipeline, SQL syntax.
+---
+
+SQL is another way into the same operator pipeline. The parser compiles SQL to a `QueryDescriptor`, which builds the same pull-based operator chain as the DataFrame API.
+
+## Usage
+
+```typescript
+import { QueryMode } from "querymode/local"
+
+const qm = QueryMode.local()
+
+const results = await qm
+  .sql("SELECT region, SUM(amount) AS total FROM orders GROUP BY region ORDER BY total DESC")
+  .collect()
+```
+
+## SQL + DataFrame compose
+
+`.sql()` returns a `DataFrame`, so you can chain DataFrame methods after it:
+
+```typescript
+const results = await qm
+  .sql("SELECT * FROM events WHERE created_at > '2026-01-01'")
+  .filter("country", "eq", "US")
+  .sort("amount", "desc")
+  .limit(50)
+  .collect()
+```
+
+## Supported syntax
+
+### SELECT
+
+```sql
+SELECT *
+SELECT col1, col2
+SELECT col1 AS alias
+SELECT DISTINCT col1, col2
+SELECT COUNT(*), SUM(amount), AVG(score)
+```
+
+### WHERE
+
+```sql
+WHERE age > 25
+WHERE status = 'active' AND amount >= 100
+WHERE dept = 'eng' OR age > 30
+WHERE name LIKE '%alice%'
+WHERE id IN (1, 2, 3)
+WHERE id NOT IN (4, 5)
+WHERE amount BETWEEN 100 AND 500
+WHERE email IS NULL
+WHERE email IS NOT NULL
+WHERE NOT (status = 'deleted')
+```
+
+### GROUP BY / HAVING
+
+```sql
+GROUP BY region
+GROUP BY region, category
+HAVING SUM(amount) > 1000
+```
+
+### ORDER BY
+
+```sql
+ORDER BY amount DESC
+ORDER BY region ASC, amount DESC
+```
+
+### LIMIT / OFFSET
+
+```sql
+LIMIT 100
+LIMIT 100 OFFSET 50
+```
+
+### Expressions
+
+```sql
+SELECT salary / 1000 AS salary_k
+SELECT CASE WHEN age > 30 THEN 'senior' ELSE 'junior' END AS level
+SELECT CAST(age AS text) AS age_str
+```
+
+### Aggregate functions
+
+`COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `COUNT(DISTINCT col)`.
+
+### JOINs
+
+```sql
+SELECT * FROM orders JOIN users ON orders.user_id = users.id
+SELECT * FROM orders LEFT JOIN users ON orders.user_id = users.id
+```
+
+## How it works
+
+```
+SQL string → lexer → parser → AST → compiler → QueryDescriptor → operator pipeline
+```
+
+The SQL frontend is a recursive descent parser written in TypeScript. It produces an AST that the compiler maps to the same `QueryDescriptor` the DataFrame API uses. Features that can be expressed as `FilterOp[]` (simple AND conditions with eq/gt/lt/etc) are pushed down to the inner executor. Features that can't (OR, LIKE, NOT IN, HAVING, multi-column ORDER BY, CASE/CAST/arithmetic) are handled by `SqlWrappingExecutor`, which applies them on the result rows.
+
+## Programmatic access
+
+If you need the parsed AST or compiled descriptor directly:
+
+```typescript
+import { parse, compile, compileFull, sqlToDescriptor } from "querymode/sql"
+
+// Parse SQL to AST
+const ast = parse("SELECT * FROM users WHERE age > 25")
+
+// Compile AST to QueryDescriptor
+const descriptor = compile(ast)
+
+// Or do both in one step
+const descriptor = sqlToDescriptor("SELECT * FROM users WHERE age > 25")
+
+// compileFull returns additional metadata for the wrapping executor
+const result = compileFull(ast)
+// result.descriptor — QueryDescriptor
+// result.whereExpr — full WHERE expression (when OR/LIKE/NOT IN present)
+// result.havingExpr — HAVING expression
+// result.allOrderBy — multi-column ORDER BY
+// result.computedExprs — CASE/CAST/arithmetic in SELECT
+```