Editor SQL
Cada aba de consulta tem seu próprio buffer de editor. O editor destaca SQL de verdade via tree-sitter, indenta com 2 espaços e mostra números de linha.
Abas
| Controle | O que faz |
|---|---|
+ ou ⌘T | Acrescenta uma aba de consulta nova e a focaliza |
| Clicar em uma aba | Muda para ela |
| Ctrl+Tab / Ctrl+Shift+Tab | A próxima / a anterior aba |
| ⌘1 … ⌘8, ⌘9 | Da primeira à oitava aba; ⌘9 é a última aba |
| Arrastar uma aba | Move-a pela faixa |
×, ⌘W ou um clique do meio | Fecha uma aba. A última aba não pode ser fechada: seu × fica oculto e ⌘W não faz nada. Um painel com edições não salvas pergunta antes |
| Clique direito em uma aba | Fechar aba, Fechar as outras abas, Fechar as abas à direita. Painéis com edições não salvas continuam abertos, e um aviso diz quantos |
| Duplo clique em uma aba | Edita o título ali mesmo. Enter ou clicar fora mantém o título novo, Escape mantém o antigo; um título vazio volta para Query N |
As abas abertas voltam no próximo início, na mesma ordem: abas de consulta com seus títulos e o SQL de seus editores, tendo sido executado ou não, e abas de painel. Os resultados não — execute a consulta de novo. Uma aba de consulta que você abre nova começa com SELECT 'Hello, DuckLocal' AS greeting;.
A barra de ferramentas
Acima do editor, da esquerda para a direita:
| Botão | O que faz |
|---|---|
| Executar | Executa o SQL do editor — veja Executando SQL |
| Parar | Aparece quando uma execução já dura um tempo; interrompe-a |
| Formatar | Reformata o SQL — veja Formatação |
| Explain | Mostra o plano que o DuckDB usaria, sem executar a instrução |
| Perfil | Executa a consulta e mostra quanto custou cada operador |
Explain e Perfil estão descritos em Explain e perfil.
Executando SQL
Pressione ⌘↵ (Cmd+Enter) com o editor em foco, ou use o botão Executar.
Enquanto uma consulta está rodando, pressionar executar de novo não faz nada (nem Explain nem Perfil), e um botão Parar aparece ao lado de Executar assim que a consulta está rodando há um tempo. Parar, ou ⌘., interrompe a consulta; ela termina com o erro Interrupted do DuckDB, registrado no histórico como qualquer falha. Não há timeout: sem Parar, uma consulta roda o tempo que o DuckDB precisar, e o restante do trabalho com o banco de dados fica na fila atrás dela.
Os resultados chegam em fluxo do DuckDB, então uma varredura para quando o limite de linhas da grade é atingido em vez de ler o resto do arquivo. Uma consulta que precisa ver todas as linhas antes da primeira — ORDER BY, GROUP BY, uma agregação, uma função de janela — ainda é calculada por completo.
Cada aba tem seus próprios resultados. Um resultado que chega depois de você trocar de aba aterrissa na aba que o executou.
Como uma instrução é tratada depende da palavra-chave inicial. SELECT, WITH, SHOW, DESCRIBE, EXPLAIN, PRAGMA, SUMMARIZE, VALUES, FROM, TABLE, PIVOT e CALL produzem um conjunto de resultados. Qualquer outra coisa — instruções DDL (definição de dados) e DML (modificação de dados) — informa Done: N rows affected, took … em vez de uma grade. Comentários -- iniciais são ignorados na decisão; comentários de bloco não.
Scripts
O editor pode conter várias instruções. Executar executa todas elas, em ordem, do jeito que o shell do DuckDB lê um arquivo, e para na primeira falha — rodar um SELECT depois de um ATTACH que falhou só acrescentaria um segundo erro enganoso. Uma faixa acima dos resultados lista as instruções, cada uma marcada com sua contagem de linhas, concluída, falhou ou não executada; clique em uma para ver seu resultado. Um erro sublinha a instrução que falhou, não o script inteiro.
Alguns comandos de ponto do shell também funcionam, cada um em sua própria linha:
| Comando | Mostra |
|---|---|
.tables ?PATTERN? | Tabelas e views, opcionalmente filtradas por um padrão ILIKE como stat% |
.schema ?PATTERN? | As instruções CREATE de tabelas e views, opcionalmente filtradas |
.databases | Os bancos de dados anexados |
.help | Esta lista |
Qualquer outro comando de ponto (.mode, .read, …) é um erro que nomeia os que funcionam.
Erros
Uma instrução que falhou mostra um alerta intitulado Consulta falhou com a mensagem do DuckDB ao pé da letra. A mensagem vem do motor e está sempre em inglês, seja qual for o idioma da interface. Nada é escrito na grade, e a tentativa ainda é registrada no histórico com uma marca de falha.
Quando a mensagem aponta para uma posição — erros de analisador e de vinculação apontam, com uma linha LINE n: e um acento circunflexo — o editor sublinha aquele ponto com uma linha ondulada vermelha: o token que o acento marca, ou o trecho que uma sequência de acentos cobre. A marca acompanha suas edições e desaparece na próxima execução. Erros de execução não têm posição e não recebem marca.
Formatação
Formatar passa o buffer pelo sqlformat com indentação de 2 espaços e palavras-chave em maiúsculas, e depois substitui o buffer inteiro. Não faz nada em um buffer vazio.
Explain e perfil
Os dois botões trabalham sobre o texto inteiro do editor, e ambos aceitam exatamente uma instrução. Com duas ou mais — ou com um comando de ponto — eles recusam com Explain e perfil aceitam uma instrução: coloque a que você quer analisar em uma aba própria. Um ; final e comentários finais não são problema.
Enquanto um de Executar, Explain ou Perfil está ocupado, os outros dois não fazem nada. Nem Explain nem Perfil são registrados no histórico. A saída deles substitui a grade na aba Resultados, mudando para ela se outra aba estava aberta; uma falha mostra o alerta Consulta falhou, como uma execução que falhou.
Explain
Explain executa EXPLAIN <your statement> e mostra o plano do DuckDB como texto monoespaçado simples, com o tempo que levou. Ele apenas planeja: a instrução não é executada, então explicar um INSERT, UPDATE ou DELETE é seguro.
Perfil
Perfil executa a instrução sob EXPLAIN (ANALYZE, FORMAT JSON) e mostra o plano que rodou como uma árvore: o tempo de cada operador e sua parte do total, as linhas produzidas contra a estimativa do otimizador (marcado quando a diferença passa de 10×), e o que ele filtrou, usou para o join ou projetou. O operador que custou mais é nomeado no topo e desenhado em vermelho. Como ler isso: Saída de Explain e perfil.
O perfil executa a instrução de verdade — é assim que seus operadores são cronometrados. Por isso ele aceita apenas uma única consulta somente leitura:
- Aceitas:
SELECT,WITH … SELECT,FROM …,VALUES,TABLE,SHOW,DESCRIBE,SUMMARIZE. - Recusadas: qualquer coisa que escreva (
INSERT,UPDATE,DELETE,CREATE, …),CALL,PRAGMA,COPY, o próprioEXPLAIN, uma escrita escondida atrás de umWITH(WITH s AS (…) INSERT …), e umPIVOTsem uma listaIN (…)explícita.
Uma instrução recusada recebe Só instruções que leem podem ser perfiladas (SELECT, WITH, FROM…): o perfil executa a instrução. O próprio analisador do DuckDB decide isso antes de qualquer coisa rodar, não a primeira palavra-chave.
Um perfil leva o tempo da consulta, mais o custo de medi-la. Parar (ou ⌘.) o interrompe como uma execução.
Autocompletar
O menu de autocompletar conhece o catálogo. Os candidatos são classificados:
- Tabelas e colunas do esquema (até 35 entradas)
- Nomes de funções do DuckDB
- Palavras-chave SQL
No máximo 50 itens são oferecidos. A correspondência é por prefixo, sem diferenciar maiúsculas de minúsculas, no identificador imediatamente à esquerda do cursor, então sel completa para SELECT mas elect não completa nada. Uma função insere seu nome e um parêntese de abertura; identificadores que contêm espaços ou caracteres especiais são inseridos entre aspas duplas.
As listas de palavras-chave e de funções são um subconjunto selecionado — não é toda função do DuckDB que vai aparecer.
Atalhos de teclado
No Windows e Linux, leia Ctrl onde está ⌘ em todo o texto.
Os atalhos do próprio DuckLocal, todos listados na barra de menus:
| Atalho | Ação |
|---|---|
| ⌘↵ | Executar a consulta |
| ⌘. | Parar a consulta em execução |
| ⌘T | Nova aba de consulta |
| ⌘W | Fechar a aba |
| Ctrl+Tab / Ctrl+Shift+Tab | Próxima / aba anterior (Ctrl também no Mac) |
| ⌘1 … ⌘9 | Ir para a aba naquela posição; ⌘9 é a última |
| ⌘O | Abrir dados |
| ⌘S | Salvar o código-fonte de um painel, na sua visualização de código-fonte |
| ⌘B | Ocultar ou mostrar a barra lateral |
| ⌘+ / ⌘− / ⌘0 | Aumentar / diminuir / tamanho padrão da interface — veja Tamanho da interface |
| ⌘Q | Sair |
Os do próprio editor, que se comportam como em qualquer campo de texto:
| Atalho | Ação |
|---|---|
| ⌘F / ⇧⌘F | Localizar / substituir no editor |
| ⌘Z / ⇧⌘Z | Desfazer / refazer |
| ⌘A | Selecionar tudo |
| ⌘C / ⌘X / ⌘V | Copiar / recortar / colar |
| ⌥⌘↑ / ⌥⌘↓ | Adicionar um cursor acima / abaixo |
| ⌘← / ⌘→ / ⌥← / ⌥→ | Mover por linha / palavra |
| ⌘↑ / ⌘↓ | Mover para o início / fim do documento |
| ⌘⌫ / ⌥⌫ | Apagar até o início da linha / a palavra anterior |
Menus
A barra de menus contém todos os comandos da janela com seu atalho:
| Menu | Comandos |
|---|---|
| DuckLocal | Linha de comando e IA, Verificar atualizações…, Verificar atualizações ao iniciar, Mostrar o guia, Abrir pasta de logs, Sair do DuckLocal |
| Arquivo | Nova consulta, Abrir dados, Salvar, Fechar aba, Próxima aba, Aba anterior |
| Editar | Desfazer, Refazer, Recortar, Copiar, Colar, Selecionar tudo |
| Consulta | Executar, Parar |
| Exibir | Mostrar ou ocultar barra lateral, Interface maior, Interface menor, Tamanho padrão, Mapa base on-line (OpenStreetMap) |
O Windows e o Linux não têm barra de menus; ali, Mostrar o guia e Abrir pasta de logs estão no menu de clique direito da versão na extremidade direita da barra de status.
Mapa base on-line (OpenStreetMap) é um item de marcação; veja Gráficos. As linhas da barra lateral de esquema também têm um menu de clique direito; veja Esquema e histórico. Não há paleta de comandos.
