> For the complete documentation index, see [llms.txt](https://wedocs.gitbook.io/wedocs-5.2/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wedocs.gitbook.io/wedocs-5.2/weknow-client/cadastros-gerais/metadados/editor-de-metadados-guia-completo-de-uso-e-funcionalidades.md).
# Editor de Metadados — Guia Completo de Uso e Funcionalidades
## Visão geral
O Editor de Metadados recebeu uma evolução significativa para proporcionar uma experiência mais moderna, inteligente e produtiva na construção de SQL e modelos dinâmicos.
As melhorias implementadas têm como objetivo facilitar a escrita do código, reduzir erros, agilizar navegação, melhorar a legibilidade e tornar a manutenção dos metadados mais simples e segura.
Além dos novos recursos visuais e funcionais, o editor passa a oferecer integração completa com a linguagem de modelo dinâmica, permitindo a criação de SQLs mais flexíveis e reutilizáveis.
***
## Linguagem de modelo dinâmica
A linguagem de modelo dinâmica permite que o SQL seja construído de forma inteligente conforme parâmetros, contexto do usuário, regras de negócio e estruturas dinâmicas.
Com ela, é possível utilizar condicionais, loops, variáveis, constantes e funções diretamente no editor de metadados.
Essa funcionalidade é recomendada principalmente para cenários onde o SQL precisa variar dinamicamente sem necessidade de criar múltiplos metadados.
[👉 Clique aqui para saber mais sobre Linguagem de modelo dinâmica](/wedocs-5.2/weknow-client/cadastros-gerais/metadados/linguagem-de-modelo-dinamica-no-editor-de-metadados-sql.md)
***
## Como habilitar a linguagem de modelo dinâmica
A funcionalidade fica disponível apenas para Metadados SQL.
Para habilitar:
1. Acesse a edição de um Metadado SQL.
2. Abra a seção **Avançado**.
3. Marque a opção:
> **Utilizar linguagem de modelo dinâmica (apenas SQL)**
Após habilitar, o editor passa automaticamente a disponibilizar funcionalidades adicionais relacionadas ao sistema de modelos.
***
## Funcionalidades liberadas ao habilitar o modelo dinâmico
Ao ativar a linguagem de modelo dinâmica, o editor passa a oferecer:
* sugestões contextuais inteligentes;
* pré-visualização do SQL final;
* destaque visual de erros e alertas;
* autocomplete de funções, variáveis e blocos;
* validação de sintaxe do modelo;
* suporte a blocos dinâmicos;
* recursos avançados de navegação e produtividade.
***
## Menu de contexto flutuante
O editor passa a possuir um menu de contexto acessível com clique direito, reunindo as principais funcionalidades do editor em um único local.
Por meio dele, é possível acessar rapidamente:
* pesquisa;
* substituição;
* marcadores;
* preferências;
* navegação por linha;
* ajuda;
* pré-visualização.
As opções disponíveis podem variar conforme o tipo de editor e contexto atual.
#### Funcionalidades disponíveis sem linguagem de modelo dinâmica habilitada
Quando a opção:
```
Utilizar linguagem de modelo dinâmica (apenas SQL)
```
estiver desabilitada, o editor funciona em modo SQL tradicional.
Nesse cenário, o menu de contexto disponibiliza funcionalidades relacionadas principalmente à edição e navegação do código.
#### Funcionalidades disponíveis com linguagem de modelo dinâmica habilitada
Quando a opção:
```
Utilizar linguagem de modelo dinâmica (apenas SQL)
```
estiver habilitada, o editor entra em modo avançado e passa a disponibilizar recursos adicionais relacionados à construção dinâmica de SQL.
Nesse cenário, além de todas as funcionalidades do modo tradicional, novas opções passam a ficar disponíveis.
***
## Pesquisa textual ao vivo e substituição
O Editor de Metadados possui um sistema avançado de pesquisa textual que permite localizar, navegar e substituir conteúdos diretamente no editor de forma rápida e dinâmica.
A pesquisa funciona em tempo real, ou seja, conforme o termo é digitado, o editor já inicia automaticamente a localização e destaque das ocorrências encontradas.
A funcionalidade foi desenvolvida para facilitar:
* manutenção de SQLs extensos;
* localização rápida de campos, tabelas e funções;
* refatoração de código;
* substituição em massa;
* validação de padrões;
* análise de conteúdo.
#### **Como acessar a pesquisa**
A pesquisa pode ser aberta de diferentes formas:
| Ação | Atalho |
| ------------------ | ------------------------- |
| Abrir pesquisa | `Ctrl + F` |
| Abrir substituição | `Ctrl + R` |
| Menu de contexto | Botão direito → Localizar |
Ao abrir, o painel de pesquisa é exibido no rodapé superior do editor.
#### **Funcionamento da pesquisa ao vivo**
Assim que o usuário começa a digitar:
* o editor pesquisa automaticamente;
* todas as ocorrências encontradas são destacadas;
* o contador de ocorrências é atualizado em tempo real;
* a primeira ocorrência válida é automaticamente selecionada.
#### **Destaque das ocorrências**
Quando um termo é encontrado:
* todas as ocorrências recebem destaque visual;
* a ocorrência atual recebe destaque diferenciado;
* o editor mantém o foco visual no resultado atual;
* a navegação entre ocorrências reposiciona automaticamente a visualização do editor.
#### **Navegação entre resultados**
A navegação entre ocorrências pode ser feita diretamente pelo teclado ou pelos botões da interface.
#### Atalhos disponíveis
| Ação | Atalho |
| ------------------- | --------------- |
| Próxima ocorrência | `Enter` |
| Ocorrência anterior | `Shift + Enter` |
| Fechar pesquisa | `Esc` |
#### **Contador de resultados**
O sistema apresenta um contador indicando:
```
Ocorrência atual / total de ocorrências
```
Exemplo:
```
4 de 13
```
#### **Pesquisa sem resultados**
Quando nenhuma ocorrência é encontrada:
* o contador exibe “Sem resultados”;
* nenhum destaque é aplicado no editor.
#### **Pesquisa com diferenciação de maiúsculas e minúsculas**
A opção permite considerar letras maiúsculas e minúsculas como diferentes.
#### **Exemplo**
Pesquisa:
```
user
```
Com diferenciação ativada:
Encontrará:
```
user
```
Não encontrará:
```
UserUSER
```
#### **Pesquisa por palavra inteira**
Permite localizar apenas palavras completas.
#### **Exemplo**
Pesquisa:
```
cliente
```
Encontrará:
```
cliente
```
Não encontrará:
```
cliente_idnome_cliente
```
#### **Pesquisa utilizando expressão regular (Regex)**
O editor suporta pesquisas utilizando expressões regulares.
Essa funcionalidade é indicada para buscas avançadas e padrões complexos.
#### **Exemplos comuns**
#### **Encontrar termos no fim da linha**
Pesquisa:
```
userName$
```
Resultado esperado:
* encontra apenas `userName` quando estiver no final da linha.
#### **Encontrar termos opcionais**
Pesquisa:
```
user(Name)?
```
Resultado esperado:
* encontra `user`;
* encontra `userName`.
#### **Encontrar sufixos alfanuméricos**
Pesquisa:
```
userName\w*
```
Resultado esperado:
* encontra `userName`;
* encontra `userName123`;
* encontra `userNameTeste`.
#### **Pesquisa apenas na seleção**
Permite limitar a busca a um trecho específico do editor.
#### **Como utilizar**
1. Selecione um trecho do código.
2. Abra a pesquisa.
3. Ative a opção:
```
Pesquisar na seleção
```
#### **Comportamento**
* somente o trecho selecionado será analisado;
* ocorrências fora da seleção serão ignoradas;
* a área selecionada recebe destaque visual suave.
#### **Histórico de pesquisa**
O sistema mantém um histórico dos termos pesquisados.
#### **Comportamento esperado**
* pesquisas anteriores podem ser reutilizadas;
* o histórico considera tempo mínimo de salvamento;
* pesquisas repetidas não devem gerar duplicidade desnecessária.
#### **Substituição de texto**
Além da pesquisa, o editor permite substituir conteúdos encontrados.
#### **Como acessar substituição**
| Ação | Atalho |
| ------------------ | ---------- |
| Abrir substituição | `Ctrl + R` |
A área de substituição será expandida abaixo da pesquisa.
#### **Funcionalidades de substituição**
A substituição permite:
* substituir ocorrência atual;
* substituir todas as ocorrências;
* substituir respeitando regex;
* substituir respeitando seleção;
* substituir respeitando case sensitive.
#### **Substituir ocorrência atual**
Substitui apenas a ocorrência atualmente selecionada.
#### **Comportamento esperado**
* substitui a ocorrência atual;
* automaticamente seleciona a próxima ocorrência válida;
* mantém histórico da substituição.
#### **Substituir todas as ocorrências**
Substitui todas as ocorrências encontradas de uma única vez.
#### **Comportamento esperado**
* todas as ocorrências válidas são substituídas;
* substituição respeita filtros ativos;
* a operação pode ser desfeita com um único `Ctrl + Z`.
#### **Comportamento do Undo (Desfazer)**
As substituições em massa são agrupadas em uma única ação de desfazer.
#### **Resultado esperado**
Ao pressionar:
```
Ctrl + Z
```
todas as alterações realizadas na substituição em massa devem ser revertidas juntas.
#### **Fechamento da pesquisa**
A pesquisa pode ser fechada através de:
| Ação | Comportamento |
| ------------------ | ------------------------ |
| `Esc` | Fecha painel de pesquisa |
| Clique fora | Mantém pesquisa ativa |
| Fechar manualmente | Remove destaques |
***
## Sugestões contextuais (Autocomplete)
O sistema de sugestões contextuais auxilia na escrita do SQL e dos modelos dinâmicos por meio de um autocomplete inteligente, exibido conforme o local onde o cursor está posicionado.
Para acionar manualmente, utilize **Ctrl + Espaço** dentro do editor. Em alguns contextos, as sugestões também podem abrir automaticamente, conforme configuração nas preferências.
As sugestões podem incluir palavras-chave SQL, funções, tabelas, campos, variáveis, constantes, blocos de modelo e snippets de código.
#### **Comportamento no SQL**
Quando o cursor está em um trecho SQL comum, o editor sugere opções compatíveis com a posição atual.
Por exemplo, ao posicionar o cursor após `select`, o sistema tende a sugerir campos disponíveis, variáveis e palavras-chave como `from`, `distinct` e `as`.
Após `from` ou `join`, as sugestões passam a priorizar tabelas conhecidas e comandos relacionados a junções, como `join`, `inner`, `left` e `right`.
Após `where`, `having` ou filtros semelhantes, o editor prioriza campos, variáveis e operadores como `and`, `or`, `in`, `like`, `is` e `null`.
Para que tabelas e campos sejam sugeridos, é necessário que a conexão tenha sido expandida ao menos uma vez na árvore de tabelas. Quando a informação vier do cache local, o sistema pode indicar que a sugestão está baseada em cache.
#### **Comportamento em expressões `{{ }}`**
Quando o cursor está dentro de um bloco de expressão, como `{{ }}`, o autocomplete passa a sugerir recursos da linguagem de fórmulas/modelos.
Nesse contexto, o usuário pode receber sugestões de constantes, variáveis e funções, como datas atuais, usuário logado, funções de texto, funções de data e funções matemáticas.
Ao selecionar uma sugestão, o item é inserido dentro do bloco `{{ }}` e será processado na pré-visualização do modelo.
#### **Comportamento em comandos `{% %}`**
Quando o cursor está dentro de um bloco de comando, como `{% %}`, o editor sugere comandos da linguagem de modelo dinâmica.
As sugestões podem incluir estruturas como `if`, `for`, `set`, `macro`, `switch`, `raw`, `inline` e comandos de fechamento.
Quando aplicável, o editor não apenas completa a palavra, mas insere um snippet completo. Por exemplo, ao selecionar um bloco condicional, o editor pode inserir a estrutura completa com abertura e fechamento, posicionando o cursor no ponto correto para preenchimento.
#### **Filtro das sugestões**
Quando já existe um texto digitado próximo ao cursor, esse texto é usado como filtro.
Por exemplo, ao digitar parte de uma palavra, como `pro`, o editor exibe apenas sugestões que contenham esse termo, destacando a parte correspondente na lista.
Conforme o usuário continua digitando, apagando ou movendo o cursor dentro do mesmo identificador, a lista é atualizada automaticamente. Se o cursor sair da área do identificador, o menu é fechado.
{% file src="/files/ksJZG9lXX1LWIN9NlUzH" %}
#### **Navegação e seleção**
A navegação pode ser feita pelo teclado ou mouse.
As setas para cima e para baixo mudam a sugestão selecionada. A tecla **Enter** confirma a sugestão atual. Também é possível inserir uma sugestão com duplo clique.
A tecla **Esc** fecha o menu sem inserir nada.
O menu também é fechado quando o editor perde o foco, quando a aplicação perde o foco ou quando o usuário clica fora da área de sugestões.
#### **Locais onde não há sugestões**
As sugestões não devem aparecer em locais onde o autocomplete não é aplicável, para evitar falsa impressão de funcionamento.
Isso inclui comentários SQL, comentários de modelo, strings comuns, trechos inválidos e locais no meio de delimitadores incompletos.
O autocomplete NÃO deve abrir nos seguintes cenários:
* comentários SQL em linha:
```
-- comentário SQL
```
* comentários SQL em bloco:
```
/* comentário SQL */
```
* comentários da linguagem de modelo:
```
{# comentário de modelo #}
```
* strings SQL comuns:
```
'texto'
"texto"
```
#### **Apresentação visual**
Cada sugestão apresenta uma identificação do tipo de conteúdo, como palavra-chave, função, tabela, campo, variável, constante ou bloco de modelo.
Quando disponível, a lista também mostra descrições adicionais para ajudar a usuário a entender o que será inserido antes de confirmar a sugestão.
Esse comportamento torna a escrita do SQL mais rápida, reduz erros de digitação e ajuda no uso correto da linguagem de modelo dinâmica.
#### Legenda das siglas exibidas nas sugestões contextuais
As sugestões exibidas pelo autocomplete apresentam uma pequena sigla à esquerda para identificar rapidamente o tipo de conteúdo sugerido.
Essas siglas ajudam a diferenciar palavras-chave, funções, tabelas, campos, variáveis, constantes e estruturas da linguagem de modelo dinâmica.
| Sigla | Tipo de sugestão | Descrição |
| ----- | ------------------- | ----------------------------------------------------------------- |
| `kw` | Palavra-chave | Comandos e palavras reservadas do SQL ou da linguagem de modelo |
| `fn` | Função | Funções SQL, funções de fórmulas ou funções da linguagem dinâmica |
| `tbl` | Tabela | Tabelas disponíveis na conexão atual |
| `fld` | Campo | Campos/colunas disponíveis das tabelas conhecidas |
| `ct` | Constante | Constantes da engine de fórmulas/modelos |
| `var` | Variável | Variáveis do sistema, contexto ou definidas no modelo |
| `{}` | Bloco de código | Estruturas completas da linguagem de modelo dinâmica |
| `{}!` | Bloco especial | Snippets especiais ou estruturas avançadas |
| `}` | Fechamento de bloco | Comandos de encerramento de estruturas dinâmicas |
***
## Destaque de delimitadores
O Editor de Metadados possui um sistema inteligente de destaque de delimitadores que auxilia na leitura, navegação e entendimento visual do código.
Conforme o cursor é movimentado pelo editor, o sistema identifica automaticamente o delimitador mais próximo relacionado ao contexto atual e destaca o par correspondente.
O objetivo da funcionalidade é facilitar a identificação visual de:
* início e fim de blocos;
* agrupamentos;
* expressões aninhadas;
* comandos da linguagem dinâmica;
* comentários;
* escopos SQL.
#### Como utilizar
A funcionalidade funciona automaticamente durante a navegação do cursor.
Não existe necessidade de executar comandos manuais para ativar o destaque.
Basta:
1. posicionar o cursor próximo de um delimitador;
2. clicar sobre um delimitador;
3. navegar com o teclado entre blocos e expressões.
O editor automaticamente identifica o par relacionado e aplica o destaque visual.
#### Comportamento geral
Quando o cursor está:
* sobre um delimitador;
* imediatamente antes;
* imediatamente depois;
* dentro de um bloco delimitado;
o editor procura o delimitador correspondente dentro do contexto atual e realiza o destaque do par.
O destaque sempre considera:
* escopo atual;
* contexto válido;
* blocos ativos;
* estruturas aninhadas;
* regras da linguagem dinâmica.
### Delimitadores suportados
O recurso suporta diferentes tipos de delimitadores conforme a linguagem e contexto utilizados.
#### Delimitadores disponíveis em todas as linguagens
Funcionam em:
* SQL;
* Python;
* Texto;
* Fórmulas;
#### Exemplo prático
#### Destaque de parênteses
Código:
```
select * from sale where (customer_id = 1)
```
#### Delimitadores da Linguagem de Modelo Dinâmica
Disponível apenas quando:
```
Utilizar linguagem de modelo dinâmica (apenas SQL)
```
estiver habilitado.
#### Bloco de comando
Utilizado para estruturas de controle da linguagem dinâmica.
#### Delimitadores
```
{% %}
```
#### Exemplo
```
{% if :cliente <> @null %} {% endif %}
```
***
## Fechamento automático de delimitadores
Ao digitar delimitadores de abertura, o editor automaticamente completa o fechamento correspondente.
O recurso funciona tanto para delimitadores simples quanto para estruturas da linguagem de modelo dinâmica.
Quando houver texto selecionado, o conteúdo pode ser automaticamente envolvido pelos delimitadores, agilizando edição e refatoração do código.
#### Como utilizar
A funcionalidade atua automaticamente durante a digitação.
Não existe necessidade de executar comandos manuais para ativar o fechamento.
Basta digitar um delimitador de abertura válido para que o editor complete automaticamente o fechamento correspondente.
#### Delimitadores suportados
#### Disponível em todas as linguagens
Funciona em:
* SQL
* Python
* Texto
* Fórmulas
* Linguagem dinâmica
#### Parênteses
Ao digitar:
```
(
```
Resultado esperado:
```
(|)
```
O cursor é posicionado automaticamente entre os delimitadores.
#### Fechamento automático da linguagem de modelo dinâmica
Quando a opção:
```
Utilizar linguagem de modelo dinâmica (apenas SQL)
```
estiver habilitada, o editor passa a tratar estruturas da linguagem dinâmica de forma especial.
#### Blocos de comando `{% %}`
Ao digitar:
```
{%
```
Resultado esperado:
```
{% | %}
```
#### Espaçamento automático
Nos delimitadores da linguagem dinâmica, o editor adiciona automaticamente espaços internos para manter padronização visual e facilitar leitura.
#### Exemplo esperado
```
{{ @currDT }}
```
#### Comportamento com texto selecionado
Quando existe um trecho selecionado e o usuário digita um delimitador válido, o editor envolve automaticamente o conteúdo selecionado.
#### Exemplo com parênteses
Texto selecionado:
```
valor + total
```
Ao digitar:
```
(
```
Resultado esperado:
```
(valor + total)
```
O cursor permanece após o conteúdo selecionado.
{% hint style="warning" %}
#### Restrição importante nos blocos de modelo
Quando a linguagem dinâmica estiver habilitada, o comportamento de envolvimento por seleção **não** ocorre para:
* `{% %}`
* `{{ }}`
* `{# #}`
Isso ocorre porque essas estruturas possuem regras próprias da engine dinâmica.
{% endhint %}
#### Relação com autocomplete
O fechamento automático trabalha em conjunto com o autocomplete contextual.
Exemplo:
Ao digitar:
```
{%
```
e utilizar:
```
Ctrl + Espaço
```
o editor pode sugerir:
* `if`
* `for`
* `macro`
* `switch`
* `set`
inserindo automaticamente snippets completos.
***
## Destaque de erros, alertas, dicas e detalhamento de problemas
O Editor de Metadados possui um sistema inteligente de validação visual que identifica automaticamente problemas na escrita do SQL e da linguagem de modelo dinâmica durante a edição.
Conforme o usuário digita ou altera o conteúdo do editor, o sistema analisa continuamente a estrutura do código e apresenta feedback visual diretamente na área de edição.
O objetivo da funcionalidade é:
* reduzir erros de sintaxe;
* facilitar identificação de problemas;
* acelerar correções;
* melhorar entendimento do código;
* auxiliar no aprendizado da linguagem dinâmica;
* evitar falhas de execução;
* fornecer orientação visual imediata.
#### Dependência da linguagem de modelo dinâmica
Os recursos de:
* destaque de erros;
* alertas;
* dicas;
* validação estrutural;
* detalhamento visual;
* tooltips de problemas;
* resumo do rodapé;
dependem da opção:
```
Utilizar linguagem de modelo dinâmica (apenas SQL)
```
#### Como funciona
A validação ocorre automaticamente enquanto o conteúdo é alterado.
O sistema monitora:
* estrutura dos blocos;
* sintaxe da linguagem dinâmica;
* delimitadores;
* comandos inválidos;
* inconsistências;
* trechos suspeitos;
* problemas estruturais.
Quando um problema é identificado, o editor:
* sublinha visualmente o trecho afetado;
* classifica a severidade;
* atualiza o resumo no rodapé;
* disponibiliza detalhes ao passar o mouse.
#### Tipos de validação
Os problemas encontrados são classificados em:
| Tipo | Objetivo |
| ------ | ------------------------------------------------- |
| Erro | Problema que impede interpretação correta |
| Alerta | Estrutura válida, mas potencialmente problemática |
| Dica | Sugestão de melhoria ou comportamento recomendado |
#### Erros
Erros representam problemas estruturais ou sintáticos que impedem o correto processamento da linguagem dinâmica.
#### Exemplo
Código:
```
{% if :cliente <> @null %}
```
Resultado esperado:
* o trecho recebe sublinhado vermelho;
* o rodapé contabiliza erro;
* o tooltip exibe detalhes do problema.
#### Alertas
Alertas representam estruturas válidas, porém com comportamento potencialmente incorreto, confuso ou não recomendado.
#### Exemplo
Código:
```
{% macro teste() %}{% return %}texto depois do return{% endmacro %}
```
Resultado esperado:
* `texto depois do return` recebe destaque amarelo;
* o rodapé contabiliza alerta;
* o tooltip explica o comportamento.
#### Resumo visual no rodapé
O rodapé do editor apresenta um resumo consolidado da situação atual do código.
O resumo é atualizado automaticamente conforme a análise do editor.
#### Informações exibidas
O rodapé pode apresentar:
```
Erros: X
Alertas: Y
Dicas: Z
```
#### Exemplo
```
Erros: 1
Alertas: 1
Dicas: 0
```
#### Comportamento do rodapé
O resumo:
* atualiza em tempo real;
* reflete apenas o conteúdo atual do editor;
* respeita contexto ativo;
* considera múltiplos problemas simultaneamente.
***
## Pré-visualização do modelo
A pré-visualização permite visualizar o SQL final gerado após o processamento da linguagem de modelo dinâmica.
O recurso auxilia na validação do resultado final do SQL antes da execução, facilitando a identificação de problemas e entendimento do comportamento do modelo.
A atualização pode ocorrer de forma automática ou manual, conforme preferência do usuário.
#### Dependência da linguagem de modelo dinâmica
A pré-visualização está diretamente relacionada à opção:
```
Utilizar linguagem de modelo dinâmica (apenas SQL)
```
#### Como abrir a pré-visualização
A pré-visualização pode ser aberta de diferentes formas.
#### Pelo menu de contexto
1. Clique com botão direito dentro do editor.
2. Acesse:
```
Pré-visualizar
```
#### Pelo rodapé do editor
No rodapé do editor existe um botão dedicado à pré-visualização.
Ao clicar:
* o painel lateral é aberto;
* o SQL renderizado passa a ser exibido;
* a visualização fica sincronizada com o conteúdo atual do editor.
#### Exemplo prático
Código original:
```
{% if :cliente <> @null %}
and sale.customer_id = :cliente
{% endif %}
```
#### Resultado na pré-visualização
Quando o parâmetro possui valor:
```
and sale.customer_id = :cliente
```
#### Atualização automática
A pré-visualização pode ser atualizada automaticamente enquanto o usuário altera o conteúdo do editor.
Nesse modo:
* pequenas pausas na digitação acionam atualização;
* o SQL renderizado é recalculado automaticamente;
* o painel acompanha as alterações em tempo real.
A configuração pode ser alterada de duas formas.
#### Pelo menu de contexto da pré-visualização
1. Clique com botão direito dentro da área da prévia.
2. Acesse:
```
Pré-visualizar
```
3. Ative ou desative:
```
Atualizar a pré-visualização automaticamente
```
#### Pelo rodapé da pré-visualização
No rodapé da própria prévia existe um botão para controlar:
* atualização automática;
* atualização manual;
#### Atualização manual
Quando a atualização automática estiver desabilitada:
* o painel permanece estático;
* o conteúdo não é recalculado automaticamente;
* o usuário controla quando deseja atualizar.
#### Como atualizar manualmente
#### Pelo menu de contexto
1. Clique com botão direito na pré-visualização.
2. Acesse:
```
Pré-visualizar
```
3. Clique em:
```
Pré-visualizar
```
#### Pelo rodapé
Utilize o botão de atualização presente no rodapé da pré-visualização.
### Cache de parâmetros SQL
Alguns valores utilizados na renderização podem ser mantidos em cache temporário para melhorar performance.
Isso ocorre principalmente quando:
* parâmetros possuem SQL próprio;
* filtros executam consultas auxiliares;
* valores dependem de consultas dinâmicas.
#### Como limpar o cache
A limpeza pode ser feita através:
* do menu de contexto da pré-visualização;
* do botão disponível no rodapé.
#### Quando utilizar limpeza de cache
A limpeza é útil quando:
* valores externos mudaram;
* parâmetros dependem de dados dinâmicos;
* o SQL de origem do parâmetro foi alterado;
* o usuário deseja forçar novo cálculo.
Após clicar em:
```
Limpar cache de variáveis e pré-visualizar
```
***
## Marcadores e navegação
O Editor de Metadados possui um sistema de marcadores que permite salvar posições estratégicas dentro do código para facilitar navegação rápida entre trechos importantes do SQL ou da linguagem de modelo dinâmica.
A funcionalidade foi desenvolvida para auxiliar principalmente em:
* SQLs extensos;
* modelos dinâmicos complexos;
* múltiplos blocos condicionais;
* loops;
* unions;
* regiões frequentemente editadas;
* pontos de validação;
* navegação entre áreas distantes do código.
Os marcadores funcionam como pontos de referência temporários dentro do editor, permitindo retornar rapidamente para locais específicos sem necessidade de procurar manualmente no conteúdo.
#### Como funciona
Cada marcador fica associado a uma posição específica do editor.
O sistema memoriza:
* linha;
* coluna;
* posição atual do cursor;
* contexto do editor.
Os marcadores permanecem disponíveis enquanto a edição estiver ativa.
#### Como adicionar marcadores
Os marcadores podem ser adicionados através do teclado ou menu de contexto.
#### Utilizando atalhos
#### Adicionar marcador
| Marcador | Atalho |
| ---------- | ------------------ |
| Marcador 0 | `Ctrl + Shift + 0` |
| Marcador 1 | `Ctrl + Shift + 1` |
| Marcador 2 | `Ctrl + Shift + 2` |
#### Exemplo prático
Posicione o cursor em:
```
group by
```
e pressione:
```
Ctrl + Shift + 1
```
Resultado esperado:
* o marcador 1 é criado;
* a posição atual fica salva;
* o editor passa a permitir retorno rápido para esse ponto.
#### Como navegar entre marcadores
Após criar um marcador, é possível retornar rapidamente para ele.
#### Atalhos de navegação
| Marcador | Atalho |
| ------------------ | ---------- |
| Ir para marcador 0 | `Ctrl + 0` |
| Ir para marcador 1 | `Ctrl + 1` |
| Ir para marcador 2 | `Ctrl + 2` |
#### Funcionalidades disponíveis no menu
O menu pode disponibilizar:
* adicionar marcador;
* remover marcador;
* navegar para marcador;
* limpar marcadores.
#### Comportamento ao fechar editor
Os marcadores são temporários e associados à sessão atual de edição.
Ao fechar o editor:
* os marcadores são descartados;
* novas sessões iniciam sem marcadores anteriores.
***
## Linha e coluna no rodapé
O Editor de Metadados exibe continuamente no rodapé a posição atual do cursor dentro do código, permitindo identificar em tempo real a linha e a coluna onde o usuário está posicionada.
#### Onde a informação é exibida
A posição atual do cursor é apresentada no canto inferior esquerdo do editor.
#### Formato exibido
O formato padrão é:
```
linha : coluna
```
#### Exemplo
```
3 : 19
```
Nesse cenário:
* linha atual:
```
3
```
* coluna atual:
```
19
```
Isso significa que o cursor está:
* na linha 9;
* coluna 23 do editor.
#### Navegação utilizando mouse
Ao clicar em qualquer ponto do editor:
* o cursor é reposicionado;
* o rodapé atualiza imediatamente;
* linha e coluna passam a refletir a nova posição.
#### Navegação utilizando teclado
O rodapé acompanha automaticamente toda movimentação realizada pelo teclado.
#### Relação com “Ir para linha”
A funcionalidade trabalha em conjunto com a navegação rápida por linha.
***
## Ir para linha
O Editor de Metadados possui uma funcionalidade de navegação rápida que permite posicionar o cursor diretamente em uma linha específica do código sem necessidade de rolagem manual.
#### Como acessar
A funcionalidade pode ser utilizada de diferentes formas.
#### Utilizando atalho
Atalho principal
| Ação | Atalho |
| ------------- | --------- |
| Ir para linha | `Alt + G` |
**Como utilizar**
1. Pressione:
```
Alt + G
```
2. Informe o número da linha desejada.
3. Confirme a navegação.
#### Resultado esperado
* o editor navega automaticamente para a linha informada;
* o cursor é reposicionado;
* o trecho é centralizado na área visível;
* o rodapé atualiza linha e coluna atuais.
#### Utilizando menu de contexto
Também é possível acessar a funcionalidade através do menu do editor.
#### Como utilizar
1. Clique com botão direito no editor.
2. Acesse:
```
Ir para linha...
```
#### Resultado esperado
* abertura da janela de navegação;
* solicitação do número da linha;
* reposicionamento automático do cursor.
#### Utilizando o rodapé do editor
O recurso também pode ser acessado diretamente pelo rodapé.
A posição atual exibida no formato:
```
linha : coluna
```
funciona como referência visual da navegação atual.
Ao clicar sobre essa região pode abrir diretamente a navegação rápida por linha.
{% file src="/files/2aYROF97GgIzIKTzKrgy" %}
#### Funcionamento da navegação
Após informar o número da linha:
* o editor localiza a posição correspondente;
* o cursor é movido automaticamente;
* a linha recebe foco visual;
* a rolagem é ajustada automaticamente.
***
## Arrastar e soltar tabelas e bibliotecas
O Editor de Metadados possui suporte para inserção inteligente de tabelas, campos e bibliotecas utilizando drag-and-drop diretamente dentro do editor SQL.
A funcionalidade foi desenvolvida para acelerar construção de consultas, reduzir erros de digitação e facilitar utilização de objetos disponíveis na estrutura lateral do editor.
A inserção ocorre diretamente na posição atual do cursor ou substitui o conteúdo selecionado quando aplicável.
#### Como utilizar
Inserindo tabela
1. Localize a tabela na estrutura lateral.
2. Clique e arraste para o editor.
3. Solte no local desejado.
Inserir campo
1. Expanda a tabela desejada.
2. Arraste o campo para o editor.
3. Solte no SQL.
#### Exemplo
Campos:
```
DS STATUS
NM PACIENTE
```
Resultado esperado:
```
select
AGENDA.DS_STATUS,
AGENDA.NM_PACIENTE
from
AGENDA
```
{% file src="/files/JIHwBUD7pOgZz3wYeTCO" %}
***
## Tela de preferências
A tela de preferências permite personalizar o comportamento do Editor de Metadados conforme a necessidade do usuário.
As configurações afetam diretamente recursos como:
* autocomplete;
* fechamento automático;
* destaque visual;
* pesquisa textual;
* pré-visualização;
* validação;
* comportamento do editor;
* sugestões automáticas.
As preferências são armazenadas:
* por usuário;
* por linguagem.
Isso significa que configurações feitas em SQL podem ser diferentes das utilizadas em Python ou Texto.
#### Como acessar
A tela pode ser aberta diretamente pelo editor.
#### Utilizando menu de contexto
1. Clique com botão direito dentro do editor.
2. Acesse:
```
Preferências...
```
#### Relação com a linguagem atual
A tela muda conforme o tipo de editor aberto.
#### Exemplo
### Editor SQL com linguagem dinâmica habilitada
Exibe opções relacionadas a:
#### Configurações do editor SQL
#### Linguagem
Define qual linguagem terá as preferências configuradas.
#### Pré-visualização
Define o comportamento padrão da pré-visualização do modelo.
Opções disponíveis podem incluir:
* manter última escolha;
* ocultar a pré-visualização;
* exibir a pré-vvisualização.
#### Atualizar a pré-visualização automaticamente
Define como a pré-visualização do SQL renderizado será atualizada durante a edição do metadado.
* **Manter a última escolha:** utiliza automaticamente o último modo configurado pelo usuário.
* **Não atualizar automaticamente:** a pré-visualização só será atualizada manualmente.
* **Atualizar automaticamente:** a pré-visualização será recalculada automaticamente conforme o SQL for alterado.
#### Atraso na atualização automática da pré-visualização
Define o tempo de espera antes da pré-visualização ser recalculada automaticamente.
Valores menores:
* atualização mais rápida;
Valores maiores:
* menos atualizações;
#### Exibir automaticamente a pré-visualização quando houver erro de execução
Quando habilitado:
* o sistema abre automaticamente a pré-visualização ao ocorrer erro de execução;
#### Atraso na verificação de erros
Define o tempo que o editor aguarda antes de validar erros após a digitação.
Valores menores:
* validação mais rápida;
Valores maiores:
* reduz reprocessamentos contínuos;
#### Fechar delimitadores automaticamente
Controla o fechamento automático de delimitadores.
Exemplos:
```
(
[
{
{{
{%
{#
'
"
```
Quando habilitado:
* o delimitador de fechamento é inserido automaticamente.
#### Adicionar espaço aos delimitadores de modelo
Controla o espaçamento automático da linguagem dinâmica.
Quando habilitado:
```
{{ @currDT }}
```
Quando desabilitado:
```
{{@currDT}}
```
#### Exibir automaticamente o menu flutuante de sugestões
Controla abertura automática do autocomplete contextual.
Quando habilitado:
* sugestões aparecem automaticamente durante digitação.
Quando desabilitado:
* sugestões aparecem apenas com:
```
Ctrl + Espaço
```
#### Atraso na exibição do menu flutuante de sugestões
Define o tempo de espera antes do menu de sugestões aparecer automaticamente.
Valores menores:
* autocomplete abre mais rápido.
Valores maiores:
* reduz abertura excessiva do menu.
#### Sugerir blocos de código
Quando habilitado:
* o autocomplete sugere estruturas completas da linguagem dinâmica.
Exemplos:
```
if
for
macro
switch
```
#### Exibir tracejado nos locais de erros
Quando habilitado:
* erros recebem destaque visual no editor;
* facilita identificação dos problemas.
#### Exibir dica flutuante ao passar o mouse sobre erros
Quando habilitado:
* ao passar o mouse sobre um erro;
* o sistema exibe explicação detalhada do problema.
#### Destacar pares de delimitadores
Quando habilitado:
o editor destaca automaticamente pares relacionados.
Exemplos:
```
()
[]
{}
{{ }}
{% %}
{# #}
```
#### Destacar palavras pesquisadas
Quando habilitado:
* termos pesquisados recebem destaque visual no editor.
Utilizado junto com:
```
Ctrl + F
```
#### Atraso para salvar termo de pesquisa
Define o tempo de espera para armazenamento automático do termo pesquisado.
Valores menores:
* histórico atualizado mais rapidamente.
Valores maiores:
* reduz gravações frequentes.
#### Selecionar a linha completa
Quando habilitado:
* seleções passam a considerar a linha inteira automaticamente em determinadas ações do editor.
### Editor Python
Exibe apenas opções compatíveis com Python.
Recursos exclusivos da linguagem dinâmica não aparecem.
***
## Ajuda integrada do Editor de Metadados
O Editor de Metadados possui uma central de ajuda integrada diretamente no menu do editor, permitindo acesso rápido às documentações oficiais relacionadas à linguagem de modelo dinâmica e funcionamento do metadado.
A funcionalidade ajuda a consultar rapidamente:
* exemplos de uso;
* regras da linguagem;
* estruturas suportadas;
* funções;
* variáveis;
* boas práticas;
* limitações;
* regras específicas do editor.
#### Como acessar
A ajuda pode ser aberta diretamente pelo menu do editor.
#### Utilizando menu de contexto
1. Clique com botão direito dentro do editor.
2. Acesse:
```
Ajuda
```
#### Opções disponíveis
O menu disponibiliza acessos rápidos para documentações específicas.
* Como usar modelos (F1)
Abre a documentação introdutória da linguagem de modelo dinâmica.
Atalho rápido
| Ação | Atalho |
| ----------------- | ------ |
| Como usar modelos | `F1` |
* Regras específicas para metadados
Abre a documentação com regras específicas do Editor de Metadados.
* Referência completa de modelos
Abre a documentação técnica completa da linguagem dinâmica.
