Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

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

View as MarkdownEdit this pageReport an issueSet up docs MCP

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)
Navigation