Funções definidas pelo usuário no Cloud

1. Usando SQL
2. Usando o console e seu próprio código
3. Usando a Cloud API (beta)
4. Usando o Terraform (beta)

​

Funções Definidas pelo Usuário em SQL

1. Faça login no Cloud Console e abra o SQL Console
2. Escreva a seguinte consulta SQL para criar a função isBusinessHours:

CREATE FUNCTION isBusinessHours AS (ts) ->
toDayOfWeek(ts) BETWEEN 1 AND 5
AND toHour(ts) BETWEEN 9 AND 17;

3. Execute o comando abaixo para testar sua UDF recém-criada:

SELECT isBusinessHours('2026-03-20 10:00:00'::DateTime), isBusinessHours('2026-03-20 23:00:00'::DateTime);

1   0

4. Você pode usar o comando DROP FUNCTION para remover a UDF que acabou de criar:

DROP FUNCTION isBusinessHours

• As configurações no nível da sessão (definidas pela instrução SET) não são propagadas para o contexto de execução das UDFs
• As configurações de perfil do usuário não são herdadas pelas UDFs
• As configurações no nível da consulta não se aplicam durante a execução das UDFs

​

Funções Definidas pelo Usuário executáveis

cat > main.py << 'EOF'
import sys
from datetime import datetime

for line in sys.stdin:
    ts = datetime.fromisoformat(line.strip())
    result = 1 if (0 <= ts.weekday() <= 4 and 9 <= ts.hour <= 17) else 0
    print(result)
    sys.stdout.flush()
EOF

requests>=2.28.0
numpy>=1.23.0

zip is_business_hours.zip main.py

zip -r ../is_business_hours.zip .

import os

# Get the base directory of the bundled files
base_dir = os.path.dirname(os.path.abspath(__file__))
config_path = os.path.join(base_dir, 'config.json')

SELECT isBusinessHours('2026-03-20 10:00:00'::DateTime), isBusinessHours('2026-03-20 23:00:00'::DateTime);

true    false

​

Tempo de execução nativo (binários compilados)

my-udf.zip
├── amd64/
│   ├── main            # linux/amd64 executable
│   └── my_data.json    # optional data files
└── arm64/
    ├── main            # linux/arm64 executable
    └── my_data.json

rustup target add x86_64-unknown-linux-musl aarch64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl
cargo build --release --target aarch64-unknown-linux-musl

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o amd64/main .
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o arm64/main .

​

Referência de configuração

​

Formatos e cabeçalhos de fragmento

​

Acesso à rede

​

Limite de memória

​

Funções determinísticas e o cache de consultas

​

Reinicializações do serviço

​

Monitoramento

SELECT
    event_time,
    query_duration_ms,
    ProfileEvents['ExecutableUserDefinedFunctionInvocations']                              AS udf_invocations,
    round(ProfileEvents['ExecutableUserDefinedFunctionElapsedMicroseconds'] / 1e6, 2)     AS udf_wall_s,
    round(ProfileEvents['ExecutableUserDefinedFunctionPoolWaitMicroseconds'] / 1e6, 2)    AS udf_pool_wait_s,
    round((ProfileEvents['ExecutableUserDefinedFunctionUserTimeMicroseconds']
         + ProfileEvents['ExecutableUserDefinedFunctionSystemTimeMicroseconds']) / 1e6, 2) AS udf_cpu_s
FROM system.query_log
WHERE type = 'QueryFinish'
  AND ProfileEvents['ExecutableUserDefinedFunctionInvocations'] > 0
ORDER BY event_time DESC
LIMIT 20;

​

Orientações de desempenho

​

Solução de problemas

Code: 754. DB::Exception: User defined function 'isBusinessHours' failed. Command: '...', Arguments: [...]. Original error: ... Child process was exited with return code 1: Stderr: <...>

• A consulta trava e depois falha por tempo limite esgotado: o processo armazenou a saída em buffer em um formato orientado a linhas sem Send chunk header. Habilite essa opção e faça flush uma vez por fragmento, ou uma vez por bloco ao usar o formato Native.
• Código de retorno 1 com um traceback de MemoryError (Python): o limite de memória foi excedido. Aumente o Memory limit ou reduza o consumo de memória por processo.
• Falhas intermitentes com o tipo executable sob carga elevada: mude para executable_pool.
• O status da compilação é erro: main.py (Python) ou amd64/main e arm64/main (Native) não estão na raiz do zip, ou o arquivo contém links simbólicos.
• Não é possível criar a função: o nome conflita com o de uma função interna.

​

Gerencie UDFs com a Cloud API

1. Crie uma URL de upload para obter uma URL pré-assinada para upload de application/zip e, em seguida, faça upload do seu arquivo ZIP. Cada ID de upload pode ser usado em apenas uma tentativa de criação ou versionamento; solicite uma nova URL de upload ao tentar novamente.
2. Crie a UDF a partir do arquivo enviado, especificando o nome da função, o runtime, os argumentos e o tipo de retorno.
3. Anexe a UDF a um serviço. Quando a versão é omitida, a versão pronta mais recente é anexada. O serviço deve estar em execução; serviços inativos podem ser ativados antes.

​

Gerencie UDFs com o Terraform

• clickhouse_udf gerencia a própria função. Ele aceita um arquivo ZIP com o código-fonte da função e publica uma nova versão sempre que o hash do arquivo é alterado, aguardando a conclusão da compilação.
• clickhouse_udf_attachment anexa uma versão de UDF a um serviço. Um serviço comporta no máximo uma versão de uma função por vez. Você pode fixar um número de versão específico ou fazer referência a clickhouse_udf.<name>.version para atualizar automaticamente os serviços para a versão mais recente.

resource "clickhouse_udf" "is_business_hours" {
  function_name = "isBusinessHours"
  runtime       = "python3.11"
  type          = "executable_pool"
  return_type   = "Bool"

  arguments = [
    { name = "timestamp", type = "DateTime" },
  ]

  source_archive_path = "${path.module}/is_business_hours.zip"
  source_archive_hash = filebase64sha256("${path.module}/is_business_hours.zip")
}

resource "clickhouse_udf_attachment" "production" {
  function_name = clickhouse_udf.is_business_hours.function_name
  service_id    = var.service_id
  version       = clickhouse_udf.is_business_hours.version
}

resource "clickhouse_udf_attachment" "dev" {
  function_name = clickhouse_udf.is_business_hours.function_name
  service_id    = var.dev_service_id
  version       = clickhouse_udf.is_business_hours.version
}

resource "clickhouse_udf_attachment" "prod" {
  function_name = clickhouse_udf.is_business_hours.function_name
  service_id    = var.prod_service_id
  version       = var.prod_udf_version
}