CLI de IA e skill oficial
Para a visão geral orientada a tarefas, veja SQL para agentes de IA sobre dados locais. Esta página é a referência completa de comandos e saída.
Execute sem janela
ducklocal --help lista dez subcomandos:
| Comando | O que faz |
|---|---|
ducklocal query | Executa uma instrução SQL e imprime o resultado como JSON |
ducklocal schema | Lista o que há para consultar, com as colunas; --stats para as estatísticas de colunas de uma relação |
ducklocal open | Mostra SQL, um painel ou dados na janela em execução; --state relê o que ela mostra |
ducklocal check | Valida um painel .dash |
ducklocal metrics | Lista as métricas de um modelo semântico; compile ou query para compilá-las ou consultá-las |
ducklocal comments | Lê e responde os comentários de revisão que as pessoas deixaram em um painel |
ducklocal propose | Sugere uma mudança no painel para a pessoa revisar e aplicar |
ducklocal project | Verifica uma pasta de análise portátil e do que ela precisa; relink corrige caminhos movidos |
ducklocal session | Relê como uma análise chegou onde chegou |
ducklocal presence | Mostra quem está trabalhando em um painel aberto e onde uma edição vai cair |
ducklocal lsp, o servidor de linguagem que os editores iniciam para arquivos .dash, e ducklocal profile, o alias legado de schema --stats, ainda funcionam, mas ficam de fora do --help.
propose, project e session, e as opções --restricted, --wait e --if-revision, chegaram na 0.4.0 e são tratados em Fluxos de trabalho de agentes. metrics e --format html são mais novos que a 0.4.1: estão no branch main e chegam na próxima versão. metrics é tratado em Métricas semânticas.
ducklocal query executa SQL sem inicializar a GUI, o histórico, os arquivos registrados, as configurações de idioma ou a conexão global da GUI. Cada invocação cria uma conexão dedicada. Invocar o DuckLocal sem comandos — ou apenas com caminhos de arquivo, pastas e padrões glob — abre a GUI normal. Para abrir na GUI um caminho cujo nome coincide com um comando (query, schema, open, check, metrics, comments, propose, project, session, presence, profile ou lsp), prefixe-o com ./, como em ./query.
Obtenha o comando
O DuckLocal tem suporte a macOS 12+ em Apple silicon, Windows (x86_64) e Linux (x86_64). A CLI roda direto do executável do aplicativo, então você não precisa instalar um binário separado da CLI do DuckDB.
O jeito mais rápido de colocá-lo no seu PATH é pelo app (0.1.1 e posteriores): abra Linha de comando e IA… — o botão do robô na barra de título, ou o menu do DuckLocal — e clique em Instalar comando. Esse mesmo diálogo instala a skill para agentes de IA; veja Instale a skill oficial. Se você pular a instalação, chame o executável onde ele está:
# 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 --helpA partir de um checkout do código, cargo build --locked compila ./target/debug/ducklocal. Os exemplos abaixo partem do princípio de que ducklocal está no seu PATH. Versões mais antigas podem não ter query; verifique --help primeiro. O suporte a JSON e Parquet vem incluído, não é baixado no momento da consulta.
Opções de consulta
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"- É obrigatório exatamente um entre
--sql SQLe--sql-file FILE. Os arquivos devem ser UTF-8;-lê da entrada padrão. O SQL deve conter exatamente uma instrução. O parser do DuckDB valida isso antes de abrir o banco de dados de destino ou de executar qualquer coisa; comentários, pontos e vírgulas entre aspas e o ponto e vírgula final funcionam. Scripts são rejeitados, não executados em parte. --database PATHabre um arquivo existente, somente leitura por padrão. Omita-o para um banco de dados novo em memória.--read-writeexige--databasee permite explicitamente escritas e a criação de um banco de dados (não das pastas superiores). Erros de banco de dados nunca caem para a memória. Quando o DuckDB recusa um arquivo, a mensagem de erro começa pelo motivo que o DuckLocal lê do cabeçalho do arquivo — escrito por um DuckDB mais novo, um arquivo da época da v0.9, um arquivo SQLite ou algo que não é um banco de dados — e pelo que executar em vez disso (para um arquivo mais novo, a cópia comATTACH … (STORAGE_VERSION)/COPY FROM DATABASEa fazer naquela versão; para SQLite, oATTACHque o lê), antes da mensagem do próprio DuckDB.--limit Né um inteiro positivo, tem 1000 como padrão e limita as linhas devolvidas. Também se aplica um orçamento de 2.000.000 de células. Depois do limite, a CLI continua contando até 100.000 linhas a mais sem codificar seus valores, informandototal_rowsetotal_rows_exact. Isso limita a saída, não o cálculo nem a memória: ordenação e agregações ainda podem processar toda a entrada. Um erro de execução encontrado depois do limite de saída ainda faz o comando falhar.--format json(o padrão) é o contrato descrito abaixo.--format mdrepresenta o mesmo resultado como uma tabela Markdown, para um documento ou para um agente que a leia.--format htmlo representa como uma única página web autocontida; veja Saída HTML. Nada mais muda: o mesmo SQL, os mesmos limites, os mesmos erros.- Flags repetidas ou desconhecidas, valores faltando, SQL vazio e limites inválidos são erros. As opções usam valores separados, não
--flag=value. Caminhos relativos são resolvidos a partir do diretório de trabalho do processo, não do diretório do arquivo SQL. Coloque aspas nos caminhos do shell; dentro do SQL, dobre os apóstrofos ('O''Brien.csv'). Identificadores SQL usam aspas duplas.
Somente leitura não é uma sandbox de sistema de arquivos nem de rede. SQL como COPY pode escrever arquivos mesmo quando o banco de dados é somente leitura. Autorize caminhos de saída, sobrescritas, mutações do banco de dados, instalação de extensões e acesso externo antes de executar. O DuckLocal não instala extensões automaticamente nem repete operações. SQL explícito de INSTALL/LOAD continua possível com autorização; extensões instaladas podem se autocarregar. Um comando que falhou pode já ter causado efeitos colaterais (por exemplo, antes de uma falha de saída); inspecione o destino antes de tentar de novo.
Saída em Markdown
--format md é uma renderização, não um segundo contrato: os valores são os que o JSON contém, escritos do jeito que a grade de resultados os mostra.
| Valor | Renderizado como |
|---|---|
NULL | NULL |
| inteiro, decimal, float | os dígitos que o valor carrega, exatamente — um DECIMAL(38,10) mantém sua escala, NaN/inf/-inf são escritos por extenso |
DATE | YYYY-MM-DD |
TIMESTAMP | YYYY-MM-DD HH:MM:SS[.fffffffff], com a fração só quando o valor tem uma, e com tantos dígitos quantos ela tiver. Nenhum fuso horário é acrescentado; --format json mantém a contagem bruta |
TIME | HH:MM:SS[.ffffff] |
INTERVAL | como o DuckDB escreve: 1 month 2 days 00:00:00.000003 |
BLOB, GEOMETRY | 0x00ff, abreviado com … quando longo |
LIST, STRUCT, MAP | [1, 2], {x: 1}, abreviado com … a partir de 120 caracteres |
Um | em uma célula é escapado e uma quebra de linha vira <br>, então um valor não consegue quebrar a tabela em que está. Um resultado sem linhas é seguido por _0 rows._, e um resultado cortado por --limit ou pelo orçamento de células por _Truncated at 2 of 5000 rows, so this is not the whole answer._ (of at least … depois da contagem de 100.000 linhas) — uma prévia não deveria soar como uma resposta completa. Os erros não mudam: JSON no stderr, stdout vazio.
Saída HTML
ducklocal query --sql "SELECT * FROM 'sales.csv'" --format html > sales.html--format html escreve os mesmos valores de --format md como uma única página web:
- O número de linhas e colunas, o tempo decorrido e o SQL por trás do resultado, recolhido.
- Os nomes das colunas com seus tipos. Números ficam alinhados à direita e os
NULLsão marcados. - Clique em um cabeçalho para ordenar; os
NULLficam por último. Digite na caixa de filtro para manter só as linhas que correspondem. - Um resultado cortado por
--limitou pelo orçamento de células avisa isso, como no Markdown.
O estilo e o script são embutidos e a página não baixa nada, então ela abre do disco e pode ser publicada como está, por exemplo no GitHub Pages. Cada célula é escapada para HTML.
Mapeie o que pode ser consultado
ducklocal schema responde "o que existe e quais são suas colunas?" em uma única chamada, enquanto DESCRIBE responde relação por relação. É a primeira coisa que um agente deveria executar.
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 largeCaminhos PATH se expandem como quando você arrasta algo para a janela: os arquivos de dados de uma pasta recursivamente (os ocultos são ignorados, no máximo 256), as correspondências de um glob e um arquivo de banco de dados como se fosse passado com --database. Volta um único objeto 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}| Campo | Significado |
|---|---|
name | O caminho de um arquivo como foi dado (relativo ao diretório de trabalho quando está dentro dele), ou o nome de uma tabela como o SQL nesta conexão a alcança: sem qualificação no esquema padrão, schema.table em outro caso |
kind | file, glob, table, view ou workbook |
from | O SQL que o lê, pronto para seguir um FROM: um caminho entre aspas, ou um identificador entre aspas quando necessário |
rows | A estimativa do catálogo para uma tabela, exata para Parquet (a partir do footer), null onde saber exigiria um scan — CSV, JSON, visões |
column_count, columns | As colunas como o DuckDB as descreve |
files | Para um glob: quantos arquivos ele corresponde |
Um glob cujas correspondências são todas de um mesmo formato é uma única relação, lida como um source de .dash a lê (ducklocal schema 'logs/*.csv'); --stats a analisa como uma. Um glob com formatos misturados, e uma pasta, listam seus arquivos um a um.
Um catálogo pequeno volta inteiro ("detail": "full"). A partir de 12 relações ou 400 colunas ele é um resumo ("detail": "summary"). As 5 relações com mais linhas mantêm suas colunas; as demais listam nome, tipo, linhas e número de colunas, e without_columns as conta. Para obter mais, o hint nomeia as duas maneiras: --table NAME para uma relação (buscada pelo nome, pelo nome da tabela sem qualificação ou pelo nome de um arquivo) e --full para todas. Uma pasta de trabalho é listada com suas sheets e sem colunas, já que não tem função de tabela; --stats lê sua primeira planilha. Um caminho PATH que não existe, ou um --table que não nomeia nada, sai com código 2.
Texto com gzip como .json.gz e .csv.gz é aqui um arquivo de dados, como é para blocos source e para a janela. Um arquivo cujos registros ficam em uma única lista — o {"Records": [...]} do CloudTrail, por exemplo — volta com um hint: o SQL que lê esses registros como linhas, já que, de outro modo, a única linha e a única coluna descrevem só o invólucro.
Explore e converta arquivos
Depois de confirmar que o arquivo real existe:
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'"Não presuma que amount existe: execute ducklocal schema ou DESCRIBE antes. Calcule as agregações completas em SQL em vez de somar uma prévia truncada. As chamadas da CLI não compartilham as visões registradas da GUI nem as tabelas em memória umas das outras. Persista explicitamente quando for preciso:
# 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"Um conflito de bloqueio do banco de dados é um erro. Feche o outro escritor (inclusive a GUI) ou use uma cópia autorizada; nunca apague arquivos de bloqueio nem crie silenciosamente um banco de dados diferente.
JSONL e JSON aninhado
read_ndjson_objects é o leitor para JSON delimitado por quebras de linha (um objeto por linha, .jsonl/.ndjson); read_json/read_json_auto leem documentos JSON (um array ou um único objeto). Nomeie o leitor explicitamente para um arquivo JSONL em vez de depender da detecção automática. json_extract_string(col, '$.a.b[0].c') percorre um caminho aninhado — chaves de objeto e índices de array — e responde VARCHAR:
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"Use json_extract em vez disso quando a folha não for uma string e você a quiser como JSON.
Estatísticas de colunas
ducklocal schema --stats responde às perguntas que decidem um gráfico, uma escala e um formato de número, antes de qualquer coisa ser construída sobre elas. DESCRIBE diz que uma coluna é DOUBLE; suas estatísticas dizem que ela usa duas casas decimais, que seu maior valor é mil vezes sua mediana e que suas datas pulam onze dias no meio.
ducklocal schema sales.csv --stats
ducklocal schema ./exports/ --table orders.parquet --stats
ducklocal schema --database warehouse.duckdb --table "my orders" --stats--stats analisa uma única relação: a única que os argumentos nomeiam, ou a que --table escolhe — duas ou mais sem --table é código 2, com um hint dizendo isso. Não pode ser combinado com --full. ducklocal profile TARGET [--database PATH], de versões anteriores, é o mesmo relatório e ainda funciona.
A relação é um arquivo de dados — csv, tsv, txt, parquet, json, ndjson, jsonl — ou uma pasta de trabalho (xlsx, xls, xlsb, ods; sua primeira planilha é importada como tabela TEMP e analisada), ou, com --database, o nome de uma tabela ou visão. Um nome com pontos é lido como schema.table e cada parte vai entre aspas, então um nome com espaço ou letra maiúscula funciona como escrito. Uma relação que não nomeia nada é um erro de argumento (código 2), não de SQL.
Volta um único objeto JSON: target, relation (o SQL contra o qual as estatísticas rodaram), row_count, elapsed_ms e columns na ordem própria da relação. Por coluna:
| Campo | Significado |
|---|---|
name, type | como o DESCRIBE informa |
nulls | linhas em que a coluna é NULL |
distinct | exato, não estimado |
unique | presente e true quando distinct é igual a row_count |
min, max | como texto, para que um DECIMAL mantenha seus dígitos |
decimals | dígitos depois do ponto que a coluna realmente usa, que não é sua escala declarada |
median | um valor que a coluna contém, não uma interpolação entre dois deles |
max_over_median | quantas vezes o maior valor é maior que a mediana — o número que decide um eixo linear em vez de um logarítmico |
covered_days, span_days, missing_days | dias que a coluna nomeia, dias entre suas pontas e a diferença: 0 é uma série contínua, qualquer outra coisa são buracos que uma linha desenharia por cima |
decimals, median e max_over_median aparecem em colunas numéricas; os campos de dias, em datas e timestamps. Colunas LIST, STRUCT, MAP e UNION informam somente nulls — min e max não são definidos nelas.
Uma coluna de texto que contém números e uma palavra curta, como o NA do R, também informa null_marker e null_marker_rows. O relatório então acrescenta um hint nomeando a chamada de read_csv que lê a coluna como números.
As estatísticas são exatas e leem a relação inteira, então custam um scan completo. --limit não se aplica: o perfil de uma amostra não é um perfil.
Mostre o trabalho na janela em execução
ducklocal open entrega algo à janela do DuckLocal que já está em execução — iniciando uma se não houver nenhuma — e a traz para a frente. É assim que um agente põe seu trabalho na frente de uma pessoa, onde ela pode continuar a partir dali:
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- Caminhos PATH abrem como quando você arrasta algo para a janela: um arquivo
.dashcomo aba, um arquivo de banco de dados DuckDB como o banco de dados da janela, e arquivos de dados, pastas e globs anexados como visões. Caminhos PATH relativos são resolvidos a partir do diretório do comando. Uma requisição que chega enquanto a janela ainda está iniciando espera até que sua abertura de inicialização termine. --sqlou--sql-file(-lê da entrada padrão) abre uma nova aba de consulta, com o título--title.--runa executa depois que os caminhos PATH foram anexados.--no-launchfalha com kindnot_runningem vez de iniciar uma janela — para uma máquina onde uma janela aparecendo sem ser pedida seria mal recebida.
O sucesso imprime {"delivered": true, "launched": BOOL}: a entrega, não um resultado. O que abre roda na sessão própria da janela — sua conexão, suas visões anexadas, seu histórico — e qualquer erro aparece lá, não no stdout. Código 2 para argumentos; 1 com kind not_running (nenhuma janela alcançável), refused (a janela recusou a requisição) ou launch.
A janela escuta em uma porta de loopback. Ela escreve a porta e um token aleatório em um arquivo que só a sua conta consegue ler (veja Configurações e dados do app); outro usuário da máquina, ou uma página web apontando para localhost, não consegue alcançá-la.
Leia o que a janela mostra
ducklocal open --state vai na direção oposta: não abre nada, nunca inicia uma janela e imprime o que a janela em execução mostra — assim um agente pode retomar de onde uma pessoa parou, em vez de pedir que ela cole sua consulta.
ducklocal open --state
ducklocal open --state sales.dash
ducklocal open --state --active{"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é o arquivo de banco de dados aberto, ou":memory:";attachedlista os arquivos que a janela registrou como visões, com onameda visão. Uma consulta da CLI não consegue ler essas visões — use opath.- Uma aba de consulta tem
sql, o texto do editor, tenha ele rodado ou não, eresult:statuséempty,running,rows,affected,failed,explainouprofile. Para linhas:columns,row_count,truncated,preview(as primeiras 20 linhas como a grade as mostra, em strings),elapsed_mse osqlque as produziu; paraaffected,counteelapsed_ms; para uma falha,error. - Depois que a pessoa escolheu colunas na aba Gráfico, um resultado também tem
chart:type,x,y,splitedash, um blocoquerye um blocoplotque desenham o mesmo gráfico em um painel. explainé o que o Explain mostra:plan, a saída deEXPLAINdo DuckDB como um array de linhas de texto, eelapsed_ms.profileé o que o Perfil mostra (veja Editor SQL):plan, a árvore de operadores que oEXPLAIN ANALYZEmediu, como um array de raízes, cada uma{operator, seconds, rows, estimated, children}—secondsé o tempo próprio do operador sem os filhos,rowso que ele produziu,estimateda estimativa do otimizador pararows(nullonde o plano não indica nenhuma),childrena mesma forma outra vez.operator_secondsé a soma do tempo próprio de cada operador, que é o valor a que as parcelas somam, não o tempo de relógio;elapsed_msé a execução inteira.- Uma aba de painel tem
path,unsavededashboard: o caminho do seucomments_file, seusplots(nome, tipo, título, consulta, linhas,open_commentsefailurequando um não consegue desenhar) e seusfilterscom o que cada um selecionou:picked,value(o primeiro valor),values(todos os valores selecionados, em ordem) emultiple.value: nullcompicked: truesignifica que o valor NULL foi selecionado.
Use --state sales.dash para manter apenas as abas que mostram aquele painel, ou --state --active para apenas a aba ativa. Um caminho que não está aberto devolve código 1, kind not_open, com os painéis abertos no hint. active_tab é o índice da aba ativa dentro das tabs devolvidas, ou null se ela não estiver entre elas; database e attached continuam incluídos.
--state aceita um caminho .dash ou --active, não os dois. --no-launch é aceito e não muda nada. Outras opções, incluindo --sql e --run, são inválidas (código 2). Código 1 com kind not_running quando não há nenhuma janela aberta, e timeout quando ela não responde em 5 segundos.
Verifique uma especificação de painel
O formato em si — blocos, atributos, tipos de gráfico, regras de SQL e mensagens comuns — é descrito em Painéis (.dash); esta seção cobre o comando.
Um arquivo .dash declara um painel como o Terraform declara infraestrutura — consultas e gráficos como blocos, referências entre eles — em vez de programá-lo. É fácil de escrever e de comparar com diff, tanto para uma pessoa quanto para um agente.
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
}ducklocal check dashboard.dash
ducklocal check dashboard.dash --database warehouse.duckdb
ducklocal check dashboard.dash --summaryUm bloco source nomeia arquivos de dados, relativos ao arquivo .dash, para as consultas lerem, e um bloco view guarda SQL compartilhado por várias consultas. Um bloco query guarda um atributo sql — uma instrução somente leitura, como heredoc ou como string. SELECT, WITH, os que começam com FROM, VALUES, SHOW, DESCRIBE, SUMMARIZE e PIVOT são aceitos; qualquer coisa que possa escrever — DDL, DML, COPY, ATTACH, INSTALL — é um diagnóstico, e a GUI se recusa a executá-la, porque as consultas de um painel rodam sempre que o arquivo é aberto. Um bloco plot guarda type (um de line, bar, stacked_bar, area, scatter, pie, heatmap, histogram, map, timeline, table, card, text), query (uma referência como query.latency a um bloco de consulta no mesmo arquivo), suas colunas, e title e width opcionais. Um bloco filter torna um gráfico de barras ou uma tabela clicável — um valor, ou vários com multiple = true em uma barra — e uma consulta lê a escolha como $name. # e // comentam até o fim da linha. Painéis (.dash) tem todos os atributos.
Um gráfico text é a exceção: ele guarda title, text, ou ambos, e não aceita query. Os cards também podem usar note e tone; veja Cards e painéis de texto.
Primeiro as verificações estáticas: o SQL de cada consulta passa pelo parser real do DuckDB em uma conexão descartável, como query valida antes de executar, e cada $name é conferido contra os blocos filter — o SQL é analisado e executado com cada $name como TRUE, que é o que o painel executa antes de qualquer escolha.
Depois cada consulta roda, exatamente como abrir o painel a executaria — somente leitura, com suas fontes, pelo mesmo caminho de código e com o mesmo orçamento de linhas — e as colunas de cada gráfico são conferidas contra as colunas que a consulta realmente devolve: um y que não é numérico é um erro para qualquer tipo de gráfico, assim como as coordenadas não numéricas de um mapa ou seu size, e uma column de filtro que a consulta do seu gráfico não devolve.
- Sem
--databaseas consultas rodam em memória, que é tudo o que um painel sobre seus próprios arquivossourceprecisa. Uma consulta que lê uma tabela que nenhuma fonte define pode ser destinada a um banco de dados que não foi passado à verificação: ela é listada emunresolved(consulta, linha, motivo) em vez de falhar, e as colunas de seus gráficos não são conferidas. - Com
--database PATH(arquivo existente, somente leitura) elas rodam nesse banco de dados. Passe-o sempre que as consultas lerem tabelas de um banco de dados: tudo o que ficar emunresolvednão foi conferido.
Toda consulta que lê um filtro também é vinculada com um valor selecionado, sem executar essa variante. Isso detecta uma coluna de filtro ausente em uma consulta consumidora, mesmo quando a versão inicial com $name = TRUE funciona. Um filtro também precisa referenciar uma coluna devolvida pelo gráfico que o seleciona.
Executar e não apenas planejar importa: algumas falhas, como um cast que a compilação não consegue fazer ou um valor que não vai converter, só aparecem quando linhas são lidas, e uma verificação que as deixasse passar entregaria um painel que não consegue desenhar. As consultas rodam inteiras, então uma verificação contra um banco de dados grande leva o mesmo tempo que abrir o painel.
O sucesso é um único objeto JSON listando as fontes do arquivo (com o caminho resolved de cada uma), as visões, as consultas (com suas colunas de resultado e rows, quantas cada uma devolveu sem nada selecionado, mais truncated: true quando o orçamento de linhas do painel a cortou), os filtros (com as queries que leem cada um), os gráficos, unresolved e empty — as consultas que rodaram e não devolveram linhas. Uma consulta vazia passa em todas as outras verificações, mas costuma ser uma regex, um filtro ou uma junção que não encontrou nada, então olhe cada uma. Com --summary, o sucesso é uma linha JSON compacta:
{"file":"sales.dash","ok":true,"sources":1,"views":0,"queries":3,"filters":1,"plots":6,"unresolved":[],"empty":[]}Os cinco campos de bloco são contagens; unresolved lista as consultas que não puderam ser conferidas, e empty as que não devolveram linhas.
Um bloco com defeito fica de fora enquanto os blocos válidos seguem pela validação. Erros de especificação e falhas de consulta são reunidos na mesma execução, um file:line: message cada um. Se existir qualquer diagnóstico de especificação, a saída é 2 com kind spec; se apenas a execução ou a vinculação de SQL falhar, é 1 com kind sql. Falhas de banco de dados e de E/S também saem com 1. --summary não esconde diagnósticos.
O mesmo arquivo abre como aba de painel na GUI — ducklocal dashboard.dash, ducklocal open dashboard.dash, ou arraste-o para a janela — com os gráficos em uma grade de 12 colunas e um gráfico que não consegue desenhar mostrando o motivo na própria linha. Veja Painéis (.dash).
Métricas de um modelo semântico
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 dataducklocal metrics lê um modelo do Apache Ossie, model.ossie.yaml, e lista suas métricas e campos. compile imprime o único SELECT do DuckDB que responde a um pedido, sem ler dados; query o executa como ducklocal query faz, com um objeto semantic que traz o SQL e o sha256 do modelo. Um pedido que o modelo não consegue responder com exatidão é recusado, com código de saída 2 e um kind como metric_fanout. Métricas semânticas descreve o formato do modelo, cada opção e cada recusa.
Comentários de revisão em um painel
As pessoas revisam um painel comentando seus gráficos na janela — passe o cursor sobre um gráfico e clique no balão de fala (veja Revisar com comentários). O ducklocal comments é o lado do agente: ele lê os tópicos e os responde, sem janela.
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?"- Sem nenhuma ação, imprime os tópicos abertos:
{file, comments_file, open, threads}.--allinclui os resolvidos. - Cada tópico tem
id,plote o que o agente precisa para encontrá-lo na especificação:plot_title,plot_queryeplot_lines, a primeira e a última linha do blocoplot(nullquando a especificação não é analisada).plot_missingétruequando não resta nenhum gráfico com esse nome. Depois vêmresolvedecomments, cada um comauthor(userouagent), em um comentário de agente seuname(o nome que opresencemostra),texteat(RFC 3339, hora local). --reply ID --text TEXTacrescenta a resposta do agente. Uma resposta a um tópico resolvido o reabre, a menos que--resolvetambém seja passado.--resolve IDe--reopen IDmudam o estado de um tópico;--add PLOT --text TEXTinicia um tópico, assinado como o agente.- O número de um tópico serve como seu ID:
--reply 1significac1.--addrecusa um gráfico que a especificação não tem (código 2), e o hint lista os gráficos dela. - Uma ação imprime
{thread}, como ficou.
Os tópicos são guardados ao lado da especificação, em FILE.comments.json. Uma janela em execução percebe uma mudança em menos de um segundo e a mostra no gráfico. Um id de tópico desconhecido é código 2, com um hint para listar os tópicos; um arquivo de especificação que não existe é código 1.
Uma revisão, do começo ao fim: leia os tópicos abertos, edite a especificação, execute ducklocal check e depois responda a cada tópico com o que mudou e --resolve. Use --reply sem --resolve para perguntar algo de volta à pessoa.
Mostre a atividade do agente
check e comments avisam automaticamente uma janela em execução sobre qual painel o agente está trabalhando. presence pode anunciar uma edição antes que ela aconteça:
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--doingaceitareading,editingouidle(doneé um alias deidle).--plotrecebe nomes de gráfico separados por vírgula. Comediting, nomes novos são permitidos e aparecem como espaços reservados. Comreadingouidle, um nome desconhecido é código 2.- O nome exibido vem de
--agent, depois deDUCKLOCAL_AGENT, depois do ambiente de agente detectado (Claude, Codex, Cursor ou Gemini), e por fim deAgent. - A saída é
{delivered}. Sem uma janela em execução, produz{"delivered":false}sem erro e sem iniciar nenhuma janela.
O nome fica no canto do painel enquanto os comandos mantêm a sessão ativa. Clique nele para ver o log de atividade. Trinta segundos de silêncio ou --doing idle encerram a sessão; gráficos alterados e adicionados continuam marcados até serem vistos, e os avisos de gráficos removidos, até serem dispensados. Veja Veja um agente trabalhando.
Edite uma especificação de painel com LSP
ducklocal lsp é um servidor do Language Server Protocol para arquivos .dash, sobre stdio, para os editores iniciarem. Ele dá a qualquer editor compatível com LSP o que o editor de especificações da própria GUI tem:
- Diagnósticos: os que
checkinforma, publicados a cada abertura e a cada alteração (sincronização do documento inteiro, todos com severidade Error — são erros, não estilo). - Autocompletar: tipos de bloco, nomes de atributo, tipos de gráfico e os nomes depois de
query.eplot., cada um com uma edição de texto que substitui a palavra que está sendo digitada. - Hover: documentação de blocos, atributos e referências.
- Ir para a definição: de uma referência
query.nameouplot.nameaté o nome do bloco dela.
Com --database PATH, o SQL de cada consulta também é validado pelo parser real do DuckDB, como check --database faz.
Aponte o suporte genérico a LSP do seu editor para ducklocal lsp em arquivos *.dash — o comando não recebe argumentos de documento; o editor fala com ele por stdio. No Neovim (0.10+):
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,
})No VS Code, qualquer extensão de LSP genérico faz o mesmo com o comando ducklocal, os argumentos ["lsp"] e o seletor de documento dash. Códigos de saída: 0 depois de um shutdown/exit limpo, 1 quando o cliente vai embora sem um, 2 para uma linha de comando ruim ou um handshake de protocolo que falhou.
Contrato JSON
Consultas bem-sucedidas escrevem exatamente um objeto JSON no stdout, seguido de uma quebra de linha:
{"columns":[{"name":"n","type":"Int32"}],"rows":[[1]],"row_count":1,"truncated":false,"total_rows":1,"total_rows_exact":true,"elapsed_ms":1}columns e cada linha preservam a ordem das colunas e nomes de coluna duplicados. type é a representação de depuração do Arrow, não o nome do tipo SQL original do DuckDB (por exemplo, HUGEINT e DECIMAL podem compartilhar um portador Arrow). row_count conta as linhas devolvidas. total_rows conta as linhas produzidas, incluindo as contadas depois do limite de saída; total_rows_exact: false significa que a contagem parou depois de até 100.000 linhas adicionais, então esse total é um limite inferior. Nenhuma das duas contagens é uma contagem de linhas afetadas. elapsed_ms mede a preparação, a execução e a codificação das linhas, não o carregamento de arquivos nem a criação da conexão. Resultados com zero linhas mantêm os metadados. DDL/DML expõem o resultado real do DuckDB, incluindo colunas Count: INSERT/COPY costumam devolver [[N]]; CREATE TABLE normalmente não devolve linhas. Eles não são classificados a partir da primeira palavra-chave do SQL.
Codificação das células:
| Valor SQL | Codificação JSON |
|---|---|
| NULL | null (nunca a string "NULL") |
| Booleano, float finito | booleano/número JSON |
| Inteiro dentro de ±9.007.199.254.740.991 | número JSON |
| Inteiro maior, incluindo HUGEINT/UHUGEINT | {"encoding":"integer","value":"9007199254740992"} |
| Decimal | {"encoding":"decimal","value":"123.450"} com o texto decimal exato |
| Texto, enum | string JSON |
| Blob, geometry | {"encoding":"hex","value":"00ff"}; bytes em minúsculas, geometry usa WKB |
| Date | {"encoding":"date","unit":"Day","value":"1","iso":"1970-01-02"}; dias desde 1970-01-01 |
| Timestamp | {"encoding":"timestamp","unit":"Nanosecond","value":"123456789","iso":"1970-01-01T00:00:00.123456789"}; contagem com sinal desde a época Unix; a unidade também pode ser Second/Millisecond/Microsecond |
| Time | {"encoding":"time","unit":"Microsecond","value":"123456","iso":"00:00:00.123456"}; contagem desde a meia-noite |
| Interval | {"encoding":"interval","months":1,"days":2,"nanos":"3000"} |
| NaN, infinito positivo/negativo | {"encoding":"float","value":"NaN"} / "inf" / "-inf" |
| List, array | array JSON, codificado recursivamente (incluindo nulos aninhados) |
| Struct | {"encoding":"struct","fields":[["name",VALUE],...]} |
| Map | {"encoding":"map","entries":[[KEY,VALUE],...]}; não é um objeto JSON, então as chaves mantêm seus tipos |
| Union | {"encoding":"union-value","value":VALUE}; apenas o valor ativo, a etiqueta do membro não é mantida |
Os value temporais são contagens exatas, então nenhuma precisão fracionária é perdida; os sentinelas de infinito de data/timestamp continuam sendo contagens brutas. Ao lado de cada um, iso é o mesmo valor como texto ISO 8601 para leitura, com tantos dígitos de fração quantos a unidade comporta. Um timestamp de uma coluna com fuso horário (metadados do Arrow) é um instante UTC, e seu iso termina em Z. --format md também renderiza datas e timestamps de forma legível. Como o wrapper Arrow do DuckDB fixado não consegue distinguir HUGEINT, UHUGEINT e DECIMAL(38,0) aninhados, ocorrências não nulas produzem um erro claro em vez de mudar o sinal ou a precisão em silêncio. Converta esses campos explicitamente para VARCHAR no SQL. Tipos desconhecidos não suportados também produzem um erro; não confunda um erro com um resultado vazio. A codificação de union é uma representação do valor ativo, não uma ida e volta sem perdas de uma union.
Os erros escrevem um objeto JSON no stderr, deixando o stdout vazio:
{"error":{"kind":"argument","message":"Unknown query option: --limt","hint":"Did you mean --limit?"}}hint existe quando o próximo passo é conhecido, nos termos desta CLI: a flag que uma escrita com erro de digitação queria ser, --read-write para uma escrita recusada em um banco de dados somente leitura, ducklocal schema para uma tabela que não existe, TRY_CAST para um valor que não vai converter, dividir um script que tem mais de uma instrução, ou AS para uma palavra-chave usada como alias de coluna sem qualificação (SELECT count(*) AS minutes, ou coloque entre aspas). Um agente deveria agir conforme ele antes de reescrever o SQL. Ele está ausente quando não há nada a acrescentar à mensagem do próprio DuckDB, como em um erro de sintaxe.
Códigos de saída: 0 sucesso, 2 argumentos ou número de instruções inválidos, 1 falha de SQL, banco de dados, E/S ou saída. Os kinds de erro são argument, sql, database, io, output, spec para check, e not_running, not_open, refused, timeout ou launch para open. Verifique o status de saída antes de analisar o stdout e inspecione truncated antes de informar que algo está completo. Ajuda e versão são exceções em texto simples. Falhas de transporte, como um pipe de stdout fechado, não conseguem garantir um fluxo de saída vazio ou completo.
Instale a skill oficial
A skill ensina ao agente os hábitos que mantêm suas respostas honestas: inspecionar o esquema, pré-visualizar uma amostra limitada, calcular agregações em SQL, verificar truncated e responder a partir dos valores devolvidos. Ela cobre inspeção de esquema, estatísticas de colunas, conversões, consultas a bancos de dados, painéis .dash e seus comentários de revisão, e entregar trabalho à janela e relê-lo; ela não oferece navegação no S3, comandos específicos de dados espaciais, memória de sessão nem um servidor MCP.
Pelo app. Abra Linha de comando e IA… (o botão do robô na barra de título, ou o menu do DuckLocal):
- Instalar comando coloca
ducklocalno seuPATH, para que o shell de um agente possa executá-lo. - Adicionar ao Claude Code escreve a skill em
~/.claude/skills/ducklocal, onde o Claude Code a encontra em todos os projetos. Apenas os dois arquivos da própria skill são escritos; qualquer outra coisa nessa pasta é mantida. Quando uma atualização do DuckLocal traz uma skill mais nova, o diálogo oferece Atualizar skill. - Copiar resumo copia uma explicação curta para qualquer outro agente — Codex, Cursor, uma janela de chat — nomeando o comando e como usá-lo.
À mão. A skill fica em skills/ducklocal. Para adicioná-la a um único projeto (exemplo para o Claude Code):
# 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/Inspecione um destino existente antes de sobrescrever mudanças locais. Outros agentes podem usar o mesmo SKILL.md mais references/cli.md no diretório de skills que eles suportam.
