Deja que los agentes de IA consulten datos locales con SQL

Da a Claude Code, Codex, Cursor y otros agentes de programación un flujo de trabajo DuckDB sin interfaz para datos CSV, Parquet, JSON y DuckDB. Sin automatizar interfaces gráficas, sin servidor de base de datos y sin API a medida.

La CLI imprime JSON por defecto y usa códigos de salida explícitos para los fallos de argumentos, SQL y E/S.

Primero descubrir, después consultar

El flujo de trabajo oficial evita que un agente adivine nombres de columnas o tome una vista previa parcial como si fuera todo el conjunto de datos.

  1. Mapea el esquema

    Ejecuta ducklocal schema ./data/ para obtener relaciones, expresiones FROM listas para consultar, columnas y tipos. Los catálogos grandes devuelven un resumen con pistas para profundizar.

  2. Previsualiza dentro de los límites

    Usa una sola sentencia SQL y un --limit pequeño para inspeccionar filas representativas. Comprueba el código de salida del comando y el campo truncated del JSON.

  3. Calcula la respuesta en SQL

    Ejecuta filtros, uniones y agregaciones en DuckDB en lugar de sumar una vista previa truncada en el contexto del agente. Devuelve solo la evidencia que la respuesta necesita.

Configúralo en Claude Code, Codex o Cursor

Todo agente necesita dos cosas: el comando ducklocal en su PATH e instrucciones sobre cómo usarlo. Ambas salen de Command line & AI… en la aplicación (el botón del robot en la barra de título, o el menú DuckLocal).

Claude Code: instala el skill

Haz clic en Install command y luego en Add to Claude Code. El skill se escribe en ~/.claude/skills/ducklocal, donde Claude Code lo encuentra en todos los proyectos. Cuando una petición encaja, Claude Code carga el skill y sigue el flujo de «primero el esquema» sin que se lo digas.

# In any project, ask in plain language:
Which channel brought in the most revenue in data/sales.csv?
Use DuckLocal and show me the query.

Para usar el skill solo en un proyecto, copia skills/ducklocal en el .claude/skills/ de ese proyecto.

Codex: pega las instrucciones en AGENTS.md

Haz clic en Install command y luego en Copy brief, y pega las instrucciones en AGENTS.md en la raíz de tu proyecto. Codex lee ese archivo al empezar cada sesión. Las instrucciones, resumidas:

DuckLocal is installed on this machine. Its command, ducklocal,
runs DuckDB SQL over local CSV, TSV, Parquet, JSON and Excel files
and databases, and prints JSON.

- Start with `ducklocal --help` for the options.
- See what there is to query, with columns, before writing SQL:
  `ducklocal schema ./data/` (or `--database file.duckdb`).
- Profile what you will chart or summarize:
  `ducklocal schema data.csv --stats`.
- Compute totals in SQL, not from sample rows;
  check `truncated` in the output.
- It opens data read-only by default. Answer from the values
  it returns, and say which query produced them.

Si tu versión de Codex admite skills, también puedes copiar los mismos SKILL.md y references/cli.md en su directorio de skills.

Cursor: guarda las instrucciones como regla de proyecto

Haz clic en Install command y luego en Copy brief, y guarda las instrucciones como regla de proyecto, por ejemplo .cursor/rules/ducklocal.mdc. Así el agente de Cursor conoce el comando siempre que trabaja en ese proyecto. Su herramienta de terminal necesita permiso para ejecutar ducklocal: permite schema y query, y sigue aprobando todo lo que escriba archivos.

# Then ask the agent:
Compare monthly order counts in exports/orders-*.csv
for 2025 and 2026 with DuckLocal.

Por qué el agente no debe sumar la vista previa

Un agente que lee filas y las suma en su propio contexto responde con lo que se le mostró. Con un archivo de 1,2 millones de filas y el límite predeterminado de 1.000 filas, ve menos del 0,1 % de los datos. El total que informa puede parecer razonable y aun así estar equivocado en varios órdenes de magnitud.

DuckLocal hace visible esa brecha en lugar de silenciarla. Una vista previa indica "truncated": true, y total_rows muestra cuántas filas tenía realmente el resultado. Cuando el conteo se detiene antes, total_rows_exact es false y el total es solo un límite inferior. El skill le dice al agente que lo trate como una muestra y devuelva el cálculo a DuckDB, que lee todas las filas.

Límites, presupuestos y formato de salida

Terminal
$ ducklocal query --sql \
  "SELECT * FROM 'events.csv'"
{..., "row_count":1000,
 "truncated":true,
 "total_rows":101000,
 "total_rows_exact":false}

$ ducklocal query --sql \
  "SELECT count(*) AS n, sum(amount) AS total
   FROM 'events.csv'"
{..., "rows":[[1204381,8812094.5]],
 "truncated":false}

Un comando, una sentencia SQL

Cada invocación crea una conexión dedicada a DuckDB, valida que la entrada contenga exactamente una sentencia y escribe un resultado legible por máquina en stdout. Los errores son JSON en stderr con un código de salida distinto de cero.

Lee el contrato de consulta

Terminal
$ ducklocal query --sql \
  "SELECT channel, round(sum(revenue), 2) AS revenue
   FROM 'sales.csv'
   GROUP BY channel
   ORDER BY revenue DESC"

{"columns":[...],
 "rows":[["Mobile app",290549.76],...],
 "row_count":4,
 "truncated":false,
 "elapsed_ms":14}

Una interfaz pequeña con contratos explícitos

ducklocal schema ./data/

Descubre relaciones

Enumera archivos, tablas, vistas y sus columnas antes de escribir SQL.

ducklocal schema sales.csv --stats

Perfila una relación

Obtén nulos exactos, valores distintos, rangos, medianas y cobertura de fechas.

ducklocal query --sql "…"

Ejecuta una sentencia

Recibe JSON con tipos por defecto, o una tabla Markdown con --format md.

ducklocal open --title "…" --run --sql "…"

Pasa el trabajo a una persona

Abre una consulta en la app de escritorio cuando el resultado necesite revisión o más exploración.

Una salida que avisa al agente cuando está incompleta

El límite de resultados por defecto es de 1.000 filas, con un presupuesto adicional de 2.000.000 de celdas. DuckLocal lee una fila extra para determinar si la respuesta se cortó y lo expone como truncated.

Las consultas con GROUP BY, ORDER BY y agregaciones siguen calculándose sobre la entrada completa antes de devolver su resultado acotado.

  • Columnas y filas con tipos en una estructura JSON estable
  • row_count, truncated y elapsed_ms explícitos
  • Código de salida 2 para argumentos no válidos; código 1 para fallos de ejecución
  • Errores JSON en stderr, con stdout vacío
  • Salida Markdown para informes legibles por personas

Enseña el flujo de trabajo, no solo el comando

La skill de código abierto de DuckLocal enseña al agente a inspeccionar el esquema, previsualizar una muestra acotada, agregar en SQL, verificar el truncado y responder con los valores devueltos. Instálala para Claude Code desde la app, o copia el mismo resumen en otro agente de programación.

Instala e inspecciona la skill

Leer: Lo que los paneles de Claude me enseñaron sobre DuckLocal →

Una CLI local, no un servicio en la nube oculto ni un entorno aislado

DuckLocal no sube tus archivos locales a un servicio de DuckLocal, pero tampoco finge que cualquier SQL es inofensivo. El modo de base de datos de solo lectura no es un entorno aislado del sistema de archivos ni de la red: SQL como COPY, la instalación de extensiones o el acceso externo explícito pueden tener efectos secundarios.

  • Autoriza rutas de salida, sobrescrituras y cambios en la base de datos
  • Autoriza la instalación de extensiones y el acceso externo
  • Inspecciona un destino antes de reintentar una escritura fallida
  • Usa --read-write solo para un cambio intencionado en la base de datos
  • Consulta ducklocal --help antes de confiar en un comando

Preguntas sobre SQL para agentes de IA

¿Cómo consulta un agente de IA datos locales con DuckLocal?
El agente ejecuta ducklocal schema para descubrir relaciones y columnas, y después ducklocal query con una sola sentencia SQL. El comando devuelve JSON estructurado por defecto sin abrir la ventana de escritorio ni iniciar un servidor.
¿La CLI devuelve los datos completos por defecto?
No. La salida de las consultas está acotada a propósito: el límite de filas por defecto es 1.000 y también se aplica un presupuesto de 2.000.000 de celdas. La respuesta JSON indica si se truncó. Los agregados completos deben calcularse dentro del SQL.
¿Puede DuckLocal ejecutar scripts SQL para un agente?
Cada invocación de ducklocal query acepta exactamente una sentencia SQL. Los scripts con varias sentencias se rechazan en lugar de ejecutarse parcialmente, lo que hace más fácil inspeccionar cada llamada de la herramienta.
¿DuckLocal funciona con Codex y Cursor, o solo con Claude Code?
Cualquier agente que pueda ejecutar un comando de terminal puede usarlo. Claude Code instala el skill oficial con un clic desde la aplicación. Para Codex, Cursor y otros agentes, el botón Copy brief de la aplicación genera instrucciones para pegar en AGENTS.md o en una regla de proyecto.
¿DuckLocal es un servidor MCP o un entorno aislado de seguridad?
No. DuckLocal ofrece una interfaz de línea de comandos y una skill de agente opcional, no un servidor MCP ni un entorno aislado de seguridad. Las posibles escrituras, la instalación de extensiones y el acceso externo siguen requiriendo la autorización habitual.

Dale a tu agente un flujo de trabajo SQL que empieza por el esquema

Instala DuckLocal, añade el comando a tu PATH y empieza preguntando qué hay realmente en los datos.