> 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/tarefas/analytics/python.md).

# Python

<figure><img src="/files/411wun5JwpvEk6xKNqtC" alt=""><figcaption></figcaption></figure>

Esta tarefa permite executar scripts **na linguagem Python**, e a versão utilizada pode ser escolhida de acordo com as versões disponibilizadas pelo administrador do Gaio. As bibliotecas podem ser instaladas e gerenciadas por desenvolvedores do Gaio. Além disso, disponibilizamos uma classe chamada bucket que permite **extrair e exportar dados que estão no banco ClickHouse** que sua aplicação tem permissão para usar.

{% hint style="info" %}
**Limite de Memória**\
A tarefa Python no Gaio é limitada por padrão a um máximo de 80% da memória da máquina; se exceder esse limite, retornará um erro de limite de memória.
{% endhint %}

***

## Como Configurar a tarefa Python

Vamos simplesmente navegar pela interface da tarefa e, após isso, desenvolveremos um script simples como exemplo.

***

### 1.  Abrir a Tarefa Python

* No **Studio**, vá até o painel de **Tasks**.
* Na seção **Analytics**, selecione **Python**.

***

### 2. Preencher os campos obrigatórios

A primeira página é a principal da tarefa. Nela, à esquerda, temos o espaço em um tema azul para escrever o script, enquanto à direita, em um tema escuro, fica o console, onde podemos visualizar a saída do script. Para executar seu script, basta clicar no botão "run" e o resultado será exibido no console.

<figure><img src="/files/WDeGp3HZK2brmmGju4BC" alt=""><figcaption><p>Python Task Code Page</p></figcaption></figure>

É possível salvar os arquivos gerados no script, como jpeg, png, mp4, pkl, entre outros. O nome dessa pasta é **assets.**

{% hint style="info" %}
Existem três pastas que você pode usar através da tarefa Python, que são as pastas content, inputs e output da sua aplicação.\
Abaixo está um exemplo de como criar seu caminho para a pasta outputs para que você possa baixar a imagem gerada.

```python
path = app_assets + "outputs/imagem_name.png"
```

{% endhint %}

Na caixa de texto, você deve escrever em cada linha o nome correto da biblioteca que deseja instalar (apenas o nome, sem quaisquer outros caracteres, conforme mostrado na imagem abaixo). Após escolher a versão do Python e as bibliotecas, basta clicar no botão "Instalar" para que suas configurações sejam executadas.

<figure><img src="/files/cjJJq14QtjLPamQXM6jn" alt=""><figcaption><p>Python Task Environment Page</p></figcaption></figure>

Como mencionado anteriormente, temos uma classe chamada bucket, que se conecta ao ClickHouse de forma encapsulada e possui os métodos `query_df`, `command,` `insert_df` e `create_df`.

### **Exemplos**

Função que transforma um select do ClickHouse em um dataframe pandas no Python.

```python
df = bucket.query_df('select columnA, columnB from table where columnB = 'active')
```

Função que faz uma cópia de uma tabela do ClickHouse indicada para um dataframe pandas.

```python
df = bucket . select_df ( 'new_table' )
```

Na primeira linha temos a função que cria uma tabela no ClickHouse que é semelhante ao seu dataframe pandas, na segunda linha inserimos os dados do seu dataframe pandas na tabela do ClickHouse.

```python
bucket . create_df ( 'new_table' , df )
bucket . insert_df ( 'new_table' , df )
```

Note que para executar a função insert\_df precisamos que seu dataframe pandas seja semelhante à sua tabela no ClickHouse.

### Exemplo prático

Neste exemplo prático passaremos pela etapa de trazer os dados para o Python, realizar agrupamento, salvar uma imagem em formato png, salvar o arquivo do modelo, e criar e salvar a tabela final no ClickHouse.

Primeiro, vamos importar as bibliotecas que serão utilizadas

```python
import pandas as pd
from sklearn . cluster import KMeans
import matplotlib . pyplot as plt
import joblib
```

Para este exemplo usaremos a famosa tabela iris fornecida por várias bibliotecas como scikit-learn. Esta tabela está no banco ClickHouse dentro do Gaio.\
Usaremos a função `select_df` para trazê-la para o Python e então aplicar o algoritmo kmeans fornecido pela biblioteca scikit-learn.

```python
# Bring data into python
data = bucket . select_df ( 'iris_table' )

# Apply the K-Means algorithm with 3 clusters (number chosen arbitrarily)
kmeans = KMeans ( n_clusters =3 )
data [ 'cluster' ] = kmeans . fit_predict ( data )
​
# Evaluate the result - for example, viewing the means of each cluster
cluster_means = data . groupby ( 'cluster' ). mean ()
```

Neste próximo passo, vamos visualizar os grupos encontrados pelo modelo e salvar a figura na **pasta assets.**

```python
# Plot the clusters on a graph (considering only the first two columns)
plt . scatter ( data [ 'sepal_length_cm_' ], data [ 'sepal_width_cm_' ], c = data [ 'cluster' ], cmap = 'viridis' )
plt . xlabel ( 'sepal_length_cm_' )
plt . ylabel ( 'sepal_width_cm_' )
​
# Save the chart in png format
plt . savefig ( 'assets/cluster_iris.png' )
```

Agora vamos salvar este modelo para que ele possa ser reutilizado em outros momentos; para isso usaremos a biblioteca joblib.

```python
# Save the model
joblib . dump ( kmeans , 'assets/modelo_kmeans_iris.joblib' )
```

Agora podemos enviar o dataframe com a nova coluna gerada pelo modelo ao ClickHouse para que possa ser usado por outras tarefas do Gaio. Para isso usaremos `create_df` e `insert_df.`

```python
# Create a table in clickhouse similar to your dataframe
bucket . create_df ( 'tmp_iris_clusterizada' , data )
​
# Insert data from your dataframe into a clickhouse table
bucket . insert_df ( 'tmp_iris_clusterizada' , data )
```

### Uso de Parâmetros em Tarefas Python

As **Python Tasks** suportam parâmetros dinâmicos, permitindo que o mesmo script seja reutilizado com diferentes entradas entre execuções, ambientes ou fluxos.

Os parâmetros são resolvidos **em tempo de execução** e injetados automaticamente no script.

***

#### 1. Como os Parâmetros Funcionam

Parâmetros definidos na configuração da tarefa podem ser referenciados diretamente dentro do código Python utilizando a seguinte sintaxe:

```python
{{params.parameter_name}}
```

Durante a execução da tarefa, o valor do parâmetro será automaticamente substituído pelo valor configurado.

#### 2. Casos de Uso Comuns

Os parâmetros podem ser utilizados em diversos cenários, como:

* Caminhos dinâmicos para ingestão de arquivos
* Seleção de tabelas ou schemas
* Lógicas condicionais de execução
* Configurações específicas por ambiente
* Processamentos baseados em datas

#### 3. Observações Importantes

* Os nomes dos parâmetros **são sensíveis a maiúsculas e minúsculas (case-sensitive)**.
* Sempre valide os valores dos parâmetros antes de utilizá-los em lógicas críticas.
* Evite **hardcoding** de valores quando parâmetros puderem ser utilizados para tornar o script mais flexível e reutilizável.

***

### Uso de Tabelas Temporárias em Tarefas Python

Em tarefas Python do **Gaio DataOS**, é comum criar tabelas temporárias para armazenar resultados intermediários durante o processamento de dados.

Para evitar conflitos de nomes entre execuções simultâneas ou entre diferentes usuários, o Gaio fornece a função:

`bucket.tmp_context_table_name(table_name)`

Essa função gera automaticamente um **nome de tabela temporária com escopo de sessão**, garantindo isolamento entre execuções.

***

### Função

```python
bucket.tmp_context_table_name(table_name)
```

Retorna o nome de uma tabela temporária ajustado ao contexto de execução.

***

### Comportamento

O nome da tabela pode variar dependendo do tipo de contexto em que o script está sendo executado.

#### Contextos com sessão

Exemplos: `file-import`, `source`, entre outros.

Nesses casos, o nome da tabela recebe automaticamente um **prefixo com o identificador da sessão**, garantindo isolamento entre usuários.

```
tmp_my_table → tmp_gaio{sessionId}_my_table
```

#### Contextos sem sessão

Exemplos: `studio`, `cron`, `rest`, `api`.

Nesses casos, o nome da tabela **permanece inalterado**.

```
tmp_my_table → tmp_my_table
```

***

### Quando utilizar

A função `bucket.tmp_context_table_name()` deve ser utilizada **sempre que for necessário criar ou referenciar tabelas temporárias (`tmp_`) dentro de scripts Python**.

Isso evita:

* colisão de nomes entre execuções simultâneas
* interferência entre usuários
* conflitos entre pipelines concorrentes

***

### Exemplo de uso

```python
import pandas as pd

df = pd.DataFrame({
    'col1': [1, 2],
    'col2': ['a', 'b']
})

table = bucket.tmp_context_table_name('tmp_my_table')

bucket.create_df(table, df)

result = bucket.query_df(f'SELECT * FROM {table}')

print(result)
```

Neste exemplo:

1. Um DataFrame é criado em memória.
2. O nome da tabela temporária é gerado com escopo de sessão.
3. O DataFrame é persistido na tabela.
4. Os dados são consultados novamente a partir da tabela criada.