🗄️ Warehouse SQL — Referencia de capacidades del query

Documento vivo · índice maestro. El editor SQL de Carbon opera el Warehouse
con paridad práctica Databricks. Estas capacidades se organizan en 13
bloques de tamaño y extensión equivalentes. Este README es la jerarquía;
cada bloque tiene su propio doc numerado.

Cómo funciona (en una frase)

Escribes SQL contra tus tablas del Warehouse por su nombre o coordenada cualificada catalog.schema.tabla. El endpoint POST /api/sql-editor/execute clasifica la sentencia y la resuelve por el plano correcto:

Sentencia
  ├─ Comando de catálogo / DDL   → INDEX (PG + Lakekeeper + ledger)
  │     DESCRIBE · SHOW · ALTER TABLE … RENAME · CREATE/DROP VIEW
  └─ Query (SELECT / WITH / DML) → MOTOR, por la puerta (Junction)
        · resuelve nombre → identidad FÍSICA (catalog.schema.ds_<uuid>)
        · expande vistas a CTEs; el cuerpo de TU SQL no se reescribe
        · ejecuta en DuckDB sobre Iceberg/Parquet en R2

Detalle técnico del motor: engine.md.

📐 Los dos contratos MEDIDOS — y los dos se GENERAN

Qué fija Cómo se produce
carbon-sql-v0.md la gramática de QUERY (la de DuckDB): qué SQL acepta el motor, con su versión sellada ejecutando cada sintaxis contra el motor real
carbon-sql-catalog-v1.md la gramática de CATÁLOGO (la nuestra): los comandos, su esquema de salida, los límites y lo que NO está en v1 en frío, sobre el código de producción — no toca el motor porque estos comandos no lo tocan
carbon-sql-verbos.md los verbos de ESCRITURA, en dos planos: qué ejecuta el motor y qué deja pasar la puerta midiendo los dos, con sondas no-op por construcción

Los bloques numerados (01-…) son narrativa y ejemplos; sus tablas de estado se
escribieron a mano y envejecen. Para saber qué funciona, mira los medidos.

	Qué fija	Cómo se produce
carbon-sql-v0.md	la gramática de QUERY (la de DuckDB): qué SQL acepta el motor, con su versión sellada	ejecutando cada sintaxis contra el motor real
carbon-sql-catalog-v1.md	la gramática de CATÁLOGO (la nuestra): los comandos, su esquema de salida, los límites y lo que NO está en v1	en frío, sobre el código de producción — no toca el motor porque estos comandos no lo tocan
carbon-sql-verbos.md	los verbos de ESCRITURA, en dos planos: qué ejecuta el motor y qué deja pasar la puerta	midiendo los dos, con sondas no-op por construcción

⚠️ Coordenada real. Los ejemplos estilo Databricks usan workspace.public;
tu coordenada real es normalmente main.default. Corre SHOW SCHEMAS para ver
la tuya. En FROM da igual (el motor resuelve por nombre); en filtros de datos
(WHERE table_schema = 'public') usa el nombre real o quita el filtro.

Los 13 bloques

#	Bloque	Estado	Doc
1	Exploración y Análisis de Datos	✅ Implementado	01-exploration-analysis.md
2	Desarrollo de Consultas (lenguaje del Warehouse)	🚧 En construcción	02-query-development.md
3	Gestión de Objetos del Data Warehouse	⏳ Planificado	`03-object-management.md`
4	Operaciones de Datos (DML)	⏳ Planificado	`04-dml.md`
5	Consultas Parametrizadas	⏳ Planificado	`05-parameterized-queries.md`
6	Automatización y Scheduling	⏳ Planificado	`06-automation-scheduling.md`
7	Gobernanza y Seguridad	⏳ Planificado	`07-governance-security.md`
8	Testing y Validación	⏳ Planificado	`08-testing-validation.md`
9	Integración con Carbon	⏳ Planificado	`09-carbon-integration.md`
10	Funciones Avanzadas	⏳ Planificado	`10-advanced-functions.md`
11	Exportación y Reporting	⏳ Planificado	`11-export-reporting.md`
12	Debugging y Troubleshooting	⏳ Planificado	`12-debugging.md`
13	Prototipado	⏳ Planificado	`13-prototyping.md`

Convención de los docs de bloque

Cada bloque sigue la MISMA estructura para que el pipeline sea homogéneo:

Resumen — qué cubre el bloque en 2-3 frases.
Capacidades — agrupadas por sub-área, cada una con: qué hace · sintaxis · ejemplo real (dominio estorninos/flujos) · estado (✅ / ⚠️ con equivalente / ❌).
Matices y límites — gotchas, diferencias de dialecto, lo diferido.
Referencia rápida — tabla de sintaxis soportada.

Al terminar un bloque: marcar ✅ en la tabla de arriba y enlazar su doc.

Principio de sostenibilidad — la frontera, no el motor

El shim sobre Postgres (traducción a CTE + dialecto Spark→PG sobre dataset_rows) ya no existe: se retiró en el F3-RETIRO (2026-07-10) y la tabla que lo sostenía se soltó el 2026-07-31. Hoy el motor es DuckDB sobre Iceberg, y habla su dialecto de forma nativa — se cumplió lo que este apartado predecía: los shims se borraron, no se migraron.

Lo que sobrevive es la tesis, y es la que importa: la costura es la puerta (Junction) + Index, no el motor. Cambiar de ejecutor —DuckDB, DataFusion, Karma— no cambia esta superficie. La especificación del contrato de dialecto, formato y parser está en warehouse-sql-dialect-spec.md.