SQL Cloud Warehouse

Apunta el flujo de sql-analyst a un data warehouse o lakehouse cloud (Snowflake, BigQuery, Redshift, Databricks) usando las mismas credenciales que ya pasaste via .env o vault.

Descripcion general

A diferencia de sql-analyst (que apunta a SQLite/Postgres/MySQL/DuckDB locales), esta skill:

• Construye un SQLAlchemy Engine apuntando al warehouse cloud.
• Provee snippets SQL que saben la diferencia entre los dialectos (ej. Snowflake usa IFF(cond, a, b), BigQuery y Databricks usan IF(...), Redshift usa CASE WHEN — el toolkit NO mezcla sintaxis).
• Mantiene la misma forma de output que schema-mapper para que el resto del flujo (query → validate) funcione igual.
• Solo lectura: SELECT unicamente. INSERT/UPDATE/DDL quedan explicitamente fuera de scope v1 (para persistencia con guardrails, usar sql-write).

Cuando usar

Invocar esta skill cuando el pedido matchee con alguno de:

• "Tengo un proyecto Snowflake / BigQuery / Redshift / Databricks con N tablas. Dame el top 10 clientes por revenue."
• "Conectate a este warehouse o lakehouse y mapéame el schema."
• "Escribime esta query en dialecto BigQuery (con backticks y SAFE_CAST) o Databricks (Spark SQL)."
• "Validá que esta query no escanee más de 1TB antes de correrla."

No invocar cuando:

• El target es SQLite/Postgres/MySQL/DuckDB local → sql-analyst solo.
• El usuario quiere escribir datos (INSERT/UPDATE/CREATE TABLE) → usar sql-write.

Flujo de trabajo

1. Detectar el target: leer WAREHOUSE_TYPE de env (snowflake | bigquery | redshift | databricks). Si no esta, inferir del connection string o pedir al usuario explicitamente.
2. Verificar credenciales y construir el Engine SQLAlchemy:
   • Snowflake: SNOWFLAKE_ACCOUNT/USER/PASSWORD/WAREHOUSE/DATABASE (opcional SNOWFLAKE_SCHEMA).
   • BigQuery: WAREHOUSE_PROJECT + WAREHOUSE_DATASET (o GOOGLE_APPLICATION_CREDENTIALS apuntando al JSON de service account).
   • Redshift: REDSHIFT_HOST/PORT/USER/PASSWORD/DATABASE.
   • Databricks: DATABRICKS_SERVER_HOSTNAME/HTTP_PATH/TOKEN (opcional DATABRICKS_CATALOG/SCHEMA).
3. Test de conexion: ejecutar SELECT 1 para validar que el engine responde antes de seguir. Si falla, mensaje accionable especificando que env var o dep falta.
4. Introspeccionar schema: introspect_schema(engine, schema=...) devuelve {warehouse, schema, tables: {<table>: {columns: [...]}}} en el mismo formato que schema-mapper.
5. Seleccionar tablas candidatas + JOIN paths: aplicar la heuristica del schema-mapper existente sobre el output del paso 4.
6. Escribir query dialecto-aware usando los snippets de dialect_snippets.py (ver tabla de diferencias abajo).
7. Validar query con validate_query(query) (estatico: parentesis balanceados, comillas) y explain_query(engine, query) cuando el warehouse lo soporte (Snowflake/Redshift; BigQuery requiere cliente nativo).
8. Ejecutar query con engine.connect() + pd.read_sql(). Output en DataFrame pandas + metadata (bytes scanned para BigQuery, credits para Snowflake) cuando aplique.

Recetas pre-aprobadas (importables)

import sys
sys.path.insert(0, "ruta/al/repo")
from skills_loader import load_skill_packages
load_skill_packages("skills")

from sql_cloud_warehouse.recetas import (
    connect_warehouse, test_connection,
    introspect_schema,
    date_trunc, conditional, current_timestamp, safe_cast,
    validate_query, explain_query,
    MissingCredentialsError, MissingDependencyError,
)

Las recetas son funciones puras (sin estado) y la mayoria NO requiere conexion activa (los snippets dialecto-aware son solo strings). La introspeccion y los connects requieren driver instalado + credenciales validas.

Diferencias de sintaxis clave

dialect_snippets.py encapsula las 4 primeras en funciones puras. Usa esas funciones SIEMPRE que armes una query — el riesgo real es copiar-pegar una query de StackOverflow en dialecto equivocado y gastar credits del warehouse antes de descubrir el error.

Credenciales

• Sin secrets hardcodeados: las credenciales van en .env (local) o en el vault de la empresa. Nunca en el codigo ni en el repo.
• Variables requeridas (ver tabla arriba).
• .env.example en este directorio documenta las variables por warehouse con placeholders (SNOWFLAKE_ACCOUNT=xxx, DATABRICKS_SERVER_HOSTNAME=xxx).
• Service accounts (BigQuery): el JSON va en una ruta local, NO en el repo. La env var GOOGLE_APPLICATION_CREDENTIALS apunta al path.

Senales de alerta

• MissingCredentialsError: el usuario no configuro las env vars. Mostrar el mensaje completo (lista que vars faltan) y donde van en .env.example.
• MissingDependencyError: el driver cloud no esta instalado. Mostrar el comando pip install ... exacto. NO intentar instalarlo tu mismo (peerDep opcional, el usuario decide).
• OperationalError con "no such table" tras introspect: el schema pasado no existe en el warehouse. Listar los schemas disponibles con SHOW SCHEMAS (Snowflake) o equivalente.
• Query corre OK pero devuelve 0 filas: chequea el filtro WHERE, el warehouse puede tener timezone distinto al local.
• Bytes scanned (BigQuery) > 100GB: warning automatico antes de cobrar.

Verificacion

Criterios de "listo" (ver docs/prd/sql-cloud-warehouse.md):

• Cada warehouse tiene un script de demo que falla con mensaje accionable si la credencial o la dep faltan.
• make test-snowflake, make test-bigquery, make test-redshift, make test-databricks ejecutan los demos (skipped por default si no hay credenciales).
• make test-sql-cloud-offline corre los snippets + validate sin necesitar credenciales (smoke test puro).
• La skill esta en skills/sql-cloud-warehouse/SKILL.md con el template de 6 secciones completo.
• AGENTS.md actualizado: sql-analyst carga sql-cloud-warehouse ANTES de sql-query-helper cuando target es uno de los cloud warehouses.
• package.json: las deps declaradas como peerDeps opcionales.
• bin/install.js corre con auto-descubrimiento dinámico.

Dependencias

El usuario instala solo la(s) que use. La skill falla con MissingDependencyError y un pip install <paquete> accionable si no esta.