Configuração em nível de função

Configure o mecanismo de execução e a correção de Dtype em nível de função

O DataStore permite controle detalhado da execução em nível de função, incluindo a seleção do motor e a correção de Dtype.

​

Configuração de Function Motor

Substitua o mecanismo de execução de funções específicas.

​

Configuração de Function Engines

from chdb.datastore.config import function_config

# Forçar funções específicas a usar chdb
function_config.use_chdb('length', 'substring', 'concat')

# Forçar funções específicas a usar pandas
function_config.use_pandas('upper', 'lower', 'capitalize')

# Definir preferência padrão
function_config.prefer_chdb()    # Padrão: chdb
function_config.prefer_pandas()  # Padrão: pandas

# Redefinir para automático
function_config.reset()

​

Quando usar

Force o uso de chdb para:

• Funções com melhor desempenho no ClickHouse
• Funções que se beneficiam da otimização por SQL
• Operações de texto/data-hora em larga escala

Force o uso de pandas para:

• Funções com comportamento específico do pandas
• Quando for necessária compatibilidade exata com o pandas
• Operações de texto personalizadas

​

Exemplo

from chdb import datastore as pd
from chdb.datastore.config import function_config

# Configurar os motores das funções
function_config.use_chdb('length', 'substring')
function_config.use_pandas('upper')

ds = pd.read_csv("data.csv")

# length() usará chdb
ds['name_len'] = ds['name'].str.len()

# substring() usará chdb  
ds['prefix'] = ds['name'].str.slice(0, 3)

# upper() usará pandas
ds['name_upper'] = ds['name'].str.upper()

---

​

Funções em comum

Mais de 159 funções estão disponíveis nos motores chdb e pandas:

Categoria	Funções
Texto	length, upper, lower, trim, ltrim, rtrim, concat, substring, replace, reverse, contains, startswith, endswith
Matemática	abs, round, floor, ceil, exp, log, log10, sqrt, pow, sin, cos, tan
Data e hora	year, month, day, hour, minute, second, dayofweek, dayofyear, quarter
Agregação	sum, avg, min, max, count, std, var, median

Para funções em comum, o motor é selecionado com base em:

1. Configuração explícita da função (se definida)
2. Configuração global execution_engine
3. Seleção automática com base no contexto

---

​

Funções exclusivas do chdb

Algumas funções estão disponíveis apenas no ClickHouse:

Categoria	Funções
Array	arraySum, arrayAvg, arraySort, arrayDistinct, groupArray, arrayElement
JSON	JSONExtractString, JSONExtractInt, JSONExtractFloat, JSONHas
URL	domain, path, protocol, extractURLParameter
IP	IPv4StringToNum, IPv4NumToString, isIPv4String
Geo	greatCircleDistance, geoDistance, geoToH3
Hash	cityHash64, xxHash64, sipHash64, MD5, SHA256
Condicional	sumIf, countIf, avgIf, minIf, maxIf

Essas funções usam automaticamente o motor chdb, independentemente da configuração.

---

​

Funções exclusivas do pandas

Algumas funções estão disponíveis apenas no pandas:

Categoria	Funções
Apply	Funções lambda personalizadas, funções definidas pelo usuário
Complex Pivot	Tabelas dinâmicas com agregações personalizadas
Stack/Unstack	Operações complexas de remodelagem
Interpolate	Métodos de interpolação de séries temporais

Essas funções usam automaticamente o motor do pandas, independentemente da configuração.

---

​

Correção de Dtype

Configure como o DataStore ajusta os tipos de dados entre motores.

​

Níveis de correção

from chdb.datastore.dtype_correction.config import CorrectionLevel
from chdb.datastore.config import config

# Sem correção
config.set_correction_level(CorrectionLevel.NONE)

# Apenas tipos críticos (tratamento de NULL, booleano)
config.set_correction_level(CorrectionLevel.CRITICAL)

# Alta prioridade (padrão) - incompatibilidades de tipo comuns
config.set_correction_level(CorrectionLevel.HIGH)

# Médio - correção mais agressiva
config.set_correction_level(CorrectionLevel.MEDIUM)

# Todos - corrigir todos os tipos possíveis
config.set_correction_level(CorrectionLevel.ALL)

​

Detalhes do nível de correção

Nível	Descrição	Tipos corrigidos
NONE	Nenhuma correção automática	Nenhum
CRITICAL	Correções essenciais	Tratamento de NULL, conversão de booleanos
HIGH (padrão)	Correções comuns	Precisão de inteiros/números de ponto flutuante, data e hora, codificação de strings
MEDIUM	Mais correções	Precisão decimal, tratamento de fuso horário
ALL	Correção máxima	Todas as diferenças de tipo

​

Quando os tipos precisam ser corrigidos

Diferenças entre tipos podem ocorrer quando:

1. ClickHouse → pandas: Diferentes tamanhos de inteiros (Int64 vs int64)
2. pandas → ClickHouse: Objetos Python para tipos SQL
3. Tratamento de NULL: NA do pandas vs NULL do ClickHouse
4. Booleano: Diferentes representações booleanas
5. DateTime: Diferenças de fuso horário

​

Exemplo

from chdb.datastore.dtype_correction.config import CorrectionLevel
from chdb.datastore.config import config

# Modo estrito - espera correspondências exatas de tipo
config.set_correction_level(CorrectionLevel.NONE)

# Modo relaxado - corrige automaticamente problemas de tipo
config.set_correction_level(CorrectionLevel.ALL)

---

​

API de configuração de função

​

Objeto function_config

from chdb.datastore.config import function_config

# Forçar engine para funções
function_config.use_chdb(*function_names)
function_config.use_pandas(*function_names)

# Definir preferência padrão
function_config.prefer_chdb()
function_config.prefer_pandas()

# Redefinir para o padrão (auto)
function_config.reset()

# Verificar configuração
function_config.get_engine('length')  # Retorna 'chdb', 'pandas' ou 'auto'

​

Sobrescrita por chamada

Alguns métodos permitem sobrescrever o motor em cada chamada:

# Usando o parâmetro engine (quando suportado)
ds['result'] = ds['col'].str.upper(engine='pandas')

---

​

Boas práticas

​

1. Comece com as configurações padrão

# Use o modo automático, deixe o DataStore decidir
config.use_auto()

​

2. Configure cargas de trabalho específicas

# Para processamento de strings otimizado para ClickHouse
function_config.use_chdb('length', 'substring', 'concat')

# Para comportamento de strings compatível com pandas
function_config.use_pandas('upper', 'lower')

​

3. Use o nível de correção adequado

# Desenvolvimento: mais flexível
config.set_correction_level(CorrectionLevel.ALL)

# Produção: mais rigoroso
config.set_correction_level(CorrectionLevel.HIGH)

​

4. Teste os dois motores

# Testar com chdb
config.use_chdb()
result_chdb = process_data()

# Testar com pandas
config.use_pandas()
result_pandas = process_data()

# Comparar resultados
assert result_chdb.equals(result_pandas)