Fonctions définies par l’utilisateur dans Cloud

1. À l’aide de SQL
2. À l’aide de la console et de votre propre code
3. À l’aide de la Cloud API (Beta)
4. À l’aide de Terraform (Beta)

​

Fonctions SQL définies par l’utilisateur

1. Connectez-vous à Cloud Console et ouvrez la console SQL
2. Écrivez la SQL query suivante pour créer la fonction isBusinessHours :

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

3. Exécutez ce qui suit pour tester l’UDF que vous venez de créer :

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

1   0

4. Vous pouvez utiliser la commande DROP FUNCTION pour supprimer l’UDF que vous venez de créer :

DROP FUNCTION isBusinessHours

• Les paramètres de session (définis via l’instruction SET) ne sont pas transmis au contexte d’exécution des UDFs
• Les paramètres du profil utilisateur ne sont pas hérités par les UDFs
• Les paramètres au niveau de la requête ne s’appliquent pas lors de l’exécution des UDFs

​

Fonctions définies par l’utilisateur exécutables

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

​

Runtime Native (binaires compilés)

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 .

​

Référence de configuration

​

Formats et en-têtes de fragment

​

Accès réseau

​

Limite de mémoire

​

Fonctions déterministes et cache de requêtes

​

Redémarrages du service

​

Supervision

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;

​

Recommandations de performance

​

Dépannage

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

• La requête se bloque, puis échoue sur un timeout : le processus a mis sa sortie en tampon dans un format orienté lignes sans Send chunk header. Activez cette option et effectuez un vidage à chaque fragment, ou à chaque bloc si vous utilisez le format Native.
• Code de retour 1 avec une trace d’appels MemoryError (Python) : la limite de mémoire a été dépassée. Augmentez la limite de mémoire ou réduisez la mémoire utilisée par processus.
• Échecs intermittents avec le type executable sous forte charge : passez à executable_pool.
• Le statut de construction indique une erreur : main.py (Python) ou amd64/main et arm64/main (Native) sont absents de la racine du zip, ou l’archive contient des liens symboliques.
• Impossible de créer la fonction : son nom entre en conflit avec celui d’une fonction intégrée.

​

Gérer les UDF avec l’API Cloud

1. Créez une URL de téléversement afin d’obtenir une URL présignée pour téléverser un fichier application/zip, puis téléversez-y votre archive ZIP. Chaque ID de téléversement ne peut être utilisé que pour une seule tentative de création ou de création de version ; demandez une nouvelle URL de téléversement lors d’une nouvelle tentative.
2. Créez l’UDF à partir de l’archive téléversée, en spécifiant le nom de la fonction, le runtime, les arguments et le type de retour.
3. Associez l’UDF à un service. Si la version est omise, la dernière version prête est associée. Le service doit être en cours d’exécution ; les services inactifs peuvent d’abord être réactivés.

​

Gérer les UDF avec Terraform

• clickhouse_udf gère la fonction elle-même. Cette ressource accepte une archive ZIP contenant le code source de la fonction et publie une nouvelle version chaque fois que le hash de l’archive change, en attendant la fin de la construction.
• clickhouse_udf_attachment associe une version d’UDF à un service. Un service ne peut utiliser qu’une seule version d’une fonction à la fois. Vous pouvez épingler un numéro de version fixe ou référencer clickhouse_udf.<name>.version pour mettre automatiquement à jour les services vers la dernière version.

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
}