> 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/ai-helper.md). # 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 %}