ducklocal schema ./data/Descubre relaciones
Enumera archivos, tablas, vistas y sus columnas antes de escribir 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.
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.
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.
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.
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.
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).
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.
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.
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.
El texto exacto de las instrucciones viene de tu aplicación instalada e incluye la ruta completa del comando si ducklocal aún no está en el PATH. Instalar y revisar el skill →
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.
$ 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}
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.
$ 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}
ducklocal schema ./data/Enumera archivos, tablas, vistas y sus columnas antes de escribir SQL.
ducklocal schema sales.csv --statsObtén nulos exactos, valores distintos, rangos, medianas y cobertura de fechas.
ducklocal query --sql "…"Recibe JSON con tipos por defecto, o una tabla Markdown con --format md.
ducklocal open --title "…" --run --sql "…"Abre una consulta en la app de escritorio cuando el resultado necesite revisión o más exploración.
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.
row_count, truncated y elapsed_ms explícitosLa 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 →
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.
--read-write solo para un cambio intencionado en la base de datosducklocal --help antes de confiar en un comando¿Necesitas el flujo visual? Ver el análisis de datos locales en la app de escritorio →
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.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.AGENTS.md o en una regla de proyecto.Relacionado: DuckDB GUI · Visor de Parquet · Consultar CSV con SQL · Paneles SQL · DuckLocal vs DBeaver
Instala DuckLocal, añade el comando a tu PATH y empieza preguntando qué hay realmente en los datos.