---
title: SQL para agentes de IA sobre datos locales | DuckLocal CLI
description: Deja que los agentes de IA inspeccionen esquemas y consulten archivos locales con una sola sentencia SQL de DuckDB y salida JSON acotada.
image: https://ducklocal.app/og-image.jpg?v=2
language: es
---

# Deja que los agentes de IA consulten datos locales con SQL

**Primero el esquema. Una sola sentencia. Salida estructurada.**

DuckLocal 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. No requiere automatizar interfaces gráficas, ni un servidor de base de datos, ni una API a medida.

## Primero descubrir, después consultar

1. **Mapea el esquema.** `ducklocal schema ./data/` devuelve 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.** Ejecuta una sola sentencia SQL con un límite pequeño. Comprueba el código de salida y el campo `truncated` del JSON.
3. **Calcula en SQL.** Haz los filtros, las uniones y las agregaciones en DuckDB en lugar de sumar una vista previa parcial en el contexto del agente.

```bash
ducklocal schema ./data/
ducklocal schema sales.csv --stats
ducklocal query --sql "SELECT channel, sum(revenue) FROM 'sales.csv' GROUP BY channel"
```

Cada invocación de `query` crea una conexión dedicada, valida que haya exactamente una sentencia SQL 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.

## 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.

```text

# 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`](https://github.com/JetSquirrel/DuckLocal/tree/main/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:

```text
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.

```text

# 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 →](https://ducklocal.app/docs/es/cli#install-the-official-skill)

## 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](https://ducklocal.app/docs/es/cli#query-options)

```bash
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}
```

## Una salida acotada y explícita

El límite por defecto es de 1.000 filas, con un presupuesto de 2.000.000 de celdas. DuckLocal lee una fila extra para determinar si el resultado se cortó.

La respuesta JSON incluye:

- columnas y filas con tipos
- `row_count`
- `truncated`
- `elapsed_ms`

El código de salida 2 indica argumentos no válidos; el código 1, un fallo de ejecución. `--format md` muestra el mismo resultado como tabla Markdown para que lo lea una persona.

## Skill de agente oficial

La skill de código abierto enseña al agente a inspeccionar el esquema, previsualizar una muestra acotada, agregar en SQL, verificar el truncado y responder con los valores devueltos. Se puede instalar para Claude Code desde la app, o usar como resumen para otro agente.

Un agente puede entregar trabajo a la app de escritorio abierta con `ducklocal open` y después leer las pestañas visibles y las vistas previas de resultados con `ducklocal open --state`.

## Límite de seguridad

DuckLocal no sube los archivos locales a un servicio de DuckLocal, pero no es un entorno aislado de seguridad. El modo de base de datos de solo lectura no impide que el SQL escriba otros archivos o acceda a la red.

Autoriza las rutas de salida, las sobrescrituras, los cambios en la base de datos, la instalación de extensiones y el acceso externo antes de ejecutar.

## Enlaces

- [Descargar DuckLocal](https://github.com/JetSquirrel/DuckLocal/releases/latest)
- [Referencia completa de la CLI](https://ducklocal.app/docs/es/cli)
- [Instalar la skill oficial](https://ducklocal.app/docs/es/cli#install-the-official-skill)
- [Análisis de datos locales](https://ducklocal.app/es/use-cases/local-data-analysis/)
- [Lo que los paneles de Claude me enseñaron sobre DuckLocal](https://ducklocal.app/es/blog/claude-dashboards-ducklocal/)
- [DuckDB GUI](https://ducklocal.app/es/use-cases/duckdb-gui/)
- [Visor de Parquet](https://ducklocal.app/es/use-cases/parquet-viewer/)
- [Consultar CSV con SQL](https://ducklocal.app/es/use-cases/query-csv-with-sql/)
- [Paneles SQL](https://ducklocal.app/es/use-cases/sql-dashboards/)
- [DuckLocal vs DBeaver](https://ducklocal.app/es/compare/ducklocal-vs-dbeaver/)

Source: https://ducklocal.app/es/use-cases/ai-agent-sql/
