# Editor SQL

> O editor SQL do DuckDB do DuckLocal: abas de consulta, formatação, erros em linha, autocompletar com conhecimento do esquema, planos Explain, perfil por operador e atalhos.

Source: https://ducklocal.app/docs/pt/sql-editor

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](#running-sql) |
| **Parar** | Aparece quando uma execução já dura um tempo; interrompe-a |
| **Formatar** | Reformata o SQL — veja [Formatação](#format) |
| **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](#explain-and-profile).

## Executando SQL {#running-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](results-and-charts.md#row-limits) 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](schema-and-history.md) 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 {#format}

**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 {#explain-and-profile}

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](schema-and-history.md#query-history). 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](results-and-charts.md#explain-and-profile).

**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:

| 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](settings-and-data.md#interface-size) |
| ⌘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](results-and-charts.md#charts). As linhas da barra lateral de esquema também têm um
menu de clique direito; veja
[Esquema e histórico](schema-and-history.md#right-click-menu). Não há
paleta de comandos.
