# Fontes de dados

> Consulte arquivos CSV, Parquet, JSON e Excel localmente com SQL do DuckDB. Abra pastas e globs, anexe bancos de dados e mantenha os dados no seu computador.

Source: https://ducklocal.app/docs/pt/data-sources

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](https://ducklocal.app/pt/use-cases/local-data-analysis/) 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:

1. Caminhos na linha de comando — `ducklocal ./logs/ billing.parquet`
2. 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
3. Arrastar arquivos ou pastas para qualquer lugar da janela
4. No Mac, arquivos que o Finder entrega ao DuckLocal — veja
   [Abrir pelo Finder](#open-from-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](#attached-databases).

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 {#supported-file-formats}

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](#database-files).

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 {#folders-and-patterns}

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:

```bash
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 {#many-csv-files-at-once}

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:

```sql
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 do `SELECT` chega tarde demais — a própria leitura dá erro. Leia
  todas as colunas como texto e faça o cast em SQL:

  ```sql
  SELECT try_cast(amount AS DOUBLE) AS amount
  FROM read_csv('data/*.csv', union_by_name = true, all_varchar = true)
  ```

  `union_by_name = true` també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ão `WHERE amount IS NOT NULL` não
  filtra isso. Use `NULLIF(amount, 'NULL')`, ou `WHERE amount <> 'NULL'`.

As duas correções se combinam: `try_cast(NULLIF(amount, 'NULL') AS DOUBLE)`.

## Arquivos de banco de dados {#database-files}

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](#attached-databases).

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 `.duckdb` e 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 como `File 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](#when-a-database-will-not-open)). 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 {#when-a-database-will-not-open}

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…](#attached-databases), 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`:

```sql
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](troubleshooting.md#opening-a-database).

### Qual DuckDB consegue ler um banco de dados {#storage-version}

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 {#attached-databases}

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.

1. Abra o menu **Abrir** na barra de título e escolha **Anexar banco de dados…**.
2. Digite o caminho, ou clique em **Procurar** para escolher o arquivo.
3. Deixe **Somente leitura** marcado a menos que você queira alterar o arquivo. Ele vem
   marcado por padrão.
4. 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`):

```sql
-- 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.duckdb` vira `db_2026_10_logs`.
- Um contador quando o nome já está ocupado: `snap`, depois `snap_2`. `main` nunca é
  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 `sqlite` do 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 {#in-the-sidebar}

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](schema-and-history.md).

### Mantidos entre conexões {#kept-across-connections}

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 {#open-from-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](dashboards.md).
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 {#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:

1. 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.
2. Reinicie o Quick Look no Terminal: `qlmanage -r`. Depois tente de novo.
3. 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](#kept-across-connections). 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](settings-and-data.md) para os locais em disco.
