# Explorador de esquema e histórico

> Navegue por bancos de dados, tabelas e colunas na barra lateral de esquema do DuckLocal, gere consultas SELECT, gerencie extensões do DuckDB e reutilize consultas antigas.

Source: https://ducklocal.app/docs/pt/schema-and-history

A barra lateral tem três abas: **Esquema**, **Histórico** e **Extensões**
(**表结构**, **查询历史** e **扩展** em chinês). O botão à esquerda da
barra de título, ou **⌘B**, oculta a barra lateral e a traz de volta; o botão fica no
mesmo lugar nos dois casos. O estado oculto da barra lateral é lembrado.

## A árvore de esquema

De cima para baixo, a árvore mostra **Arquivos locais**, **Painéis**, **Métricas** e **S3** como pequenos
títulos cinza, seguidos dos seus bancos de dados como linhas em negrito:

- **Arquivos locais** — os arquivos de dados que você registrou, cada um nomeado pela sua
  view, com sua contagem de linhas. Seus filhos são as colunas da view.
  - O nome do arquivo aparece ao lado do nome da view apenas quando os dois diferem
    (`sales_2` de `sales.csv`).
  - A pasta aparece quando dois arquivos compartilham um nome de view.
  - Passe o mouse sobre uma linha para ver o caminho completo.
- **Painéis** — os painéis `.dash` que você abriu recentemente, ordenados
  por nome para que uma linha não se mova quando você clica nela.
  - Clique em um para reabri-lo como aba, como você faria com um arquivo.
  - Dois painéis com o mesmo nome mostram sua pasta ao lado. Um arquivo
    alcançado por duas grafias do seu caminho (`E:\Proj` e `E:\proj`, ou um
    caminho relativo e um absoluto) é uma única entrada, e abre uma única aba.
  - O × ao passar o mouse o tira da lista, deixando seus arquivos e qualquer aba aberta
    em paz.
  - Uma entrada cujo caminho não existe mais é removida da lista.
- **Métricas** — presente quando há um `model.ossie.yaml` ao lado de um desses
  painéis. Uma linha por métrica; um clique a compila no editor de consultas e a
  executa. Veja [Métricas semânticas](metrics.md#sidebar). Mais novo que a 0.4.1.
- **S3** — presente quando o [S3 está configurado](s3.md). Carrega sob demanda.
- Cada banco de dados, depois seus esquemas, depois tabelas e views, depois colunas. O
  banco de dados com que a janela abriu vem primeiro; os bancos de dados que você
  [anexou ao lado dele](data-sources.md#attached-databases) vêm depois, marcados
  `read-only` quando anexados assim.

As tabelas mostram contagens de linhas estimadas; as views não. As entradas de coluna mostram tipos de dados do DuckDB. O banco de dados de sistema e os esquemas `information_schema`, `pg_catalog` e `system` ficam ocultos.

A caixa de busca sobre a árvore (**Buscar tabelas e colunas**) mantém apenas as
linhas cujos nomes contêm o que você digita, ignorando maiúsculas, e as linhas acima delas.
Uma tabela cujo nome corresponde mantém todas as suas colunas; uma tabela mantida por uma
coluna correspondente abre para mostrá-la. Limpe a caixa para recuperar a árvore inteira.

### Bancos de dados {#databases}

O banco de dados aberto vem primeiro, depois cada
[banco de dados anexado](data-sources.md#attached-databases) como um grupo próprio,
com o número de tabelas ao lado do nome.

- Um banco de dados anexado aparece mesmo quando está vazio. O banco de dados aberto fica
  de fora enquanto não tem tabelas, que é como uma sessão em memória nova começa.
- Uma dica discreta ao lado do nome diz **somente leitura**, e o tipo de arquivo quando ele
  não é DuckDB (**sqlite**).
- Passe o mouse sobre o nome para ver o caminho do arquivo do banco de dados.

Clique com o botão direito em um banco de dados para torná-lo o padrão ou para desanexá-lo — veja
[Menu de clique direito](#right-click-menu).

O botão de atualizar ao lado das abas (**Atualizar esquema**) recarrega o catálogo e
a lista de arquivos registrados.

## Gerando um SELECT

Todos os cliques abaixo **substituem o buffer inteiro** da aba ativa — eles
não inserem no cursor. O mesmo vale para clicar em uma entrada do histórico.
Salve o que você se importa antes de sair clicando.

Estes preenchem o editor ativo quando clicados:

| Clique | SQL gerado |
| --- | --- |
| O botão de play de uma tabela | `SELECT * FROM db.schema.table LIMIT 100;` |
| A caixa de seleção de uma coluna, ou seu nome | `SELECT col FROM db.schema.table LIMIT 100;` |
| Mais colunas da mesma tabela | `SELECT a, b FROM db.schema.table LIMIT 100;` |
| Um objeto de S3 que é um arquivo de dados | `SELECT * FROM 's3://bucket/key' LIMIT 100;` |

Cada coluna, de uma tabela, de uma view ou de um arquivo local, tem uma caixa de seleção. Marcar
colunas, ou clicar em seus nomes, o que as marca, monta o `SELECT` a partir
das marcadas, na ordem das colunas da tabela e não na ordem em que você as marcou. Desmarcar a última dá `SELECT *`. As marcas pertencem a uma tabela:
marcar uma coluna de outra tabela começa de novo ali.

O SQL gerado ocupa três linhas (`SELECT …`, `FROM …`, `LIMIT 100;`).
Os nomes de tabela são escritos o mais curtos que o banco de dados e o esquema padrão atuais
permitirem: `orders` para uma tabela no esquema padrão, `main.orders` para outro
esquema do mesmo banco de dados, e `database.schema.table` caso contrário. Depois de
**Usar como banco de dados padrão** em `snap`, a prévia de uma de suas tabelas diz
`FROM orders`. Até a primeira consulta rodar, os nomes são totalmente qualificados.

Um nome só recebe aspas duplas quando contém caracteres diferentes de letras,
dígitos e sublinhados.

## Menu de clique direito {#right-click-menu}

Todo comando que os botões de passar o mouse de uma linha oferecem também está no menu de clique direito dela, então
você encontra o comando sem precisar passar o mouse:

| Linha | Menu |
| --- | --- |
| Tabela ou view | Gerar consulta SELECT, Visão geral das colunas, Copiar nome, Copiar informações da tabela |
| Coluna | Gerar consulta SELECT, Copiar nome, Alterar tipo de dados… (apenas colunas de tabelas) |
| Banco de dados anexado | Usar como banco de dados padrão, Desanexar banco de dados |
| Lista de buckets do S3 | Atualizar buckets |
| Painel recente | Remover da lista |
| Arquivo local | Gerar consulta SELECT, Visão geral das colunas, Copiar nome, Copiar informações da tabela, Remover dos arquivos locais |

**Copiar nome** copia o nome puro — só o nome da tabela, da coluna ou da view,
sem qualificar com seu banco de dados e esquema, e sem aspas.

**Copiar informações da tabela** copia a tabela inteira como Markdown, pronta para colar em um
chat, uma issue ou o prompt de um agente de IA — o nome que uma consulta usa, o que ela é,
seu tamanho e cada coluna com seu tipo:

```md
memory.main.orders (table, ~224 rows, 3 columns)

| column | type |
|---|---|
| date | DATE |
| channel | VARCHAR |
| revenue | DOUBLE |
```

**Visão geral das colunas** substitui o texto do editor ativo por `FROM <table>;`,
o executa, e abre o painel de resultados na aba **Visão geral**, que resume
cada coluna da tabela inteira: nulos, valores distintos, intervalo e um pequeno
gráfico de seus valores. Veja [Visão geral das colunas](results-and-charts.md#overview).

**Usar como banco de dados padrão** executa `USE` naquele banco de dados, então nomes de tabela
sem banco de dados são resolvidos ali, e as consultas geradas ficam mais curtas (veja
acima). Ele não é oferecido no banco de dados que já é o padrão.

**Desanexar banco de dados** desanexa um banco de dados anexado e o esquece, então ele não é
anexado de novo na próxima vez. Se ele era o padrão, a sessão passa primeiro para outro
banco de dados. O arquivo não é tocado. O banco de dados aberto em si não pode ser
desanexado, então seu menu não tem esse item. Mais em
[Bancos de dados anexados](data-sources.md#attached-databases).

## Alterando o tipo de uma coluna

Uma linha de coluna oferece uma ação de tipo (indisponível em colunas de views, então colunas de CSV e Parquet anexados não podem ser retipadas). Ela abre uma caixa de diálogo de texto livre
pré-preenchida com o tipo atual e executa:

```sql
ALTER TABLE db.schema.table ALTER COLUMN col SET DATA TYPE <what you typed>
```

O nome da tabela é sempre totalmente qualificado aqui, e o nome da coluna recebe aspas
apenas quando é necessário.

Não há seletor nem lista de validação — qualquer string de tipo do DuckDB funciona,
inclusive as parametrizadas como `DECIMAL(10,2)`. Um tipo inválido volta
como uma notificação de erro. O sucesso recarrega o catálogo.

Renomear e descartar colunas, e editar comentários de colunas, não estão disponíveis.

## Removendo um arquivo registrado

O **×** em uma linha de arquivo pede confirmação, depois descarta a view e esquece
o registro. **O arquivo em disco não é tocado.**

Para remover vários registros juntos, selecione suas linhas em **Arquivos locais**:

- **⌘-clique** no macOS ou **Ctrl-clique** no Windows/Linux adiciona ou remove um arquivo da seleção.
- **Shift-clique** seleciona um intervalo consecutivo.
- Clique em **×** em um arquivo selecionado, ou use sua ação de remoção no clique direito, para confirmar a remoção dos registros selecionados. O menu mostra quantos arquivos serão removidos.

Isso remove as views e os registros, deixando os arquivos originais em disco. Selecionar
arquivos dessa forma não seleciona tabelas de banco de dados nem filtros de painel.

## Extensões {#extensions}

A aba **Extensões** lista todas as extensões do DuckDB que o motor conhece:
primeiro as carregadas, depois as instaladas, depois o resto, cada grupo por nome.

Cada linha mostra:

- o nome da extensão e uma etiqueta de status: **Carregada**, **Instalada** ou
  **Não instalada**;
- a descrição de uma linha do DuckDB sobre ela;
- sua versão e de onde veio: **embutida**, ou o repositório de onde foi
  instalada (`core`, `community` ou uma URL).

O que os status significam:

| Status | Significado |
| --- | --- |
| Carregada | Ativa na conexão atual: suas funções, leitores e tipos funcionam nas consultas agora |
| Instalada | Baixada para esta máquina, mas não carregada nesta conexão |
| Não instalada | Conhecida pelo DuckDB, mas ainda não está nesta máquina |

Extensões **embutidas** são compiladas no DuckLocal — `parquet` e `json`
entre elas, ambas carregadas desde o início. Elas nunca são instaladas nem atualizadas.

Extensões da comunidade são instaladas da mesma forma. Desde a 0.4.1 a aba alcança
o repositório da comunidade do DuckDB além do repositório principal, então uma extensão como
`mssql` (SQL Server) pode ser instalada e carregada sem sair do app; a
etiqueta do repositório na linha diz `community`.

Uma linha oferece as ações que se aplicam a ela:

| Botão | Mostrado quando | Executa |
| --- | --- | --- |
| **Instalar** | Não instalada | `INSTALL name` |
| **Carregar** | Instalada, não carregada | `LOAD name` |
| **Atualizar** | Instalada de um repositório | `UPDATE EXTENSIONS (name)` |

- **Instalar** e **Atualizar** baixam do repositório de extensões do DuckDB, então
  precisam de rede. **Carregar** lê o arquivo instalado e não precisa.
- Instalar não carrega. Clique em **Carregar** depois, ou execute `LOAD name`.
- Uma extensão instalada continua instalada: é um arquivo em disco, na pasta de extensões
  do próprio DuckDB. O carregamento dura apenas a conexão atual.
- Essa pasta é por versão do DuckDB (`~/.duckdb/extensions/v2.0.0/…`). Quando uma
  atualização leva o DuckLocal para uma versão nova do DuckDB, como a 0.3.0 fez com o DuckDB 2.0,
  as extensões que você tinha aparecem como **Não instalada** até você instalá-las
  de novo.
- Uma ação roda por vez; os outros botões ficam desativados enquanto isso. Uma
  notificação diz *Instalada …*, *Carregada …* ou *Atualizada …*, ou por que falhou.
- Depois de um carregamento ou de uma atualização, a árvore de esquema é recarregada, já que uma extensão
  pode trazer tabelas e funções consigo.

A lista é lida de `duckdb_extensions()` cada vez que a aba abre, depois de cada
ação, quando a conexão muda com a aba aberta, e quando você clica
no botão de atualizar ao lado das abas (**Atualizar extensões**). Assim ela também mostra
uma extensão carregada de outra forma — por um `LOAD` digitado em uma aba de consulta, ou pelo
DuckDB por conta própria.

Desde a v0.2.1, nem a janela nem a CLI baixam automaticamente uma extensão que falta
quando uma consulta precisa dela. Instale-a explicitamente em **Extensões** ou com `INSTALL name`. As extensões já instaladas nesta máquina ainda podem ser carregadas automaticamente.

### Abrindo a UI do DuckDB {#duckdb-ui}

A [UI do DuckDB](https://duckdb.org/2025/03/12/duckdb-ui) — o notebook de navegador do próprio
DuckDB, criado pela MotherDuck — é uma extensão como qualquer outra, então ela
também roda dentro do DuckLocal:

1. Na aba **Extensões**, clique em **Instalar** na linha `ui`, depois em **Carregar**.
2. Em uma aba de consulta, execute:

   ```sql
   CALL start_ui();
   ```

   Seu navegador abre a UI em `http://localhost:4213`. Para iniciar o servidor
   sem abrir um navegador, execute `CALL start_ui_server();` em vez disso.

![A aba Extensões com a extensão ui carregada](../assets/duckdb-ui.png)

A UI roda na instância do DuckDB a partir da qual foi iniciada, que aqui é a
do DuckLocal. Algumas coisas para saber:

- **Ela precisa de rede.** Instalar a `ui` a baixa, como qualquer extensão.
  E cada vez que ela inicia, o servidor local da extensão busca os arquivos da própria UI
  em `https://ui.duckdb.org`. Suas consultas e seus dados continuam rodando localmente.
- **Ela vive enquanto o DuckLocal viver.** Sair do DuckLocal fecha sua instância do DuckDB,
  e o servidor junto. `CALL stop_ui_server();` o encerra antes.
- **Os notebooks são salvos pela extensão, não pelo DuckLocal,** em
  `~/.duckdb/extension_data/ui/`. O histórico de consultas do DuckLocal não inclui
  o que você executa na UI.
- **Ela não consegue rodar diretamente em um banco de dados somente leitura.** Anexe esse banco de dados
  a partir de um notebook com `ATTACH '…' (READ_ONLY)`.

[DuckDB UI vs DuckLocal](https://ducklocal.app/pt/blog/duckdb-ui-vs-ducklocal/)
compara as duas e cobre quando usar cada uma.

## Histórico de consultas {#query-history}

Toda execução é registrada — sucessos e falhas — com um carimbo de data e hora
local, duração em milissegundos, contagem de linhas (ou de linhas afetadas em
DML), e o texto do erro se falhou. Entradas com falha aparecem em vermelho com uma
etiqueta *Falhou*.

A lista mostra as **200** entradas mais recentes. Clicar em uma linha repreenche o editor
ativo com aquele SQL e o focaliza, substituindo o que estava lá.

Não há política de retenção nem limpeza: a tabela de histórico cresce sem
limite, e a interface simplesmente mostra as 200 mais recentes. Também não há busca,
nem filtro, nem exportação, nem forma de apagar uma entrada pela interface.

O histórico fica guardado no próprio arquivo de banco de dados do DuckLocal, não no banco de dados que
você tem aberto, então sobrevive à troca de banco de dados e à perda do seu espaço de trabalho. Veja
[Configurações e dados do app](settings-and-data.md) para saber onde ele fica.
