Skills IA para ClickHouse®: Patrones con 100B+ Filas

Los asistentes de IA escriben SQL excelente. También escriben queries que van a destrozar tu base de datos de producción.

Pide a Claude o Cursor que creen un esquema de ClickHouse y vas a obtener algo sintácticamente perfecto: tipos correctos, nombres de columna razonables, una ENGINE que compila. Lo que no vas a obtener es un esquema optimizado para tus patrones de uso reales. El agente no sabe que poner timestamp primero en ORDER BY hará que las queries por usuario sean 10x más lentas. No sabe que SELECT * en ClickHouse es un error de naturaleza distinta al de PostgreSQL.

Este es el problema del slop de IA aplicado a bases de datos: resultados que parecen bien, compilan sin error y te revientan la factura en producción.

En ObsessionDB llevamos corriendo ClickHouse con más de 100.000 millones de filas y 10 millones de peticiones al día. Queries que funcionan en desarrollo y hacen timeout con datos reales. Esquemas que parecen razonables hasta que escalan. Casos de uso que directamente no encajan en ClickHouse. Los patrones que separan un ClickHouse funcional de uno de producción no están en las primeras páginas de la documentación.

Por eso extrajimos esos patrones en skills open source que enseñan a tu asistente de IA las reglas de optimización que de verdad importan.

Por qué los skills le ganan a la documentación

ClickHouse tiene buena documentación. El problema es el volumen.

Un agente de IA apuntando a la documentación en bruto se comporta como un recién llegado con acceso a Confluence: encuentra información, pero no sabe qué importa. Pregúntale por PREWHERE y te cita la página entera. Pregúntale por diseño de esquemas y te resume los principios generales. Lo que no va a hacer es decirte que la selección de columnas de ORDER BY es la decisión que más probabilidades tiene de salvar o hundir tus queries.

Esa es la limitación de fondo. Los agentes son reactivos. Contestan a la pregunta que haces, no a la que deberías haber hecho. Cuando dices "crea un esquema de ClickHouse para eventos", el agente no piensa "esta persona seguramente filtra por user_id, así que eso debería ir primero en ORDER BY." No conoce tus patrones de consulta. No sabe cómo es el tráfico en producción. Así que toma una decisión razonable que resulta ser incorrecta.

La documentación no lo soluciona porque está organizada por funcionalidad, no por prioridad. La página de ORDER BY explica qué hace ORDER BY. No dice "esto es lo primero que vas a hacer mal, y aquí tienes la regla exacta." Ese conocimiento vive en la cabeza de ingenieros que han debuggeado estos problemas, y se queda ahí hasta que alguien lo escribe en un formato que los agentes puedan consumir.

Los skills funcionan distinto. En vez de un manual donde buscar, dan patrones priorizados justo cuando el agente los necesita. Los patrones CRITICAL que evitan regresiones de rendimiento de 10-100x van primero. Las optimizaciones de alto impacto para cargas de producción, después. Todo tiene prioridades numeradas para que los agentes sepan qué arreglar primero.

Cuando tu agente carga el skill de diseño de esquemas, obtiene las reglas exactas para seleccionar columnas de ORDER BY: el marco de decisión, no un enlace a la documentación. Deja de adivinar. Hace las preguntas correctas o revisa la pipeline antes de decidir.

Las tres categorías de skills

Organizamos la optimización de ClickHouse en tres skills, ordenados por impacto:

Skill	Qué previene
Diseño de esquemas	Diseño de tablas y pipelines, motores, particiones
Optimización de consultas	Escaneos completos de tabla, índices, PREWHERE, desbordamientos de memoria
Vistas materializadas	Pre-agrega datos, profundización en motores, buenas prácticas

El diseño de esquemas es donde se gana o se pierde casi todo el rendimiento. La selección de columnas de ORDER BY es uno de los errores más comunes, seguido de la estrategia de particiones y la elección de engine. Si esto sale mal, da igual cuánto optimices las queries.

La optimización de queries cubre patrones de runtime: PREWHERE vs. WHERE, selección de columnas, por qué SELECT * es especialmente caro en bases de datos columnares, y estrategias de JOIN que no te tumban el clúster.

Las materialized views permiten dashboards en tiempo real sin agregación en query time. El skill cubre los patrones más comunes, estrategias de refresh y los problemas que causan inconsistencias de datos.

Ejemplo: el orden de columnas en ORDER BY importa

Como ejemplo básico, imagina una tabla que se va a consultar por user_id. Este es el código que suelen generar los agentes:

-- INCORRECTO: timestamp primero
CREATE TABLE events (
    timestamp DateTime,
    user_id UInt64,
    event_type String
) ENGINE = MergeTree()
ORDER BY (timestamp, user_id);

Parece razonable. Los eventos tienen timestamps, ordenar por ellos suena natural.

Pero cualquiera que haya usado ClickHouse sabe que esto está mal. La versión correcta:

-- CORRECTO: columna de filtro primero
CREATE TABLE events (
    timestamp DateTime,
    user_id UInt64,
    event_type String
) ENGINE = MergeTree()
ORDER BY (user_id, timestamp);

Por qué importa: ClickHouse almacena los datos ordenados por las columnas de ORDER BY. Cuando consultas WHERE user_id = 123, la base de datos usa ese orden para saltar directo a los datos relevantes, como un index lookup.

Con ORDER BY (timestamp, user_id), ClickHouse tiene que escanear todo para encontrar filas de un usuario concreto. El orden por timestamp no sirve para queries por usuario, que suelen ser buena parte del tráfico de producción.

El impacto: en producción hemos visto queries pasar de 20 segundos a 100 milisegundos solo corrigiendo el orden de columnas. Un desarrollador con experiencia en ClickHouse lo detecta al instante, pero los modelos cometen este error una y otra vez. Nos cansamos de revisar lo mismo.

El skill de diseño de esquemas enseña a los agentes a preguntar: "por qué columnas se va a filtrar con más frecuencia?" y ponerlas primero. Una regla simple que previene el desastre de rendimiento más común en ClickHouse.

Por qué los agentes repiten los mismos errores

Cada conversación con un agente arranca de cero. Tu asistente de IA no sabe que la semana pasada te tiraste cuatro horas debuggeando un problema de ORDER BY. No sabe que tu equipo exige LowCardinality para recortar costes en columnas string con menos de 10.000 valores distintos. No sabe que ya tienes patrones establecidos para claves de partición o que tus dashboards dependen de intervalos concretos de refresh de materialized views.

Sin orientación, el agente tira de lo que sabe por sus datos de entrenamiento: patrones genéricos que compilan, consejos generales de la documentación y conjeturas razonables basadas en los nombres de las columnas. Así acabas con esquemas técnicamente correctos que no cubren tu caso de uso real.

El agente no es tonto, le falta contexto. Con el contexto adecuado, toma buenas decisiones. Sin él, toma decisiones seguras y genéricas que muchas veces resultan incorrectas para tu caso.

Los skills resuelven esto. Cuando un agente carga los skills de ClickHouse, sabe lo que saben tus ingenieros senior. El de diseño de esquemas no se limita a listar reglas: le dice al agente que pregunte "por qué columnas se filtra más" antes de decidir el ORDER BY. El de optimización de queries explica por qué SELECT * es peor en ClickHouse que en bases de datos row-oriented. El de materialized views cubre los problemas de timing en merges que causan datos obsoletos.

Instala la lección una vez y cada sesión futura se beneficia. El agente deja de cometer los mismos errores porque alguien le enseñó qué evitar.

Los skills funcionan en Claude Code, Cursor y cualquier agente que los cargue.

Cómo empezar

La instalación es un solo comando:

npx skills add obsessiondb/clickhouse-skills

Se cargan automáticamente cuando trabajas con esquemas o queries de ClickHouse. Sin configuración.

Qué viene después

Los skills son open source. Si has aprendido lecciones de ClickHouse a base de golpes, contribuye o abre issues con patrones que nos hayamos dejado.

El objetivo es poner la experiencia en ClickHouse al alcance de cualquier desarrollador, escriba queries directamente o a través de un asistente de IA.

Dale una estrella al repositorio de GitHub, prueba los skills y cuéntanos qué te duele.