Fontes de dados
O DuckLocal transforma arquivos em views em uma conexão DuckDB em memória, ou em um arquivo de banco de dados se você abriu um. Outros bancos de dados podem conviver ao lado. Não há nada para configurar. Veja o fluxo de trabalho de análise de dados local para um caminho curto dos arquivos ao SQL, aos gráficos e à exportação.
Formas de abrir dados
Todas elas passam pelas mesmas regras de resolução:
- Caminhos na linha de comando —
ducklocal ./logs/ billing.parquet - O menu Abrir na barra de título: Abrir arquivos, Abrir pasta ou Informar um caminho ou glob, que abre a caixa de diálogo Abrir dados para um caminho digitado ou um escolhido no seletor nativo
- Arrastar arquivos ou pastas para qualquer lugar da janela
- No Mac, arquivos que o Finder entrega ao DuckLocal — veja Abrir pelo Finder
Para adicionar um banco de dados ao lado do aberto em vez de substituí-lo, use Abrir → Anexar banco de dados… — veja Bancos de dados anexados.
No macOS, você pode dar duplo clique em arquivos Parquet e DuckDB no Finder para abri-los, ou pressionar a barra de espaço para pré-visualizar as primeiras linhas de arquivos Parquet, DuckDB, CSV, TSV e JSON Lines com o Quick Look, sem abrir o DuckLocal.
Formatos de arquivo compatíveis
As extensões são comparadas sem diferenciar maiúsculas de minúsculas.
| Extensão | Como é lido |
|---|---|
.csv, .tsv, .txt | view read_csv_auto |
.parquet | view read_parquet |
.json, .ndjson, .jsonl | view read_json_auto |
.xlsx, .xls, .xlsb, .ods | importado como uma tabela por planilha |
Texto comprimido com gzip, como .json.gz e .csv.gz, também conta como arquivo de dados, em blocos schema, blocos source e ao anexar um arquivo; logs.json.gz vira uma view chamada logs. Antes da 0.4.0, ducklocal schema tentava abrir esse tipo de arquivo como banco de dados; em uma cópia mais antiga, leia-o em SQL com read_json ou read_csv.
Qualquer outra coisa não é um arquivo de dados — veja Arquivos de banco de dados.
Uma pasta de trabalho é o único formato que vira tabelas, não views, e ela importa todas as planilhas: a primeira planilha recebe como nome o radical do arquivo (o nome do arquivo sem a extensão), as outras são nomeadas {stem}_{sheet name}. Uma planilha vazia é ignorada. Os tipos das colunas são inferidos a partir das células — inteiros viram BIGINT, uma mistura de inteiro e decimal vira DOUBLE, datas viram TIMESTAMP, e qualquer coisa misturada ou não reconhecida vira VARCHAR; células vazias são importadas como NULL.
Pastas e padrões
Um diretório é percorrido recursivamente, e cada arquivo de dados dentro dele vira uma view. Duas regras valem para o percurso:
- Entradas ocultas (nomes que começam com
.) são ignoradas, e suas subárvores não são percorridas. - Links simbólicos não são seguidos. Seguir um link de volta para cima na árvore nunca terminaria, e o diretório apontado normalmente é percorrido onde ele realmente está.
Os arquivos são anexados em ordem alfabética, então a mesma pasta sempre produz o mesmo espaço de trabalho.
Um padrão pode conter * (qualquer sequência de caracteres) e ? (exatamente um). A correspondência acontece por componente de caminho, contra o sistema de arquivos, então um padrão pode atravessar diretórios:
ducklocal './data/2026-0*/*.parquet'Não há caractere de escape. ** não é especial — comporta-se como um único * e não é recursivo. Um padrão que corresponde a um diretório o ignora; apenas arquivos são anexados. Entradas ocultas também são ignoradas aqui.
Padrões sem aspas são expandidos pelo seu shell antes de o DuckLocal vê-los. Isso não é problema. Use aspas em um padrão apenas quando você quiser que o próprio DuckLocal o expanda — por exemplo, quando o shell não encontra nenhuma correspondência e daria erro.
Muitos arquivos CSV de uma vez
Cada arquivo que o DuckLocal anexa vira uma view própria com seu próprio esquema detectado, então dois CSVs que não combinam nunca quebram um ao outro. As armadilhas aparecem quando uma leitura SQL abrange muitos arquivos:
SELECT * FROM read_csv('data/*.csv', union_by_name = true)A detecção de tipos pode divergir entre arquivos. O leitor infere o tipo de uma coluna a partir de uma amostra; uma coluna que é numérica em todo lugar mas guarda uma string
'NULL'perdida em um arquivo faz a leitura inteira falhar com um erro de conversão, e um cast na lista doSELECTchega tarde demais — a própria leitura dá erro. Leia todas as colunas como texto e faça o cast em SQL:sqlSELECT try_cast(amount AS DOUBLE) AS amount FROM read_csv('data/*.csv', union_by_name = true, all_varchar = true)union_by_name = truetambém tolera arquivos cujos conjuntos de colunas diferem.A string
'NULL'não éNULL. Um'NULL'literal (ou'N/A','null') em um CSV é texto comum, entãoWHERE amount IS NOT NULLnão filtra isso. UseNULLIF(amount, 'NULL'), ouWHERE amount <> 'NULL'.
As duas correções se combinam: try_cast(NULLIF(amount, 'NULL') AS DOUBLE).
Arquivos de banco de dados
O DuckLocal tem um banco de dados principal por vez: em memória, ou um arquivo DuckDB que você abriu. Arquivos de dados viram views no banco de dados principal. Você também pode anexar outros bancos de dados ao lado dele.
Qualquer caminho que exista e não seja um arquivo de dados é aberto como o banco de dados principal em vez de ser anexado como view. A extensão não importa: um caminho .db, .duckdb ou até .md é tratado como banco de dados, e o DuckDB decide se ele realmente pode ser aberto.
Vale a pena conhecer algumas consequências:
- Um banco de dados novo só vem da caixa de diálogo Abrir dados. Digite um caminho que termine em
.duckdbe ainda não exista, e o DuckLocal cria o banco de dados, junto com as pastas pai que faltarem. Em qualquer outro lugar — a linha de comando, os seletores, um arrasto, o Finder — um caminho que não existe é reportado comoFile not found. - Abrir um banco de dados substitui o principal. Seus arquivos registrados e bancos de dados anexados são anexados de novo na nova conexão. As credenciais de S3 não são; configure o S3 de novo.
- Se o arquivo não puder ser aberto, o DuckLocal diz por quê (abaixo). Na inicialização ele volta para um espaço de trabalho em memória em vez de falhar ao iniciar. Enquanto ele está rodando, o espaço de trabalho que você tinha continua como estava.
- Um arquivo que já está anexado ao lado do banco de dados principal é desanexado primeiro e depois aberto como banco de dados principal. Se essa abertura falhar, o anexo volta. Abrir o arquivo que já é o banco de dados principal o reutiliza.
Anexar arquivos de dados enquanto um arquivo de banco de dados está aberto escreve essas views nesse arquivo de banco de dados — elas persistem ali, não apenas na sessão.
Quando um banco de dados não abre
Quando o DuckDB recusa um arquivo, o DuckLocal lê os primeiros bytes do arquivo por conta própria e, quando eles explicam a falha, coloca um motivo e uma saída acima da mensagem do próprio DuckDB. A mensagem do DuckDB fica embaixo para o erro exato. A explicação está no idioma da interface.
| O que o arquivo é | O que o DuckLocal diz |
|---|---|
| Um arquivo DuckDB escrito por um DuckDB mais recente que o embutido no DuckLocal | As duas versões, e o SQL para executar no DuckDB mais novo que copia o arquivo para um formato que o DuckLocal lê (abaixo) |
| Um arquivo DuckDB da v0.9 ou anterior | Execute EXPORT DATABASE 'dir' com o DuckDB que o escreveu, e depois IMPORT DATABASE 'dir' no DuckLocal |
| Um banco de dados SQLite | Não é um arquivo DuckDB; anexe-o — com Anexar banco de dados…, ou INSTALL sqlite; ATTACH '…' (TYPE sqlite); |
| Qualquer outra coisa que não seja um arquivo DuckDB | Abra arquivos CSV, Parquet, JSON ou Excel como arquivos de dados |
Para um arquivo de um DuckDB mais novo, a mensagem preenche o caminho do arquivo e a versão do DuckDB do DuckLocal. Execute-a no DuckDB que criou o arquivo e depois abra compat.duckdb:
ATTACH '/path/to/file.duckdb' AS src (READ_ONLY);
ATTACH 'compat.duckdb' AS dst (STORAGE_VERSION 'v2.0.0');
COPY FROM DATABASE src TO dst;Arquivos escritos antes do DuckDB v1.2 não registram qual versão os criou. Qualquer outra falha — um arquivo bloqueado por outro programa, um que você não pode ler — mostra apenas a mensagem do DuckDB. Veja Solução de problemas.
Qual DuckDB consegue ler um banco de dados
Quando um arquivo de banco de dados está aberto, a barra de status mostra o caminho dele. Passe o mouse por cima para ver o formato de armazenamento do arquivo — o DuckDB mais antigo que o lê, como Formato de armazenamento: legível pelo DuckDB v1.0.0+ — e, quando o arquivo registra isso, a versão que o criou (Criado pelo DuckDB v1.4.3). Confira isso antes de entregar um arquivo para alguém com um DuckDB mais antigo.
O DuckLocal roda o DuckDB 2.0, mas um arquivo de banco de dados que ele cria é escrito no formato que o DuckDB 1.x escrevia (legível pelo DuckDB v1.0.0+), então a CLI do duckdb, Python ou DBeaver no DuckDB 1.x ainda o abrem. Um arquivo que outro programa escreveu no formato próprio do DuckDB 2.0 (v2.0.0+) também abre, e mantém esse formato: o 1.x não consegue lê-lo.
Bancos de dados anexados
Anexe outro arquivo DuckDB ou SQLite ao lado do banco de dados principal para consultar entre eles — um snapshot ao lado dos dados de hoje, por exemplo.
- Abra o menu Abrir na barra de título e escolha Anexar banco de dados….
- Digite o caminho, ou clique em Procurar para escolher o arquivo.
- Deixe Somente leitura marcado a menos que você queira alterar o arquivo. Ele vem marcado por padrão.
- Clique em Anexar.
O banco de dados recebe um alias a partir do nome do arquivo, e você consulta suas tabelas como alias.table (ou alias.schema.table):
-- snap-2026-10-01.duckdb anexado como snap_2026_10_01
SELECT t.id, t.amount, s.amount AS amount_last_week
FROM orders t
JOIN snap_2026_10_01.orders s USING (id);Como o alias é formado:
- O nome do arquivo sem extensão, com cada caractere que não seja uma letra ASCII ou um dígito substituído por
_. db_na frente quando ele não começa com uma letra:2026-10 logs.duckdbviradb_2026_10_logs.- Um contador quando o nome já está ocupado:
snap, depoissnap_2.mainnunca é usado. - Anexar um arquivo de novo mais tarde devolve a ele o alias que tinha, então o SQL escrito contra ele continua funcionando.
Detalhes:
- Arquivos SQLite são reconhecidos pelo conteúdo e anexados por meio da extensão
sqlitedo DuckDB. - Desmarcar Somente leitura anexa o arquivo para escrita. Um caminho DuckDB que não existe é então criado como um banco de dados novo e vazio; em somente leitura, o anexo falha.
- O mesmo arquivo nunca é anexado duas vezes. Anexar um arquivo que já está aberto — como banco de dados principal ou como anexo — diz Este banco de dados já está aberto, como ….
Na barra lateral
Todo banco de dados aparece na árvore de esquema, tanto o principal quanto os anexados, inclusive os vazios. Um banco de dados mostra somente leitura ou sqlite ao lado do nome quando isso se aplica, e seu arquivo como dica de ferramenta.
Clique com o botão direito em um banco de dados para:
- Usar como banco de dados padrão — executa
USE, então nomes de tabela sem banco de dados são resolvidos ali. A barra de status mostra onde eles são resolvidos agora. - Desanexar banco de dados — desanexa e esquece, então ele não volta na próxima vez. Se ele era o banco de dados padrão, a sessão volta primeiro para o banco de dados principal. O arquivo em si não é tocado.
O resto desse menu está descrito em Explorador de esquema e histórico.
Mantidos entre conexões
Bancos de dados anexados são guardados no próprio banco de dados de histórico do DuckLocal, com seu alias e configuração de somente leitura, e anexados de novo em cada conexão nova: no próximo início, depois que você abre outro banco de dados, e depois de Novo banco de dados em memória.
- Um banco de dados cujo arquivo está faltando é ignorado silenciosamente. Seu registro é mantido, então ele volta quando o arquivo voltar — o DuckLocal nunca cria um banco de dados vazio no lugar dele.
- Um banco de dados que já está aberto, como principal ou de outra forma, não é anexado uma segunda vez.
- Se o novo banco de dados principal já tem um banco de dados com esse alias, o DuckLocal diz Não foi possível anexar …: o nome … está ocupado no banco de dados aberto.
Abrir pelo Finder
No Mac, o Finder pode entregar arquivos diretamente ao DuckLocal:
| Arquivo | Duplo clique | Abrir com, ou arrastar para o ícone do Dock |
|---|---|---|
.parquet | Abre no DuckLocal | Sim |
.duckdb, .ddb | Abre no DuckLocal | Sim |
.dash | Abre no DuckLocal | Sim |
.csv, .tsv, .json, .jsonl, .ndjson, .xlsx, .xls | Fica com o app que já os abre (Numbers, Excel, um editor de texto) | Sim |
O DuckLocal se registra como padrão apenas para formatos que nada mais no Mac reivindica. Se outro app já assumiu os arquivos Parquet ou DuckDB, escolha DuckLocal em Abrir com — ou use Obter informações → Abrir com → Alterar tudo… do Finder para torná-lo o padrão.
Um arquivo vindo do Finder é tratado exatamente como um arrasto para a janela: um arquivo de dados vira uma view no espaço de trabalho atual, um arquivo de banco de dados é aberto como banco de dados principal, e um arquivo .dash abre como aba de painel. Se o DuckLocal não estiver rodando, ele inicia primeiro e abre o arquivo quando sua própria inicialização termina.
Prévias do Quick Look
No Mac, selecione um arquivo de dados no Finder e pressione Espaço para ver suas colunas e primeiras linhas sem abrir nada. A prévia vem dentro do DuckLocal.app; não há nada para instalar separadamente. Ela precisa de macOS 12 ou mais recente, como o app.
| Arquivo | O que a prévia mostra |
|---|---|
.parquet | Colunas e tipos, as primeiras 50 linhas, e do rodapé do arquivo: contagem de linhas, grupos de linhas, compressão e o escritor |
.duckdb, .ddb | O número de tabelas, o formato de armazenamento (Legível pelo DuckDB …), e as cinco maiores tabelas, cada uma com sua contagem de linhas estimada e as primeiras 50 linhas |
.csv, .tsv | Colunas com seus tipos detectados, e as primeiras 50 linhas — uma tabela em vez de texto bruto |
.jsonl, .ndjson | Colunas e as primeiras 50 linhas |
Arquivos .json comuns e do Excel ficam com as prévias do próprio macOS.
O que a prévia faz e não faz:
- Ela nunca escreve. Um banco de dados é anexado como somente leitura.
- Ela nunca varre um arquivo inteiro: as linhas são um
LIMIT, e uma contagem de linhas aparece apenas onde o formato guarda uma (o rodapé do Parquet, a estimativa de um banco de dados). - Ela não baixa nada: extensões do DuckDB não são instaladas nem carregadas.
- Células com mais de 200 caracteres são cortadas. O texto da página está em inglês.
- Um arquivo que ela não consegue ler recebe uma página explicando por quê.
Se pressionar Espaço não mostrar nenhuma prévia do DuckLocal:
- Confira se o DuckLocal está em Aplicativos, e inicie-o uma vez. O macOS registra a prévia quando vê o app pela primeira vez.
- Reinicie o Quick Look no Terminal:
qlmanage -r. Depois tente de novo. - Confira se DuckLocal Preview está ativado em Quick Look nas configurações de extensões das Configurações do Sistema.
Nomes
A view de um arquivo é nomeada a partir do nome do arquivo sem extensão, limpo até virar um identificador válido. Quando esse nome já está ocupado na conexão, o DuckLocal acrescenta um contador: events, depois events_2, events_3. Dois arquivos com o mesmo nome base em diretórios diferentes, portanto, ganham views distintas.
A detecção de duplicatas é feita pelo texto do caminho como escrito, então ./a.csv e a.csv são tratados como dois arquivos diferentes.
Limites
- 256 arquivos de dados por pedido de abertura. O limite cobre todos os caminhos de um pedido juntos, não cada pasta separadamente — ele existe para que arrastar um diretório pessoal por acidente não prenda a conexão por minutos. Quando o limite é atingido, o DuckLocal avisa e anexa os primeiros 256 arquivos.
- Arquivos reanexados na inicialização a partir da sessão anterior não estão sujeitos a esse limite.
Gerenciando fontes registradas
Arquivos registrados aparecem no grupo Arquivos locais da barra lateral, cada um com seu nome de view, nome de arquivo e contagem de linhas. Selecionar um arquivo gera uma instrução SELECT para ele.
O × em uma linha de arquivo o remove, depois de uma caixa de diálogo de confirmação. Remover descarta a view e esquece o registro; o arquivo subjacente não é tocado.
Atualizar esquema recarrega o catálogo e os arquivos registrados.
O que é lembrado
A lista de arquivos registrados — seus caminhos, nomes de view e tipos — é guardada no próprio banco de dados de histórico do DuckLocal e reanexada no próximo início, então o espaço de trabalho que você deixou é o espaço de trabalho que você recupera. O mesmo vale para bancos de dados anexados. O arquivo do banco de dados principal não é lembrado: cada início começa em memória a menos que você informe um banco de dados.
Veja Configurações e dados do app para os locais em disco.
