# AI Helper
### Visão geral
O **AI Helper** é um assistente contextual integrado às áreas de criação, edição e análise de consultas, scripts e transformações. Ele permite solicitar ajuda diretamente dentro do ambiente de trabalho, sem alternar para ferramentas externas.
O assistente é acessado pelo botão **AI Helper**, disponível na barra superior das telas compatíveis. Ao ser acionado, ele abre um painel lateral à direita, mantendo o editor, builder ou área de configuração visível.
### Onde o AI Helper está disponível
O AI Helper está presente nos principais ambientes de desenvolvimento e modelagem da plataforma:
| Área | Descrição |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **SQL** | Disponível no editor SQL para apoiar criação, explicação, correção e otimização de queries. |
| **Python** | Disponível no editor de scripts Python para explicar código, investigar erros de execução e sugerir melhorias. |
| **Builder** | Disponível na interface visual de construção de consultas, auxiliando no uso de colunas, filtros, joins, agrupamentos, ordenações e limites. |
| **Computed Field dentro da Builder** | Disponível durante a criação ou edição de campos computados, auxiliando na escrita, correção e explicação de expressões. |
| **Source SQL** | Disponível na definição de fontes SQL, apoiando a criação, validação e entendimento da consulta usada como origem dos dados. |
### Objetivo
O AI Helper tem como objetivo auxiliar o usuário durante o ciclo de desenvolvimento, oferecendo suporte para:
* Entender o que uma query, script ou configuração faz;
* Melhorar ou otimizar uma consulta SQL;
* Explicar código Python;
* Investigar erros de execução;
* Interpretar resultados inesperados;
* Sugerir próximos passos;
* Apoiar a criação de campos computados;
* Auxiliar na construção visual de consultas no Builder;
* Explicar expressões, funções e transformações;
* Apoiar ajustes de lógica, filtros, joins, agregações, ordenações e limites.
### Acesso ao AI Helper
Para abrir o assistente:
1. Acesse uma tela compatível, como **SQL**, **Python**, **Builder**, **Computed Field** ou **Source SQL**.
2. Clique no botão **AI Helper** na barra superior da tela.
3. O painel lateral do assistente será exibido no lado direito da interface.
4. Digite uma pergunta ou selecione um dos **Quick Prompts** disponíveis.
O painel pode ser fechado pelo ícone **X** no canto superior direito.
### Comportamento contextual
O AI Helper identifica o contexto ativo da tela e adapta sua assistência conforme a área em uso.
Exemplo:
```
Active tab: code
```
```
Active tab: builder
```
```
Active tab: computed
```
Essa indicação informa qual área está sendo considerada pelo assistente no momento. Com isso, as perguntas e sugestões podem ser direcionadas ao conteúdo ativo, como código SQL, script Python, configuração visual do Builder ou expressão de um campo computado.
### Uso no SQL
No editor SQL, o AI Helper pode ser usado para:
* Explicar o objetivo de uma query;
* Revisar a estrutura da consulta;
* Identificar possíveis erros de sintaxe;
* Sugerir melhorias de performance;
* Ajustar filtros, joins, agrupamentos e ordenações;
* Investigar resultados incorretos ou inesperados.
Exemplos de perguntas:
```
O que esta query faz?
```
```
Como posso melhorar esta consulta?
```
```
Por que esta query está retornando erro?
```
```
Existe algum problema no join desta consulta?
```
### Uso no Python
No editor de scripts Python, o AI Helper pode auxiliar na análise e manutenção de código.
Ele pode ser usado para:
* Explicar o funcionamento de um script;
* Identificar erros de execução;
* Sugerir simplificações;
* Organizar ou refatorar o código;
* Indicar possíveis problemas de lógica;
* Apoiar o uso de bibliotecas, funções e manipulação de dados.
Exemplos de perguntas:
```
O que este script faz?
```
```
Por que este código está falhando?
```
```
Como posso organizar ou simplificar este script?
```
```
Existe uma forma mais eficiente de escrever este código?
```
### Uso no Builder
Na interface **Builder**, o AI Helper apoia a criação visual de consultas. Ele pode ajudar o usuário a entender a relação entre as configurações visuais e o SQL gerado.
O assistente pode ser usado para:
* Explicar o SQL gerado pelo Builder;
* Orientar sobre quando usar filtros;
* Apoiar a configuração de joins;
* Sugerir agrupamentos;
* Explicar ordenações;
* Orientar sobre limite de linhas e paginação;
* Indicar diferenças entre construir pela interface visual e escrever SQL diretamente.
Exemplos de perguntas:
```
O que significa o SQL gerado?
```
```
Como adiciono um filtro nesta consulta?
```
```
Quando devo usar join no Builder?
```
```
Qual a diferença entre Builder e Query task?
```
### Uso em Computed Field dentro da Builder
Ao criar ou editar um **Computed Field** dentro da Builder, o AI Helper fica disponível para apoiar a escrita da expressão.
Esse contexto é útil para:
* Criar expressões calculadas;
* Corrigir expressões inválidas;
* Explicar expressões existentes;
* Sugerir funções compatíveis;
* Apoiar o uso de funções do ClickHouse;
* Validar tipos de dados esperados;
* Transformar valores de colunas existentes.
Exemplos de perguntas:
```
Crie uma expressão para este campo calculado.
```
```
Corrija esta expressão.
```
```
Explique esta expressão.
```
```
Qual função do ClickHouse posso usar aqui?
```
### Uso em Source SQL
No contexto de **Source SQL**, o AI Helper auxilia na criação e manutenção da consulta SQL utilizada como fonte dos dados.
Ele pode ser usado para:
* Explicar a consulta de origem;
* Validar a estrutura do SQL;
* Sugerir melhorias;
* Identificar problemas de sintaxe;
* Ajustar seleção de colunas;
* Revisar filtros aplicados na origem;
* Apoiar a preparação dos dados antes do uso em etapas posteriores.
Exemplos de perguntas:
```
Esta query está adequada como fonte de dados?
```
```
Explique esta Source SQL.
```
```
Como posso melhorar a consulta de origem?
```
```
Existe algum filtro incorreto nesta Source SQL?
```
### Quick Prompts
O AI Helper disponibiliza atalhos com perguntas frequentes de acordo com o contexto ativo.
Exemplos de prompts por contexto:
| Contexto | Exemplos de Quick Prompts |
| ------------------ | ----------------------------------------------------------------------------------- |
| **SQL** | `What does this query do?`, `How can I improve this query?`, `Error or odd result?` |
| **Python** | `What does this script do?`, `Execution error`, `Organize or simplify` |
| **Builder** | `What does generated SQL mean?`, `Builder vs Query task`, `Where to work?` |
| **Computed Field** | `Create expression`, `Fix expression`, `ClickHouse function`, `Explain expression` |
| **Source SQL** | Prompts relacionados à explicação, validação e melhoria da consulta de origem. |
### Estrutura da interface
| Elemento | Descrição |
| ---------------------- | -------------------------------------------------------------------------------------------------------- |
| **Botão AI Helper** | Abre o painel lateral do assistente. |
| **Painel lateral** | Área onde o usuário interage com o assistente. |
| **Active tab** | Indica a aba ou contexto atualmente ativo, como `code`, `builder` ou `computed`. |
| **Área de orientação** | Exibe uma mensagem informando que o usuário pode perguntar sobre código, erro, saída ou próximos passos. |
| **Quick Prompts** | Sugestões rápidas de perguntas comuns, adaptadas ao contexto ativo. |
| **Campo de mensagem** | Campo onde o usuário digita sua solicitação. |
| **Botão Send** | Envia a mensagem ao assistente. |
| **Ícone X** | Fecha o painel do AI Helper. |
### Fluxo recomendado de uso
1. Acesse uma área compatível: **SQL**, **Python**, **Builder**, **Computed Field** ou **Source SQL**.
2. Crie ou edite a consulta, script, configuração ou expressão.
3. Abra o **AI Helper**.
4. Verifique o contexto indicado em **Active tab**.
5. Use um **Quick Prompt** ou digite uma pergunta específica.
6. Analise a resposta do assistente.
7. Aplique os ajustes necessários.
8. Execute, salve ou valide novamente o resultado.
### Boas práticas
Para obter respostas mais precisas, recomenda-se:
* Formular perguntas objetivas;
* Informar o comportamento esperado;
* Mencionar se o problema está relacionado a erro, performance, lógica ou resultado incorreto;
* Revisar a resposta antes de aplicar alterações;
* Validar manualmente qualquer sugestão em dados reais;
* Executar testes após alterações em queries, scripts ou expressões.
{% hint style="info" %}
O AI Helper funciona como uma camada de apoio ao desenvolvimento em SQL, Python e Builder. Ele também está disponível em contextos específicos, como **Computed Field dentro da Builder** e **Source SQL**.
{% endhint %}
{% hint style="warning" %}
As sugestões fornecidas pelo assistente devem ser revisadas pelo usuário antes de serem salvas, executadas ou utilizadas em ambientes produtivos.
{% endhint %}
---
# 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/ai-helper.md?ask=
```
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.