Ir para o conteúdo

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 ​

ControleO que faz
+ ou ⌘TAcrescenta uma aba de consulta nova e a focaliza
Clicar em uma abaMuda para ela
Ctrl+Tab / Ctrl+Shift+TabA próxima / a anterior aba
⌘1 … ⌘8, ⌘9Da primeira à oitava aba; ⌘9 é a última aba
Arrastar uma abaMove-a pela faixa
×, ⌘W ou um clique do meioFecha 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 abaFechar 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 abaEdita 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ãoO que faz
ExecutarExecuta o SQL do editor — veja Executando SQL
PararAparece quando uma execução já dura um tempo; interrompe-a
FormatarReformata o SQL — veja Formatação
ExplainMostra o plano que o DuckDB usaria, sem executar a instrução
PerfilExecuta 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:

ComandoMostra
.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
.databasesOs bancos de dados anexados
.helpEsta 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óprio EXPLAIN, uma escrita escondida atrás de um WITH (WITH s AS (…) INSERT …), e um PIVOT sem uma lista IN (…) 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:

  1. Tabelas e colunas do esquema (até 35 entradas)
  2. Nomes de funções do DuckDB
  3. 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:

AtalhoAção
⌘↵Executar a consulta
⌘.Parar a consulta em execução
⌘TNova aba de consulta
⌘WFechar a aba
Ctrl+Tab / Ctrl+Shift+TabPróxima / aba anterior (Ctrl também no Mac)
⌘1 … ⌘9Ir para a aba naquela posição; ⌘9 é a última
⌘OAbrir dados
⌘SSalvar o código-fonte de um painel, na sua visualização de código-fonte
⌘BOcultar ou mostrar a barra lateral
⌘+ / ⌘− / ⌘0Aumentar / diminuir / tamanho padrão da interface — veja Tamanho da interface
⌘QSair

Os do próprio editor, que se comportam como em qualquer campo de texto:

AtalhoAção
⌘F / ⇧⌘FLocalizar / substituir no editor
⌘Z / ⇧⌘ZDesfazer / refazer
⌘ASelecionar tudo
⌘C / ⌘X / ⌘VCopiar / 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

A barra de menus contém todos os comandos da janela com seu atalho:

MenuComandos
DuckLocalLinha de comando e IA, Verificar atualizações…, Verificar atualizações ao iniciar, Mostrar o guia, Abrir pasta de logs, Sair do DuckLocal
ArquivoNova consulta, Abrir dados, Salvar, Fechar aba, Próxima aba, Aba anterior
EditarDesfazer, Refazer, Recortar, Copiar, Colar, Selecionar tudo
ConsultaExecutar, Parar
ExibirMostrar 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.

Publicado sob a licença Apache-2.0.