Funciones definidas por el usuario en Cloud

1. Mediante SQL
2. Mediante la consola y su propio código
3. Mediante la Cloud API (beta)
4. Mediante Terraform (beta)

​

Funciones definidas por el usuario en SQL

1. Inicie sesión en Cloud Console y abra la consola SQL
2. Escriba la siguiente consulta SQL para crear la función isBusinessHours:

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

3. Ejecute lo siguiente para probar la UDF que acaba de crear:

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

1   0

4. Puede usar el comando DROP FUNCTION para eliminar la UDF que acaba de crear:

DROP FUNCTION isBusinessHours

• La configuración a nivel de sesión (establecida mediante la instrucción SET) no se propaga al contexto de ejecución de las UDF
• Las UDF no heredan la configuración del perfil de usuario
• La configuración a nivel de consulta no se aplica durante la ejecución de las UDF

​

Funciones ejecutables definidas por el usuario

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

​

Tiempo de ejecución nativo (binarios 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 .

​

Referencia de configuración

​

Formatos y encabezados de fragmento

​

Acceso a la red

​

Memory limit

​

Funciones deterministas y la caché de consultas

​

Reinicios del servicio

​

Monitorización

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;

​

Recomendaciones de rendimiento

​

Solución de problemas

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

• La consulta se bloquea y luego falla por tiempo de espera agotado: el proceso almacenó temporalmente su salida en el búfer en un formato orientado a filas sin Send chunk header. Actívelo y realice un vaciado una vez por fragmento, o una vez por bloque si usa el formato Native.
• Código de retorno 1 con un traceback de MemoryError (Python): se superó el memory limit. Aumente Memory limit o reduzca el consumo de memoria por proceso.
• Fallos intermitentes con el tipo executable bajo cargas elevadas: cambie a executable_pool.
• El estado del build es error: falta main.py (Python) o amd64/main y arm64/main (Native) en la raíz del zip, o el archivo comprimido contiene enlaces simbólicos.
• No se puede crear la función: el nombre coincide con el de una función integrada.

​

Administrar UDFs con la Cloud API

1. Crear una URL de carga para obtener una URL prefirmada para cargar archivos application/zip y, a continuación, cargar en ella su archivo ZIP. Cada ID de carga solo puede utilizarse para un intento de creación o de versión; solicite una nueva URL de carga al reintentar.
2. Crear la UDF a partir del archivo cargado, especificando el nombre de la función, el runtime, los argumentos y el tipo de retorno.
3. Adjuntar la UDF a un servicio. Si se omite la versión, se adjunta la versión lista más reciente. El servicio debe estar en ejecución; primero se pueden activar los servicios inactivos.

​

Administrar UDFs con Terraform

• clickhouse_udf administra la función propiamente dicha. Recibe un archivo ZIP con el código fuente de la función y publica una nueva versión cada vez que cambia el hash del archivo, esperando a que finalice la compilación.
• clickhouse_udf_attachment adjunta una versión de una UDF a un servicio. Un servicio puede tener como máximo una versión de una función a la vez. Puede fijar un número de versión o hacer referencia a clickhouse_udf.<name>.version para actualizar automáticamente los servicios a la versión más reciente.

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
}