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.

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.

As sugestões fornecidas pelo assistente devem ser revisadas pelo usuário antes de serem salvas, executadas ou utilizadas em ambientes produtivos.