Ir al contenido

CLI de IA y habilidad oficial ​

Para una visión general orientada a tareas, consulta SQL para agentes de IA sobre datos locales. Esta página es la referencia completa de comandos y salida.

Ejecuta sin ventana ​

ducklocal --help lista diez subcomandos:

ComandoQué hace
ducklocal queryEjecuta una sentencia SQL e imprime el resultado como JSON
ducklocal schemaLista qué se puede consultar, con sus columnas; --stats para las estadísticas de columnas de una relación
ducklocal openMuestra SQL, un panel o datos en la ventana en ejecución; --state vuelve a leer lo que muestra
ducklocal checkValida un panel .dash
ducklocal metricsLista las métricas de un modelo semántico; compile o query para compilarlas o consultarlas
ducklocal commentsLee y responde los comentarios de revisión que la gente dejó en un panel
ducklocal proposePropone un cambio en un panel para que la persona lo revise y lo aplique
ducklocal projectComprueba una carpeta de análisis portátil y lo que necesita; relink arregla rutas movidas
ducklocal sessionVuelve a leer cómo llegó un análisis adonde llegó
ducklocal presenceMuestra quién está trabajando en un panel abierto y dónde caerá una edición

ducklocal lsp, el servidor de lenguaje que los editores lanzan para archivos .dash, y ducklocal profile, el alias heredado de schema --stats, siguen funcionando, pero se omiten de --help.

propose, project y session, y las opciones --restricted, --wait y --if-revision, llegaron en 0.4.0 y se tratan en Flujos de trabajo de agentes. metrics y --format html son posteriores a 0.4.1: están en la rama main y llegarán con la próxima versión. metrics se trata en Métricas semánticas.

ducklocal query ejecuta SQL sin inicializar la GUI, el historial, los archivos registrados, los ajustes de idioma ni la conexión global de la GUI. Cada invocación crea una conexión dedicada. Invocar DuckLocal sin comandos —o solo con rutas de archivo, carpetas y patrones glob— abre la GUI normal. Para abrir en la GUI una ruta cuyo nombre coincide con un comando (query, schema, open, check, metrics, comments, propose, project, session, presence, profile o lsp), antepón ./, por ejemplo ./query.

Obtén el comando ​

DuckLocal admite macOS 12+ en Apple silicon, Windows (x86_64) y Linux (x86_64). La CLI se ejecuta directamente desde el ejecutable de la aplicación, así que no necesitas instalar un binario de la CLI de DuckDB aparte.

La forma más rápida de tenerlo en tu PATH es desde la app (0.1.1 y posteriores): abre Línea de comandos e IA… —el botón del robot de la barra de título, o el menú de DuckLocal— y haz clic en Instalar comando. Ese mismo diálogo instala la habilidad para agentes de IA; consulta Instala la habilidad oficial. Si te saltas la instalación, llama al ejecutable donde está:

bash
# macOS
/Applications/DuckLocal.app/Contents/MacOS/ducklocal --help
# Linux: wherever you extracted the tarball
./ducklocal-linux-x86_64/ducklocal --help
# Windows (PowerShell): wherever you extracted the zip
.\ducklocal-windows-x86_64\ducklocal.exe --help

Desde un checkout del código, cargo build --locked compila ./target/debug/ducklocal. Los ejemplos de aquí abajo dan por hecho que ducklocal está en tu PATH. Las versiones antiguas puede que no tengan query; comprueba --help primero. La compatibilidad con JSON y Parquet viene incluida, no se descarga en el momento de la consulta.

Opciones de query ​

bash
ducklocal --help
ducklocal --version
ducklocal query --help
ducklocal query --sql "SELECT 1 AS n"
ducklocal query --sql "SELECT 1 AS n" --format md
ducklocal query --sql-file analysis.sql --limit 100
ducklocal query --sql-file - < analysis.sql
ducklocal query --database warehouse.duckdb --sql "SHOW TABLES"
  • Se requiere exactamente uno de --sql SQL y --sql-file FILE. Los archivos deben ser UTF-8; - lee de stdin. El SQL debe contener exactamente una sentencia. El analizador de DuckDB lo valida antes de abrir la base de datos de destino o de ejecutar nada; los comentarios, los puntos y coma entre comillas y el punto y coma final funcionan. Los scripts se rechazan, no se ejecutan a medias.
  • --database PATH abre un archivo existente, de solo lectura de forma predeterminada. Omítelo para una base de datos en memoria nueva. --read-write requiere --database y permite explícitamente escribir y crear una base de datos (no las carpetas superiores). Los errores de base de datos nunca recurren a la memoria. Cuando DuckDB rechaza un archivo, el mensaje de error empieza por el motivo que DuckLocal lee de la cabecera del archivo —escrito por una DuckDB más nueva, un archivo de la época de la v0.9, un archivo SQLite o algo que no es una base de datos— y por lo que hay que ejecutar en su lugar (para un archivo más nuevo, la copia con ATTACH … (STORAGE_VERSION) / COPY FROM DATABASE que hay que hacer en esa versión; para SQLite, el ATTACH que lo lee), por delante del mensaje propio de DuckDB.
  • --limit N es un entero positivo, vale 1000 por defecto y limita las filas devueltas. También se aplica un presupuesto de 2.000.000 de celdas. Después del límite, la CLI sigue contando hasta 100.000 filas más sin codificar sus valores, e informa de total_rows y total_rows_exact. Esto limita la salida, no el cálculo ni la memoria: la ordenación y las agregaciones pueden seguir procesando toda la entrada. Un error de ejecución que aparezca después del límite de salida sigue haciendo fallar el comando.
  • --format json (el valor predeterminado) es el contrato que hay más abajo. --format md representa el mismo resultado como una tabla Markdown, para un documento o para un agente que lo lea. --format html lo representa como una única página web autónoma; consulta Salida HTML. Nada más cambia: el mismo SQL, los mismos límites, los mismos errores.
  • Las flags repetidas o desconocidas, los valores que faltan, el SQL vacío y los límites no válidos son errores. Las opciones usan valores separados, no --flag=value. Las rutas relativas se resuelven contra el directorio de trabajo del proceso, no contra el del archivo SQL. Pon comillas en las rutas del shell; dentro del SQL, duplica los apóstrofos ('O''Brien.csv'). Los identificadores SQL usan comillas dobles.

Solo lectura no es una sandbox de sistema de archivos ni de red. SQL como COPY puede escribir archivos incluso cuando la base de datos es de solo lectura. Autoriza las rutas de salida, las sobrescrituras, las mutaciones de la base de datos, la instalación de extensiones y el acceso externo antes de ejecutar. DuckLocal no instala extensiones automáticamente ni reintenta operaciones. El SQL explícito INSTALL/LOAD sigue siendo posible con autorización; las extensiones instaladas pueden cargarse solas. Un comando que falla puede haber causado ya efectos secundarios (por ejemplo, antes de un fallo de salida); inspecciona el destino antes de reintentar.

Salida Markdown ​

--format md es una representación, no un segundo contrato: los valores son los que contiene el JSON, escritos como los muestra la cuadrícula de resultados.

ValorSe representa como
NULLNULL
entero, decimal, floatlos dígitos que lleva el valor, exactamente — un DECIMAL(38,10) conserva su escala, NaN/inf/-inf se escriben tal cual
DATEYYYY-MM-DD
TIMESTAMPYYYY-MM-DD HH:MM:SS[.fffffffff], con la fracción solo cuando el valor la tiene, y con tantos dígitos como tenga. No se añade zona horaria; --format json conserva el recuento en bruto
TIMEHH:MM:SS[.ffffff]
INTERVALcomo lo escribe DuckDB: 1 month 2 days 00:00:00.000003
BLOB, GEOMETRY0x00ff, elidido con … cuando es largo
LIST, STRUCT, MAP[1, 2], {x: 1}, elidido con … a partir de 120 caracteres

Un | en una celda se escapa y un salto de línea pasa a ser <br>, así que un valor no puede romper la tabla en la que está. A un resultado sin filas le sigue _0 rows._, y a un resultado que --limit o el presupuesto de celdas cortaron, _Truncated at 2 of 5000 rows, so this is not the whole answer._ (of at least … cuando pasó del recuento de 100.000 filas): una previsualización no debería leerse como una respuesta completa. Los errores no cambian: JSON en stderr, stdout vacío.

Salida HTML ​

bash
ducklocal query --sql "SELECT * FROM 'sales.csv'" --format html > sales.html

--format html escribe los mismos valores que --format md como una sola página web:

  • El número de filas y columnas, el tiempo transcurrido y el SQL detrás del resultado, plegado.
  • Los nombres de las columnas con sus tipos. Los números se alinean a la derecha y los NULL se marcan.
  • Haz clic en un encabezado para ordenar; los NULL quedan al final. Escribe en el cuadro de filtro para quedarte solo con las filas que coinciden.
  • Un resultado recortado por --limit o por el presupuesto de celdas lo indica, como en Markdown.

El estilo y el script van incrustados y la página no descarga nada, así que se abre desde el disco y se puede publicar tal cual, por ejemplo en GitHub Pages. Cada celda se escapa como HTML.

Mapea qué se puede consultar ​

ducklocal schema responde a «¿qué hay y cuáles son sus columnas?» en una sola llamada, mientras que DESCRIBE lo responde relación a relación. Es lo primero que debería ejecutar un agente.

bash
ducklocal schema ./data/                          # files, folders, globs
ducklocal schema --database warehouse.duckdb      # tables and views
ducklocal schema warehouse.duckdb --table orders  # one relation, whole
ducklocal schema ./logs/ --full                   # everything, however large

Las rutas PATH se expanden como cuando arrastras algo a la ventana: los archivos de datos de una carpeta de forma recursiva (se omiten los ocultos, como máximo 256), las coincidencias de un glob y un archivo de base de datos como si se diera con --database. Vuelve un único objeto JSON:

json
{"detail":"full","relations":[{"name":"data/orders.csv","kind":"file","from":"'data/orders.csv'","rows":null,"column_count":2,"path":"data/orders.csv","columns":[{"name":"channel","type":"VARCHAR"},{"name":"amount","type":"BIGINT"}]}],"without_columns":0}
CampoSignificado
nameLa ruta de un archivo tal como se dio (relativa al directorio de trabajo cuando está dentro de él), o el nombre de una tabla tal como lo alcanza el SQL en esta conexión: sin calificar en el esquema predeterminado, schema.table en otro caso
kindfile, glob, table, view o workbook
fromEl SQL que lo lee, listo para seguir a FROM: una ruta entre comillas, o un identificador entre comillas cuando hace falta
rowsLa estimación del catálogo para una tabla, exacta para Parquet (desde su footer), null donde saberlo exigiría un escaneo: CSV, JSON, vistas
column_count, columnsLas columnas tal como las describe DuckDB
filesPara un glob: cuántos archivos coinciden

Un glob cuyas coincidencias son todas de un mismo formato es una sola relación, leída como la lee un source de .dash (ducklocal schema 'logs/*.csv'); --stats la perfila como una. Un glob con formatos mezclados, y una carpeta, listan sus archivos uno a uno.

Un catálogo pequeño vuelve entero ("detail": "full"). A partir de 12 relaciones o 400 columnas es un resumen ("detail": "summary"). Las 5 relaciones con más filas conservan sus columnas; el resto lista nombre, tipo, filas y número de columnas, y without_columns las cuenta. Para obtener más, hint nombra las dos maneras: --table NAME para una relación (buscada por su nombre, por su nombre de tabla sin calificar o por el nombre de un archivo) y --full para todas. Un libro se lista con sus sheets y sin columnas, ya que no tiene función de tabla; --stats lee su primera hoja. Una ruta PATH que no existe, o un --table que no nombra nada, sale con código 2.

El texto con gzip como .json.gz y .csv.gz es aquí un archivo de datos, igual que lo es para los bloques source y para la ventana. Un archivo cuyos registros están en una sola lista —el {"Records": [...]} de CloudTrail, por ejemplo— vuelve con un hint: el SQL que lee esos registros como filas, ya que de otro modo la única fila y la única columna describen solo el envoltorio.

Explora y convierte archivos ​

Después de confirmar que el archivo real existe:

bash
ducklocal query --sql "DESCRIBE SELECT * FROM 'sales.csv'"
ducklocal query --sql "SELECT * FROM 'sales.csv'" --limit 20
ducklocal query --sql "SELECT sum(amount) AS total FROM 'sales.csv'"
# Only after authorizing this output path:
ducklocal query --sql "COPY (SELECT * FROM 'sales.csv') TO 'sales.parquet' (FORMAT PARQUET)"
ducklocal query --sql "SELECT count(*), sum(amount) FROM 'sales.parquet'"
ducklocal query --sql "DESCRIBE SELECT * FROM 'events.json'"

No des por hecho que amount existe: ejecuta ducklocal schema o DESCRIBE primero. Calcula las agregaciones completas en SQL en lugar de sumar una previsualización truncada. Las llamadas de la CLI no comparten las vistas registradas de la GUI ni las tablas en memoria de otras llamadas. Persiste de forma explícita cuando haga falta:

bash
# These are separate statements and separate invocations, with explicit write permission.
ducklocal query --database warehouse.duckdb --read-write --sql "CREATE TABLE sales AS SELECT * FROM 'sales.csv'"
ducklocal query --database warehouse.duckdb --sql "SELECT count(*) FROM sales"

Un conflicto de bloqueo de la base de datos es un error. Cierra el otro escritor (incluida la GUI) o usa una copia autorizada; nunca borres archivos de bloqueo ni crees en silencio una base de datos distinta.

JSONL y JSON anidado ​

read_ndjson_objects es el lector para JSON delimitado por saltos de línea (un objeto por línea, .jsonl/.ndjson); read_json/read_json_auto leen documentos JSON (un array o un único objeto). Nombra el lector de forma explícita para un archivo JSONL en lugar de confiar en la detección automática. json_extract_string(col, '$.a.b[0].c') recorre una ruta anidada —claves de objeto e índices de array— y devuelve VARCHAR:

bash
ducklocal query --sql "SELECT json_extract_string(event, '$.payload.items[0].sku') AS sku, count(*) AS n FROM read_ndjson_objects('events.jsonl') GROUP BY 1 ORDER BY n DESC"

Usa json_extract en su lugar cuando la hoja no sea una cadena y la quieras como JSON.

Estadísticas de columnas ​

ducklocal schema --stats responde a las preguntas que deciden un gráfico, una escala y un formato de número, antes de construir nada sobre ellas. DESCRIBE dice que una columna es DOUBLE; sus estadísticas dicen que usa dos decimales, que su valor mayor es mil veces su mediana y que sus fechas se saltan once días en medio.

bash
ducklocal schema sales.csv --stats
ducklocal schema ./exports/ --table orders.parquet --stats
ducklocal schema --database warehouse.duckdb --table "my orders" --stats

--stats perfila una sola relación: la única que nombran los argumentos, o la que elige --table —dos o más sin --table es código 2, con un hint que lo dice—. No se puede combinar con --full. ducklocal profile TARGET [--database PATH], de versiones anteriores, es el mismo informe y sigue funcionando.

La relación es un archivo de datos —csv, tsv, txt, parquet, json, ndjson, jsonl—, un libro (xlsx, xls, xlsb, ods; su primera hoja se importa como tabla TEMP y se perfila) o, con --database, el nombre de una tabla o vista. Un nombre con puntos se lee como schema.table y cada parte va entre comillas, así que un nombre con un espacio o una mayúscula funciona tal como se escribe. Una relación que no nombra nada es un error de argumentos (código 2), no uno de SQL.

Vuelve un único objeto JSON: target, relation (el SQL sobre el que se ejecutaron las estadísticas), row_count, elapsed_ms y columns en el orden propio de la relación. Por columna:

CampoSignificado
name, typetal como los informa DESCRIBE
nullsfilas en las que la columna es NULL
distinctexacto, no estimado
uniquepresente y true cuando distinct es igual a row_count
min, maxcomo texto, para que un DECIMAL conserve sus dígitos
decimalsdígitos después del punto que la columna usa realmente, que no es su escala declarada
medianun valor que la columna contiene, no una interpolación entre dos de ellos
max_over_mediancuántas veces el valor mayor es más grande que la mediana: el número que decide un eje lineal frente a uno logarítmico
covered_days, span_days, missing_daysdías que nombra la columna, días entre sus extremos y la diferencia: 0 es una serie continua, cualquier otra cosa son huecos que una línea dibujaría por encima

decimals, median y max_over_median aparecen en las columnas numéricas; los campos de días, en fechas y timestamps. Las columnas LIST, STRUCT, MAP y UNION solo informan de nulls: min y max no están definidos en ellas.

Una columna de texto que contiene números y una palabra corta, como el NA de R, informa además de null_marker y null_marker_rows. El informe añade entonces un hint que nombra la llamada a read_csv que lee la columna como números.

Las estadísticas son exactas y leen toda la relación, así que cuestan un escaneo completo. --limit no se aplica: el perfil de una muestra no es un perfil.

Muestra el trabajo en la ventana en ejecución ​

ducklocal open entrega algo a la ventana de DuckLocal que ya está en ejecución —y la inicia si no hay ninguna— y la trae al frente. Es cómo un agente pone su trabajo delante de una persona, para que pueda seguir desde ahí:

bash
ducklocal open --title "Revenue by channel" --run --sql "SELECT channel, sum(amount) AS total FROM 'orders.csv' GROUP BY 1"
ducklocal open sales.dash                    # a dashboard tab
ducklocal open ./data/ --sql-file analysis.sql
echo "SELECT 42" | ducklocal open --sql-file - --no-launch
  • Las rutas PATH se abren como cuando arrastras algo a la ventana: un archivo .dash como pestaña, un archivo de base de datos DuckDB como base de datos de la ventana, y archivos de datos, carpetas y globs adjuntos como vistas. Las rutas PATH relativas se resuelven contra el directorio del comando. Una petición que llega mientras la ventana aún está arrancando espera a que termine su apertura de inicio.
  • --sql o --sql-file (- lee de stdin) abre una pestaña de consulta nueva, titulada --title. --run la ejecuta una vez que las rutas PATH se han adjuntado.
  • --no-launch falla con kind not_running en lugar de iniciar una ventana, para una máquina donde una ventana que aparece sin pedirla no sería bien recibida.

El éxito imprime {"delivered": true, "launched": BOOL}: la entrega, no un resultado. Lo que se abre se ejecuta en la sesión propia de la ventana —su conexión, sus vistas adjuntas, su historial— y cualquier error aparece allí, no en stdout. Código 2 para los argumentos; 1 con kind not_running (no se alcanza ninguna ventana), refused (la ventana rechazó la petición) o launch.

La ventana escucha en un puerto de loopback. Escribe el puerto y un token aleatorio en un archivo que solo tu cuenta puede leer (consulta Ajustes y datos de la app); otro usuario de la máquina, o una página web que apunte a localhost, no puede alcanzarla.

Lee lo que muestra la ventana ​

ducklocal open --state va en la otra dirección: no abre nada, nunca inicia una ventana e imprime lo que muestra la ventana en ejecución, para que un agente pueda retomar donde lo dejó una persona en lugar de pedirle que pegue su consulta.

bash
ducklocal open --state
ducklocal open --state sales.dash
ducklocal open --state --active
json
{"database":":memory:","attached":[{"path":"/Users/me/data/orders.csv","name":"orders","rows":224}],"active_tab":1,"tabs":[{"kind":"query","title":"Query 1","active":false,"sql":"SELECT …","result":{"status":"rows","columns":[…],"row_count":5,"truncated":false,"preview":[["Web","132771.24"],…],"sql":"SELECT …","elapsed_ms":4}},{"kind":"dashboard","title":"sales","active":true,"path":"/Users/me/data/sales.dash","unsaved":false,"dashboard":{"running":false,"error":null,"stale":null,"plots":[…],"filters":[{"name":"channel","plot":"revenue_by_channel","column":"channel","picked":true,"value":"Web"}]}}]}
  • database es el archivo de base de datos abierto, o ":memory:"; attached lista los archivos que la ventana registró como vistas, con el name de la vista. Una consulta de la CLI no puede leer esas vistas: usa el path.
  • Una pestaña de consulta tiene sql, el texto del editor se haya ejecutado o no, y result: status es empty, running, rows, affected, failed, explain o profile. Para filas: columns, row_count, truncated, preview (las primeras 20 filas tal como las muestra la cuadrícula, como cadenas), elapsed_ms y el sql que las produjo; para affected, count y elapsed_ms; para un fallo, error.
  • Una vez que la persona ha elegido columnas en la pestaña Gráfico, un resultado tiene además chart: type, x, y, split y dash, un bloque query y otro plot que dibujan el mismo gráfico en un panel.
  • explain es lo que muestra Explain: plan, la salida de EXPLAIN de DuckDB como un array de líneas de texto, y elapsed_ms.
  • profile es lo que muestra Perfil (consulta Editor SQL): plan, el árbol de operadores que midió EXPLAIN ANALYZE, como un array de raíces, cada una {operator, seconds, rows, estimated, children} — seconds es el tiempo propio del operador sin sus hijos, rows lo que produjo, estimated la estimación del optimizador para rows (null donde el plan no indica ninguna) y children la misma forma otra vez. operator_seconds es la suma del tiempo propio de cada operador, que es a lo que suman las partes, no el tiempo de reloj; elapsed_ms es la ejecución completa.
  • Una pestaña de panel tiene path, unsaved y dashboard: la ruta de su comments_file, sus plots (nombre, tipo, título, consulta, filas, open_comments y failure cuando uno no puede dibujar) y sus filters con lo que ha elegido cada uno: picked, value (el primer valor), values (todos los valores elegidos, en orden) y multiple. value: null con picked: true significa que se eligió el valor NULL.

Usa --state sales.dash para quedarte solo con las pestañas que muestran ese panel, o --state --active para solo la pestaña activa. Una ruta que no está abierta devuelve código 1, kind not_open, con los paneles abiertos en el hint. active_tab es el índice de la pestaña activa dentro de las tabs devueltas, o null si no está entre ellas; database y attached se siguen incluyendo.

--state acepta una ruta .dash o --active, no ambas. --no-launch se acepta y no cambia nada. Otras opciones, incluidas --sql y --run, no son válidas (código 2). Código 1 con kind not_running cuando no hay ninguna ventana en marcha, y timeout cuando no responde en 5 segundos.

Comprueba una especificación de panel ​

El formato en sí —bloques, atributos, tipos de gráfico, reglas de SQL y mensajes habituales— se describe en Paneles (.dash); esta sección cubre el comando.

Un archivo .dash declara un panel como Terraform declara infraestructura —consultas y gráficos como bloques, referencias entre ellos— en lugar de programarlo. Es fácil de escribir y de comparar con diff, tanto para una persona como para un agente.

hcl
query "latency" {
  sql = <<SQL
    SELECT timestamp, service, avg(latency) AS latency
    FROM logs
    GROUP BY timestamp, service
  SQL
}

plot "latency" {
  type   = "line"
  query  = query.latency
  x      = timestamp
  y      = latency
  series = service
}
bash
ducklocal check dashboard.dash
ducklocal check dashboard.dash --database warehouse.duckdb
ducklocal check dashboard.dash --summary

Un bloque source nombra archivos de datos, relativos al archivo .dash, para que los lean las consultas, y un bloque view contiene SQL que comparten varias consultas. Un bloque query contiene un atributo sql —una sentencia de solo lectura, como heredoc o como cadena—. Se aceptan SELECT, WITH, los que empiezan por FROM, VALUES, SHOW, DESCRIBE, SUMMARIZE y PIVOT; cualquier cosa que pueda escribir —DDL, DML, COPY, ATTACH, INSTALL— es un diagnóstico, y la GUI se niega a ejecutarla, porque las consultas de un panel se ejecutan cada vez que se abre el archivo. Un bloque plot contiene type (uno de line, bar, stacked_bar, area, scatter, pie, heatmap, histogram, map, timeline, table, card, text), query (una referencia como query.latency a un bloque de consulta del mismo archivo), sus columnas y, opcionalmente, title y width. Un bloque filter hace que un gráfico de barras o una tabla sean clicables —un valor, o varios con multiple = true en una barra— y una consulta lee la elección como $name. # y // comentan hasta el final de la línea. Paneles (.dash) tiene todos los atributos.

Un gráfico text es la excepción: contiene title, text o ambos y no acepta query. Las tarjetas también pueden usar note y tone; consulta Tarjetas y paneles de texto.

Primero las comprobaciones estáticas: el SQL de cada consulta pasa por el analizador real de DuckDB en una conexión desechable, como lo valida query antes de ejecutar, y cada $name se contrasta con los bloques filter: el SQL se analiza y se ejecuta con cada $name como TRUE, que es lo que ejecuta el panel antes de que se elija nada.

Después se ejecuta cada consulta, exactamente como la ejecutaría abrir el panel —de solo lectura, con sus fuentes, por el mismo código y con el mismo presupuesto de filas—, y las columnas de cada gráfico se comprueban contra las columnas que la consulta devuelve realmente: un y que no es numérico es un error para cualquier tipo de gráfico, y también lo son las coordenadas no numéricas de un mapa o su size, y una column de filtro que la consulta de su gráfico no devuelve.

  • Sin --database las consultas se ejecutan en memoria, que es todo lo que necesita un panel sobre sus propios archivos source. Una consulta que lee una tabla que ninguna fuente define puede estar pensada para una base de datos que no se le pasó a la comprobación: se lista en unresolved (consulta, línea, motivo) en lugar de fallar, y las columnas de sus gráficos no se comprueban.
  • Con --database PATH (archivo existente, de solo lectura) se ejecutan sobre esa base de datos. Pásala siempre que las consultas lean tablas de una base de datos: todo lo que quede en unresolved no se comprobó.

Toda consulta que lee un filtro se vincula además con un valor elegido, sin ejecutar esa variante. Así se detecta una columna de filtro que falta en una consulta consumidora, incluso cuando la versión inicial con $name = TRUE funciona. Un filtro también debe referenciar una columna que devuelva su gráfico selector.

Ejecutar y no solo planificar importa: algunos fallos, como un cast que la compilación no puede hacer o un valor que no se convertirá, aparecen solo cuando se leen filas, y una comprobación que los dejara pasar entregaría un panel que no puede dibujar. Las consultas se ejecutan enteras, así que una comprobación contra una base de datos grande tarda lo mismo que abrir el panel.

El éxito es un único objeto JSON que lista las fuentes del archivo (con su ruta resolved), las vistas, las consultas (con sus columnas de resultado y rows, cuántas devolvió cada una sin nada elegido, además de truncated: true cuando el presupuesto de filas del panel la cortó), los filtros (con las queries que lee cada uno), los gráficos, unresolved y empty: las consultas que se ejecutaron y no devolvieron filas. Una consulta vacía pasa todas las demás comprobaciones, pero normalmente es una regex, un filtro o un join que no encontró nada, así que revísalas una a una. Con --summary, el éxito es una línea JSON compacta:

json
{"file":"sales.dash","ok":true,"sources":1,"views":0,"queries":3,"filters":1,"plots":6,"unresolved":[],"empty":[]}

Los cinco campos de bloque son recuentos; unresolved lista las consultas que no se pudieron comprobar y empty las que no devolvieron filas.

Un bloque defectuoso se omite mientras los bloques válidos siguen por la validación. Los errores de especificación y los fallos de consulta se reúnen en la misma ejecución, uno file:line: message cada uno. Si hay algún diagnóstico de especificación, la salida es 2 con kind spec; si solo falla la ejecución o el vínculo de SQL, es 1 con kind sql. Los fallos de base de datos y de E/S también salen con 1. --summary no oculta los diagnósticos.

El mismo archivo se abre como pestaña de panel en la GUI — ducklocal dashboard.dash, ducklocal open dashboard.dash, o arrástralo a la ventana — con los gráficos en una cuadrícula de 12 columnas y un gráfico que no puede dibujar mostrando el motivo en línea. Consulta Paneles (.dash).

Métricas de un modelo semántico ​

bash
ducklocal metrics                       # ./model.ossie.yaml
ducklocal metrics compile --metric error_count,event_count --by events.ip
ducklocal metrics query --metric event_count --by events.event_time:day \
  --views reports/investigation.dash --restricted --allow-read data

ducklocal metrics lee un modelo de Apache Ossie, model.ossie.yaml, y lista sus métricas y campos. compile imprime el único SELECT de DuckDB que responde a una petición, sin leer datos; query lo ejecuta como lo hace ducklocal query, con un objeto semantic que indica el SQL y el sha256 del modelo. Una petición que el modelo no puede responder con exactitud se rechaza, con código de salida 2 y un kind como metric_fanout. Métricas semánticas describe el formato del modelo, cada opción y cada rechazo.

Revisa los comentarios de un panel ​

La gente revisa un panel comentando sus gráficos en la ventana: pasa el cursor por un gráfico y haz clic en la burbuja de diálogo (consulta Revisar con comentarios). ducklocal comments es el lado del agente: lee los hilos y los responde, sin ventana.

bash
ducklocal comments sales.dash [--all]
ducklocal comments sales.dash --reply c1 --text "Sorted by revenue, descending" [--resolve]
ducklocal comments sales.dash --resolve c1
ducklocal comments sales.dash --reopen c1
ducklocal comments sales.dash --add revenue_by_channel --text "Is this net of refunds?"
  • Sin ninguna acción, imprime los hilos abiertos: {file, comments_file, open, threads}. --all incluye los resueltos.
  • Cada hilo tiene id, plot y lo que el agente necesita para encontrarlo en la especificación: plot_title, plot_query y plot_lines, la primera y la última línea del bloque plot (null cuando la especificación no se analiza). plot_missing es true cuando ya no queda ningún gráfico con ese nombre. Luego resolved y comments, cada uno con author (user o agent), en un comentario de agente su name (el nombre que muestra presence), text y at (RFC 3339, hora local).
  • --reply ID --text TEXT añade la respuesta del agente. Una respuesta a un hilo resuelto lo reabre, a menos que se dé también --resolve.
  • --resolve ID y --reopen ID cambian el estado de un hilo; --add PLOT --text TEXT inicia un hilo, firmado como el agente.
  • El número de un hilo sirve como su ID: --reply 1 significa c1. --add rechaza un gráfico que la especificación no tiene (código 2), y el hint lista sus gráficos.
  • Una acción imprime {thread}, tal como quedó.

Los hilos se guardan junto a la especificación, en FILE.comments.json. Una ventana en ejecución nota un cambio en menos de un segundo y lo muestra en el gráfico. Un id de hilo desconocido es código 2, con un hint para listar los hilos; un archivo de especificación que no existe es código 1.

Una revisión, de principio a fin: lee los hilos abiertos, edita la especificación, ejecuta ducklocal check y luego responde a cada hilo con lo que cambió y --resolve. Usa --reply sin --resolve para preguntarle algo a la persona.

Muestra la actividad del agente ​

check y comments avisan automáticamente a una ventana en ejecución de en qué panel está trabajando el agente. presence puede anunciar una edición antes de que ocurra:

bash
ducklocal presence sales.dash --doing editing --plot revenue_by_channel,daily_revenue
ducklocal presence sales.dash --doing reading --agent "Analyst"
ducklocal presence sales.dash --doing idle
  • --doing acepta reading, editing o idle (done es un alias de idle).
  • --plot toma nombres de gráfico separados por comas. Con editing, se permiten nombres nuevos y aparecen como marcadores de posición. Con reading o idle, un nombre desconocido es código 2.
  • El nombre que se muestra viene de --agent, luego de DUCKLOCAL_AGENT, luego del entorno de agente detectado (Claude, Codex, Cursor o Gemini), y si no, de Agent.
  • La salida es {delivered}. Sin una ventana en ejecución produce {"delivered":false} sin error y sin iniciar ninguna ventana.

El nombre se queda en la esquina del panel mientras los comandos mantienen la sesión activa. Haz clic en él para ver el registro de actividad. Treinta segundos de silencio o --doing idle terminan la sesión; los gráficos modificados y añadidos siguen marcados hasta que se ven, y los avisos de gráficos eliminados, hasta que se descartan. Consulta Ver a un agente trabajar.

Edita una especificación de panel con LSP ​

ducklocal lsp es un servidor del Protocolo de Servidor de Lenguaje para archivos .dash, sobre stdio, para que lo lancen los editores. Da a cualquier editor compatible con LSP lo mismo que tiene el editor de especificaciones de la GUI:

  • Diagnósticos: los que informa check, publicados en cada apertura y cada cambio (sincronización de documento completo, todos con severidad Error: son errores, no estilo).
  • Autocompletado: tipos de bloque, nombres de atributo, tipos de gráfico y los nombres tras query. y plot., cada uno con una edición de texto que sustituye la palabra que se está escribiendo.
  • Hover: documentación de bloques, atributos y referencias.
  • Ir a la definición: desde una referencia query.name o plot.name hasta el nombre de su bloque.

Con --database PATH, el SQL de cada consulta se valida además con el analizador real de DuckDB, como hace check --database.

Apunta el soporte LSP genérico de tu editor a ducklocal lsp para archivos *.dash: el comando no toma argumentos de documento; el editor habla con él por stdio. En Neovim (0.10+):

lua
vim.api.nvim_create_autocmd("FileType", {
  pattern = "dash",
  callback = function(event)
    vim.lsp.start({
      name = "ducklocal",
      cmd = { "ducklocal", "lsp" },
      root_dir = vim.fs.dirname(vim.api.nvim_buf_get_name(event.buf)),
    })
  end,
})

En VS Code, cualquier extensión de LSP genérico hace lo mismo con el comando ducklocal, los argumentos ["lsp"] y el selector de documento dash. Códigos de salida: 0 tras un shutdown/exit limpio, 1 cuando el cliente se va sin hacerlo, 2 para una línea de comandos incorrecta o un handshake de protocolo fallido.

Contrato JSON ​

Las consultas correctas escriben exactamente un objeto JSON en stdout, seguido de un salto de línea:

json
{"columns":[{"name":"n","type":"Int32"}],"rows":[[1]],"row_count":1,"truncated":false,"total_rows":1,"total_rows_exact":true,"elapsed_ms":1}

columns y cada fila conservan el orden de las columnas y los nombres duplicados. type es la representación de depuración de Arrow, no el nombre de tipo SQL original de DuckDB (por ejemplo, HUGEINT y DECIMAL pueden compartir un portador de Arrow). row_count cuenta las filas devueltas. total_rows cuenta las filas producidas, incluidas las contadas después del límite de salida; total_rows_exact: false significa que el recuento se detuvo tras hasta 100.000 filas adicionales, así que ese total es un límite inferior. Ninguno de los dos recuentos es un recuento de filas afectadas. elapsed_ms mide la preparación, la ejecución y la codificación de filas, no la carga de archivos ni la creación de la conexión. Los resultados con cero filas conservan los metadatos. DDL/DML exponen el resultado real de DuckDB, incluidas las columnas Count: INSERT/COPY suelen devolver [[N]]; CREATE TABLE normalmente no devuelve filas. No se clasifican a partir de la primera palabra clave del SQL.

Codificación de las celdas:

Valor SQLCodificación JSON
NULLnull (nunca la cadena "NULL")
Booleano, float finitobooleano o número JSON
Entero dentro de ±9.007.199.254.740.991número JSON
Entero mayor, incluidos HUGEINT/UHUGEINT{"encoding":"integer","value":"9007199254740992"}
Decimal{"encoding":"decimal","value":"123.450"} con el texto decimal exacto
Texto, enumcadena JSON
Blob, geometry{"encoding":"hex","value":"00ff"}; bytes en minúsculas, geometry usa WKB
Date{"encoding":"date","unit":"Day","value":"1","iso":"1970-01-02"}; días desde 1970-01-01
Timestamp{"encoding":"timestamp","unit":"Nanosecond","value":"123456789","iso":"1970-01-01T00:00:00.123456789"}; recuento con signo desde la época Unix; la unidad también puede ser Second/Millisecond/Microsecond
Time{"encoding":"time","unit":"Microsecond","value":"123456","iso":"00:00:00.123456"}; recuento desde medianoche
Interval{"encoding":"interval","months":1,"days":2,"nanos":"3000"}
NaN, infinito positivo o negativo{"encoding":"float","value":"NaN"} / "inf" / "-inf"
List, arrayarray JSON, codificado de forma recursiva (incluidos los null anidados)
Struct{"encoding":"struct","fields":[["name",VALUE],...]}
Map{"encoding":"map","entries":[[KEY,VALUE],...]}; no es un objeto JSON, así que las claves conservan sus tipos
Union{"encoding":"union-value","value":VALUE}; solo el valor activo, la etiqueta de miembro no se conserva

Los value temporales son recuentos exactos, así que no se pierde precisión fraccionaria; los centinelas de infinito de fecha y timestamp siguen siendo recuentos en bruto. Junto a cada uno, iso es el mismo valor como texto ISO 8601 para leerlo, con tantos dígitos de fracción como admite la unidad. Un timestamp de una columna con zona horaria (metadatos de Arrow) es un instante UTC, y su iso termina en Z. --format md también representa fechas y timestamps de forma legible. Como el envoltorio de Arrow de DuckDB que está fijado no puede distinguir HUGEINT, UHUGEINT y DECIMAL(38,0) anidados, las apariciones no nulas producen un error claro en lugar de cambiar el signo o la precisión en silencio. Convierte esos campos explícitamente a VARCHAR en SQL. Los tipos no admitidos desconocidos también producen un error; no confundas un error con un resultado vacío. La codificación de union es una representación del valor activo, no un viaje de ida y vuelta sin pérdidas de una union.

Los errores escriben un objeto JSON en stderr, dejando stdout vacío:

json
{"error":{"kind":"argument","message":"Unknown query option: --limt","hint":"Did you mean --limit?"}}

hint está cuando se conoce el paso siguiente, en los términos de esta CLI: la flag que se quería escribir, --read-write para una escritura rechazada en una base de datos de solo lectura, ducklocal schema para una tabla que no existe, TRY_CAST para un valor que no se convertirá, dividir un script que tiene más de una sentencia, o AS para una palabra clave usada como alias de columna sin calificar (SELECT count(*) AS minutes, o ponlo entre comillas). Un agente debería actuar según él antes de reescribir el SQL. Falta cuando no hay nada que añadir al mensaje propio de DuckDB, como en un error de sintaxis.

Códigos de salida: 0 éxito, 2 argumentos o número de sentencias no válidos, 1 fallo de SQL, base de datos, E/S o salida. Los kinds de error son argument, sql, database, io, output, spec para check, y not_running, not_open, refused, timeout o launch para open. Comprueba el estado de salida antes de analizar stdout e inspecciona truncated antes de informar de que algo está completo. La ayuda y la versión son excepciones en texto plano. Los fallos de transporte, como un pipe de stdout cerrado, no pueden garantizar un flujo de salida vacío ni completo.

Instala la habilidad oficial ​

La habilidad enseña al agente los hábitos que mantienen honestas sus respuestas: inspeccionar el esquema, previsualizar una muestra acotada, calcular las agregaciones en SQL, comprobar truncated y responder a partir de los valores devueltos. Cubre la inspección de esquemas, las estadísticas de columnas, las conversiones, las consultas a bases de datos, los paneles .dash y sus comentarios de revisión, y entregar trabajo a la ventana y volver a leerlo; no ofrece navegación por S3, comandos específicos de datos espaciales, memoria de sesión ni un servidor MCP.

Desde la app. Abre Línea de comandos e IA… (el botón del robot de la barra de título, o el menú de DuckLocal):

  • Instalar comando pone ducklocal en tu PATH, para que el shell de un agente pueda ejecutarlo.
  • Añadir a Claude Code escribe la habilidad en ~/.claude/skills/ducklocal, donde Claude Code la encuentra en todos los proyectos. Solo se escriben los dos archivos propios de la habilidad; cualquier otra cosa en esa carpeta se conserva. Cuando una actualización de DuckLocal trae una habilidad más nueva, el diálogo ofrece Actualizar habilidad.
  • Copiar resumen copia una explicación breve para cualquier otro agente —Codex, Cursor, una ventana de chat—, con el nombre del comando y cómo usarlo.

A mano. La habilidad está en skills/ducklocal. Para añadirla a un solo proyecto en su lugar (ejemplo para Claude Code):

bash
# Run from the DuckLocal checkout; replace the destination with your project.
mkdir -p /path/to/your-project/.claude/skills
cp -R skills/ducklocal /path/to/your-project/.claude/skills/

Inspecciona primero un destino que ya exista en lugar de sobrescribir cambios locales. Otros agentes pueden usar el mismo SKILL.md más references/cli.md en el directorio de habilidades que admitan.

Publicado bajo la licencia Apache-2.0.