# AI Helper

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

The **AI Helper** is a contextual assistant integrated into the platform’s query, script, and data transformation workflows. It allows users to request help directly within the working environment, without switching to external tools.

The assistant is accessed through the **AI Helper** button, available in the top bar of supported screens. When opened, it displays a side panel on the right side of the interface while keeping the editor, builder, or configuration area visible.

### Where AI Helper is available

AI Helper is available in the main development and data modeling environments of the platform:

| Area                              | Description                                                                                                             |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **SQL**                           | Available in the SQL editor to help create, explain, fix, and optimize queries.                                         |
| **Python**                        | Available in the Python script editor to explain code, investigate execution errors, and suggest improvements.          |
| **Builder**                       | Available in the visual query builder, helping users work with columns, filters, joins, groupings, sorting, and limits. |
| **Computed Field within Builder** | Available when creating or editing computed fields, helping users write, fix, and explain expressions.                  |
| **Source SQL**                    | Available when defining SQL sources, helping users create, validate, and understand the query used as the data source.  |

### Purpose

The AI Helper is designed to support users throughout the development workflow by helping them:

* Understand what a query, script, or configuration does;
* Improve or optimize SQL queries;
* Explain Python code;
* Investigate execution errors;
* Interpret unexpected results;
* Suggest next steps;
* Create computed fields;
* Build visual queries in the Builder;
* Explain expressions, functions, and transformations;
* Adjust logic, filters, joins, aggregations, sorting, and limits.

### Accessing AI Helper

To open the assistant:

1. Go to a supported screen, such as **SQL**, **Python**, **Builder**, **Computed Field**, or **Source SQL**.
2. Click the **AI Helper** button in the top bar.
3. The assistant panel will open on the right side of the interface.
4. Type a question or select one of the available **Quick Prompts**.

The panel can be closed using the **X** icon in the upper-right corner.

### Contextual behavior

AI Helper detects the active context and adapts its assistance according to the area currently in use.

Examples:

```
Active tab: code
```

```
Active tab: builder
```

```
Active tab: computed
```

This indicator shows which area the assistant is using as context. Based on that context, questions and suggestions can be directed to the active SQL code, Python script, Builder configuration, or computed field expression.

### Usage in SQL

In the [SQL editor,](https://docs.gaiodataos.com/~/revisions/bYcp6p0pV7NhCwqVJU6A/tools/tasks/etl/sql) AI Helper can be used to:

* Explain the purpose of a query;
* Review the query structure;
* Identify possible syntax errors;
* Suggest performance improvements;
* Adjust filters, joins, groupings, and sorting;
* Investigate incorrect or unexpected results.

Example questions:

```
What does this query do?
```

```
How can I improve this query?
```

```
Why is this query returning an error?
```

```
Is there any issue with this join?
```

### Usage in Python

In the [Python](https://docs.gaiodataos.com/~/revisions/bYcp6p0pV7NhCwqVJU6A/tools/tasks/analytics/python) script editor, AI Helper can assist with code analysis and maintenance.

It can be used to:

* Explain how a script works;
* Identify execution errors;
* Suggest simplifications;
* Organize or refactor code;
* Detect possible logic issues;
* Support the use of libraries, functions, and data manipulation.

Example questions:

```
What does this script do?
```

```
Why is this code failing?
```

```
How can I organize or simplify this script?
```

```
Is there a more efficient way to write this code?
```

### Usage in Builder

In the [**Builder** ](https://docs.gaiodataos.com/~/revisions/bYcp6p0pV7NhCwqVJU6A/tools/tasks/etl/builder)interface, AI Helper supports visual query creation. It helps users understand the relationship between visual configurations and the generated SQL.

The assistant can be used to:

* Explain the SQL generated by the Builder;
* Provide guidance on when to use filters;
* Support join configuration;
* Suggest groupings;
* Explain sorting;
* Provide guidance on row limits and pagination;
* Explain the difference between using the visual Builder and writing SQL directly.

Example questions:

```
What does the generated SQL mean?
```

```
How do I add a filter to this query?
```

```
When should I use a join in Builder?
```

```
What is the difference between Builder and Query task?
```

### Usage in Computed Field within Builder

When creating or editing a **Computed Field** within Builder, AI Helper is available to help write the expression.

This context is useful for:

* Creating calculated expressions;
* Fixing invalid expressions;
* Explaining existing expressions;
* Suggesting compatible functions;
* Supporting the use of ClickHouse functions;
* Validating expected data types;
* Transforming values from existing columns.

Example questions:

```
Create an expression for this calculated field.
```

```
Fix this expression.
```

```
Explain this expression.
```

```
Which ClickHouse function can I use here?
```

### Usage in Source SQL

In the [**Source SQL**](https://docs.gaiodataos.com/~/revisions/bYcp6p0pV7NhCwqVJU6A/tools/tasks/etl/source-sql) context, AI Helper assists with creating and maintaining the SQL query used as the data source.

It can be used to:

* Explain the source query;
* Validate the SQL structure;
* Suggest improvements;
* Identify syntax issues;
* Adjust selected columns;
* Review filters applied at the source level;
* Prepare data before it is used in later steps.

Example questions:

```
Is this query suitable as a data source?
```

```
Explain this Source SQL.
```

```
How can I improve the source query?
```

```
Is there any incorrect filter in this Source SQL?
```

### Quick Prompts

AI Helper provides shortcuts with frequently used questions based on the active context.

Examples of prompts by context:

| Context            | Quick Prompt examples                                                               |
| ------------------ | ----------------------------------------------------------------------------------- |
| **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 related to explaining, validating, and improving the source query.          |

### Interface structure

| Element              | Description                                                                                        |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| **AI Helper button** | Opens the assistant side panel.                                                                    |
| **Side panel**       | Area where the user interacts with the assistant.                                                  |
| **Active tab**       | Indicates the currently active tab or context, such as `code`, `builder`, or `computed`.           |
| **Guidance area**    | Displays a message informing the user that they can ask about code, errors, output, or next steps. |
| **Quick Prompts**    | Quick suggestions for common questions, adapted to the active context.                             |
| **Message field**    | Field where the user types their request.                                                          |
| **Send button**      | Sends the message to the assistant.                                                                |
| **X icon**           | Closes the AI Helper panel.                                                                        |

### Recommended workflow

1. Open a supported area: **SQL**, **Python**, **Builder**, **Computed Field**, or **Source SQL**.
2. Create or edit the query, script, configuration, or expression.
3. Open **AI Helper**.
4. Check the context shown in **Active tab**.
5. Use a **Quick Prompt** or type a specific question.
6. Review the assistant’s response.
7. Apply the necessary adjustments.
8. Execute, save, or validate the result again.

### Best practices

For more accurate responses, it is recommended to:

* Ask clear and specific questions;
* Describe the expected behavior;
* Mention whether the issue is related to an error, performance, logic, or incorrect result;
* Review the response before applying changes;
* Manually validate any suggestion using real data;
* Run tests after changing queries, scripts, or expressions.

{% hint style="info" %}
AI Helper acts as a support layer for development in SQL, Python, and Builder. It is also available in specific contexts such as **Computed Field within Builder** and **Source SQL**.
{% endhint %}

{% hint style="warning" %}
Suggestions provided by the assistant should be reviewed by the user before being saved, executed, or used in production environments.
{% 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/tools/ai-helper.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.