# Python
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.
Python Task Code Page
É 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.
Python Task Environment Page
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.
---
# 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/tarefas/analytics/python.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.