> For the complete documentation index, see [llms.txt](https://docs.gaiodataos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gaiodataos.com/gaio-dataos-portuguese/tools/tarefas/etl/consulta.md).

# Consulta

<figure><img src="/files/tlFODQQW4hZTjEHlwCAQ" alt=""><figcaption></figcaption></figure>

A tarefa **Consulta** é o construtor visual de consultas do Gaio DataOS.\
Ele permite que usuários técnicos e não técnicos criem consultas estruturadas de maneira simples e intuitiva, sem precisar escrever código SQL (embora o SQL gerado possa ser visualizado e editado a qualquer momento).

***

## Como usar a tarefa Consulta

***

### **1.** Inserir e selecionar um bloco de tabela

* Adicione uma **tabela** ao seu fluxo e escolha o conjunto de dados com o qual deseja trabalhar.
* A tarefa **Consulta** só ficará disponível depois que uma tabela for selecionada.

### **2.** Abra a tarefa do Consulta

* No menu à esquerda, vá para: **Tarefas> ETL > Consulta**
* No painel esquerdo, todos os campos disponíveis serão listados abaixo, com ícones indicando os tipos de dados (texto, número, data, etc.).

### **3. Configurar Informações básicas**

* **Rótulo da tarefa:** (opcional) Adicione um nome para a tarefa para identificá-la no seu fluxo.
* **Tabela**: A tabela deve ser vinculada automaticamente a partir do bloco selecionado (e.g., `new_sales`).

***

### 4. Crie sua consulta visualmente

Na guia **Consulta**, você pode criar sua consulta usando os seguintes blocos:

**Colunas:** Escolha os campos que deseja exibir nos resultados e aplique funções agregadas como `SOMA`, `CONTAGEM`, `MÉDIA`, etc.

**Filtros:** Aplique condições para restringir o conjunto de dados (e.g., `regiao = 'Sul'`, `unidades_vendidas > 5`).

**Join:** Vincule outras tabelas usando relações (JOINs).

**Agrupamento:** Agrupe os dados por uma ou mais colunas.

**Filtro após agrupamento:** Filtre os resultados agrupados (por exemplo, mostre apenas produtos com vendas totais acima de 100 unidades).

**Ordenação:** Classifique o conjunto de resultados com base nos campos selecionados.

**Linhas & Paginação (Offset):**&#x20;

* **Limite**: Número máximo de linhas a retornar.
* **Offset**: Número de linhas a pular (útil para paginação).

***

### 5. Usar Recursos de Consulta

Além da guia **Tabela**, você encontrará duas opções no canto superior esquerdo:

**Calculado:** crie **campos calculados** usando expressões personalizadas.\
Exemplo: `unidades_vendidas * valor_unidade` para gerar um campo de vendas totais.

{% hint style="warning" %}
Para usar parâmetros em campos calculados, o usuário deve inserir '**{{nome\_do\_parâmetro}}'** em sua função ou como um valor.
{% endhint %}

**Agregado:** Gerencie e visualize todos os **campos agregados.**

***

### 6. Visualizar a saída e a lógica

Na parte superior da tela, você encontrará duas guias úteis:

**SQL:** Exibe **o código SQL gerado automaticamente** com base na sua configuração. Você pode revisá-lo, copiá-lo ou até mesmo editá-lo, conforme necessário.

**Preview:** Mostra uma **pré-visualização em tempo real** dos resultados da consulta, ajudando você a validar a lógica antes de salvar.

***

### 7. Executar ou salvar a consulta

* Clique em **Salvar** para armazenar a configuração da sua consulta.
* Clique em **Salvar e Executar** para executar imediatamente a consulta e visualizar os resultados.

***

#### Boas práticas

* Use **campos computados** para criar métricas diretamente em sua consulta.
* Sempre verifique a guia **SQL** para entender o que está sendo executado.
* Use **Preview** para validar o resultado antes de salvar ou publicar.
* Dê nomes claros às suas consultas para manter seu projeto organizado.