Explorador de esquema e histórico
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_2desales.csv). - A pasta aparece quando dois arquivos compartilham um nome de view.
- Passe o mouse sobre uma linha para ver o caminho completo.
- O nome do arquivo aparece ao lado do nome da view apenas quando os dois diferem (
- Painéis — os painéis
.dashque 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:\ProjeE:\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.yamlao 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. Mais novo que a 0.4.1. - S3 — presente quando o S3 está configurado. 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 vêm depois, marcados
read-onlyquando 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
O banco de dados aberto vem primeiro, depois cada banco de dados anexado 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.
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
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:
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.
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.
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:
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
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,communityou 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
A UI do DuckDB — 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:
Na aba Extensões, clique em Instalar na linha
ui, depois em Carregar.Em uma aba de consulta, execute:
sqlCALL start_ui();Seu navegador abre a UI em
http://localhost:4213. Para iniciar o servidor sem abrir um navegador, executeCALL start_ui_server();em vez disso.

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
uia baixa, como qualquer extensão. E cada vez que ela inicia, o servidor local da extensão busca os arquivos da própria UI emhttps://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 compara as duas e cobre quando usar cada uma.
Histórico de consultas
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 para saber onde ele fica.
