# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gaiodataos.com/gaio-dataos-portuguese/tools/tarefas/etl/consulta.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.