Skills De IA Para Bases De Dataos ClickHouse®: Patrones De Optimización Probados Con 100B+ Filas

Los asistentes de IA escriben SQL excelente. También escriben consultas que destrozarán tu base de datos de producción.

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

Este es el problema del slop de IA en bases de datos: resultados que parecen correctos, compilan bien y revientan tu factura en producción.

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

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

Por Qué Los Skills Superan 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 contratado con acceso a Confluence: puede encontrar información, pero no sabe qué es lo que importa. Pregúntale sobre PREWHERE y te citará la página entera. Pregúntale sobre diseño de esquemas y te resumirá los principios generales. Lo que no hará es decirte que la selección de columnas de ORDER BY es la decisión individual con más probabilidades de hacer triunfar o hundir tus consultas.

Esta es la limitación fundamental. Los agentes son reactivos. Responden a la pregunta que haces, no a la pregunta que deberías haber hecho. Cuando dices "crea un esquema de ClickHouse para eventos", el agente no piensa "esta persona probablemente 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 de producción. Así que toma una decisión razonable que resulta estar equivocada.

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

Los skills funcionan de forma diferente. En lugar de un manual donde buscar, proporcionan patrones escalonados entregados cuando el agente los necesita. Los patrones CRITICAL que previenen regresiones de rendimiento de 10-100x van primero. Las optimizaciones de alto impacto para cargas de producción van después. Todo tiene prioridades numeradas para que los agentes sepan qué corregir primero.

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

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 la mayor parte del 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 selección de motor. Si esto sale mal, ninguna cantidad de optimización de consultas te salvará.

La optimización de consultas maneja patrones en tiempo de ejecución: PREWHERE vs WHERE, selección de columnas, por qué SELECT * es particularmente costoso en bases de datos columnares, y estrategias de JOIN que no matan tu clúster.

Las vistas materializadas permiten dashboards en tiempo real sin agregación en tiempo de consulta. El skill cubre los patrones más comunes, estrategias de refresco y los problemas que causan inconsistencias de datos.

Ejemplo: El Orden De Columnas De ORDER BY Importa

Como ejemplo básico, imaginemos una tabla que será consultada por user_id. Este es el código que los agentes suelen generar:

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

Esto parece razonable. Los eventos tienen timestamps, ordenar por ellos parece natural.

Sin embargo, cualquiera que haya usado ClickHouse sabe que esto es incorrecto. Aquí 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é esto 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 directamente a los datos relevantes, como una búsqueda por índice.

Con ORDER BY (timestamp, user_id), ClickHouse tiene que escanear todos los datos para encontrar filas de un usuario específico. El orden por timestamp es inútil para consultas específicas de usuario, que típicamente son una gran parte del tráfico de producción.

¿El impacto? En producción, hemos visto consultas pasar de 20 segundos a 100 milisegundos corrigiendo el orden de columnas. Un desarrollador con experiencia en ClickHouse detecta esto inmediatamente, pero los modelos cometen este error de forma consistente. Nos cansamos de revisar el mismo problema.

El skill de diseño de esquemas enseña a los agentes a preguntar: "¿Por qué columnas van a filtrar las consultas 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 Siguen Cometiendo Los Mismos Errores

Cada conversación con un agente empieza de cero. Tu asistente de IA no sabe que la semana pasada pasaste cuatro horas depurando un problema de ORDER BY. No sabe que tu equipo exige LowCardinality para recortar costes en columnas de cadenas con menos de 10.000 valores distintos. No sabe que ya has establecido patrones para claves de partición o que tus dashboards dependen de intervalos específicos de refresco de vistas materializadas.

Sin orientación, el agente recurre a lo que sabe de 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í es como acabas con esquemas técnicamente correctos que no cubren tu caso de uso real.

El agente no es tonto. Está desinformado. Con el contexto adecuado, toma buenas decisiones. Sin contexto, toma decisiones seguras y genéricas que a menudo resultan ser incorrectas para tu situación específica.

Los skills solucionan esto. Cuando un agente carga los skills de ClickHouse, sabe lo que saben tus ingenieros senior. El skill de diseño de esquemas no solo lista reglas; le dice al agente que pregunte "¿por qué columnas van a filtrar las consultas con más frecuencia?" antes de tomar decisiones de ORDER BY. El skill de optimización de consultas explica por qué SELECT * es peor en ClickHouse que en bases de datos orientadas a filas. El skill de vistas materializadas cubre los problemas de temporización de fusiones que causan datos obsoletos.

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

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

Primeros Pasos

La instalación requiere un solo comando:

npx skills add obsessiondb/clickhouse-skills

Los skills se cargan automáticamente cuando estás trabajando con esquemas o consultas de ClickHouse. No necesitan 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 hayamos pasado por alto.

El objetivo es hacer que la experiencia en ClickHouse sea accesible para todos los desarrolladores, ya sea que escriban consultas 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.