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.

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.

---

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.

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.

path = app_assets + "outputs/imagem_name.png"

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.

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.

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.

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

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.

# 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.

# 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.

# 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.

# 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:

{{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

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

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.