Fonctions définies par l’utilisateur dans Cloud

Les fonctions définies par l’utilisateur (UDF) permettent d’étendre le comportement de ClickHouse au-delà de ce que permettent les plus de mille fonctions intégrées. Dans ClickHouse Cloud, il existe plusieurs façons de créer et de gérer des fonctions définies par l’utilisateur :

À l’aide de SQL
À l’aide de l’UI et de votre propre code (Public Beta)
À l’aide de la Cloud API (Beta)
À l’aide de Terraform (alpha)

Fonctions SQL définies par l’utilisateur

Les UDF SQL peuvent être créées à l’aide de l’instruction CREATE FUNCTION à partir d’une expression lambda. Dans cet exemple, nous allons créer une simple fonction exécutable définie par l’utilisateur, isBusinessHours. La fonction vérifiera si un timestamp donné correspond aux heures ouvrées habituelles et renverra true si c’est le cas, sinon false.

Connectez-vous à Cloud Console et ouvrez la console SQL
É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;

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

Vous devriez obtenir le résultat suivant :

1   0

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

DROP FUNCTION isBusinessHours

ImportantLes UDFs dans ClickHouse Cloud n’héritent pas des paramètres définis au niveau de l’utilisateur. Elles s’exécutent avec les paramètres système par défaut.

Cela signifie :

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 créées via l’UI

ClickHouse Cloud offre une interface de configuration dans l’UI pour créer des fonctions définies par l’utilisateur. Dans cet exemple, nous allons créer la même fonction définie par l’utilisateur exécutable simple, isBusinessHours, qui vérifie si un timestamp donné se situe dans les heures ouvrées habituelles. Nous l’avons précédemment créée en SQL, mais cette fois, nous allons la créer en Python et la configurer via l’UI.

Créer le fichier Python

Créez un nouveau fichier main.py localement :

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

Si votre script Python importe des paquets tiers, indiquez-les dans un fichier requirements.txt, et ClickHouse Cloud les installera pour vous. Vous pouvez aussi inclure directement les dépendances dans l’archive ZIP, mais vous devrez alors fournir les paquets mis en cache pour les deux architectures CPU ; requirements.txt reste donc la solution la plus simple. Par exemple :

requests>=2.28.0
numpy>=1.23.0

ClickHouse Cloud s’attend à trouver main.py dans l’archive zip que vous téléverserez via l’UI à l’étape suivante. Si vous donnez un autre nom au fichier, une erreur se produira.

Dépendances regroupées et fichiers locaux

Pour inclure les paquets de dépendances et tout autre fichier local (par exemple, des fichiers wheel, des fichiers de configuration ou des fichiers de données), placez-les dans le même répertoire que main.py et requirements.txt. Lorsque vous créez l’archive ZIP, incluez tous les fichiers :

zip is_business_hours.zip main.py requirements.txt

Vous pouvez référencer, dans votre code Python, le répertoire de base du chemin local inclus en utilisant os.path.dirname(os.path.abspath(__file__)). Cela renvoie le chemin absolu du répertoire où se trouve votre main.py dans l’archive ZIP, ce qui vous permet d’accéder aux autres fichiers inclus :

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

Cela est utile lorsque vous devez :

Accéder aux fichiers de configuration inclus avec votre UDF
Charger des packages wheel pour des dépendances personnalisées
Référencer des scripts supplémentaires ou des fichiers de données

Compressez maintenant le fichier en archive ZIP :

zip is_business_hours.zip main.py

Les liens symboliques ne sont pas autorisésClickHouse Cloud rejette les archives UDF qui contiennent des liens symboliques. Assurez-vous que votre archive ZIP ne contient que des fichiers et répertoires ordinaires — les téléversements contenant des liens symboliques échoueront lors de la validation.

Créer une UDF via l’UI

Depuis la page d’accueil de la console Cloud, cliquez sur le nom de votre organisation dans le menu en bas à gauche.
Sélectionnez Fonctions définies par l’utilisateur dans le menu.
Sur la page des fonctions définies par l’utilisateur, cliquez sur Configurer une UDF. Un panneau de configuration s’ouvre sur la droite de l’écran.
Saisissez un nom de fonction. Pour cet exemple, utilisez isBusinessHours.
Sélectionnez un type de fonction, Executable pool ou Executable :
- Executable pool : un pool de processus persistants est maintenu, et un processus est prélevé dans ce pool pour effectuer les lectures.
- Executable : le script s’exécute à chaque requête.
Pour cet exemple, utilisez les paramètres par défaut. Pour obtenir la liste complète des paramètres de configuration, consultez Executable user-defined functions.
Cliquez sur Parcourir le fichier pour téléverser le fichier .zip créé au début de ce tutoriel.
Ajoutez un nouvel argument. Pour cet exemple, ajoutez un argument timestamp de type DateTime.
Sélectionnez un type de retour. Pour cet exemple, sélectionnez Bool.
Cliquez sur Créer une UDF. Une boîte de dialogue affiche l’état actuel du build.
- En cas de problème, l’état devient error.
- Sinon, l’état passe de building à provisioning. Votre service doit être actif pour terminer le provisionnement. Si votre service est inactif, cliquez sur Réveiller le service dans le panneau Détails de l’UDF à côté du nom du service.
- Une fois l’opération terminée, l’état devient deployed.

Testez votre UDF

revenez à la page d’accueil de la SQL Console en cliquant sur Settings - return to your service view dans le coin supérieur gauche de la page
cliquez sur SQL Console dans le menu de gauche
saisissez la requête suivante :

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

Vous devriez obtenir le résultat suivant :

true    false

Créer une nouvelle version

Pour modifier le code d’une UDF, créez une nouvelle version. Le panneau Edit sert uniquement à gérer les services auxquels une UDF est affectée ; y téléverser un fichier ne remplacera pas le code déployé.

Depuis la page d’accueil de la console Cloud, cliquez sur le nom de votre organisation dans le menu en bas à gauche.
Sélectionnez User-defined functions dans le menu.
Cliquez sur les trois points sous Actions pour la UDF isBusinessHours, puis sur Create new version
Téléversez un fichier zip contenant le code modifié, ou modifiez les paramètres, puis cliquez sur Create new version

Vous avez ajouté avec succès votre première fonction définie par l’utilisateur via l’UI, confirmé qu’elle s’exécute et vu comment en créer une nouvelle version si nécessaire.

Gérer les UDF avec l’API Cloud

Tout ce qui est disponible dans l’UI est également accessible par programmation via l’API ClickHouse Cloud. Les endpoints UDF vous permettent d’automatiser l’ensemble du cycle de vie d’une UDF : téléversement d’archives sources, création de fonctions et de versions, association à des services et suppression.

Ces endpoints sont en bêta et le contrat de l’API est susceptible d’évoluer.

Le workflow type pour créer et déployer une UDF via l’API est le suivant :

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.
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.
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.

L’ensemble des endpoints :

Endpoint	Description
Créer une URL de téléversement UDF	Crée une URL présignée pour téléverser un fichier `application/zip`, limitée à l’organisation
Créer une UDF	Crée une nouvelle UDF à partir d’une archive téléversée
Lister les UDF	Renvoie la dernière version de chaque UDF de l’organisation
Obtenir une UDF	Renvoie la dernière version d’une UDF
Supprimer une UDF	Supprime toutes les versions d’une UDF et la détache de tous les services
Créer une version d’UDF	Utilise une archive source, affecte une version et lance la build de l’UDF
Lister les versions d’UDF	Renvoie toutes les versions d’une UDF
Supprimer une version d’UDF	Supprime une version d’UDF qui n’est associée à aucun service
Associer une UDF à un service	Associe une version d’UDF à un service et remplace la version actuelle si nécessaire
Lister les associations d’UDF	Renvoie les associations actuelles d’une UDF aux services
Obtenir une association d’UDF	Renvoie l’association actuelle d’une UDF à un service
Détacher une UDF d’un service	Détache une UDF d’un service

Consultez la référence de l’API UDF pour les schémas de requête et de réponse.

Gérer les UDF avec Terraform

Le provider Terraform ClickHouse officiel inclut deux ressources pour gérer les UDF en tant qu’infrastructure as code :

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 du build.
clickhouse_udf_attachment attache 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.

Ces ressources sont disponibles à partir de la version 3.24.0 du provider. Elles sont au statut alpha et leur comportement peut changer dans les prochaines versions du provider.

Par exemple, pour déployer avec Terraform l’UDF isBusinessHours de l’exemple précédent :

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
}

L’opération d’association ne réussit que pour les versions prêtes et peut prendre რამდენიმე minutes ; les services inactifs sont automatiquement réactivés. La suppression d’une ressource clickhouse_udf supprime toutes les versions de la FUNCTION et la détache de tous les services.

ClickHouse Cloud

Bring Your Own Cloud

ClickHouse Private

Fonctions définies par l’utilisateur dans Cloud

Fonctions SQL définies par l’utilisateur

Fonctions définies par l’utilisateur créées via l’UI

Gérer les UDF avec l’API Cloud

Gérer les UDF avec Terraform

​Fonctions SQL définies par l’utilisateur

​Fonctions définies par l’utilisateur créées via l’UI

​Gérer les UDF avec l’API Cloud

​Gérer les UDF avec Terraform

Fonctions SQL définies par l’utilisateur

Fonctions définies par l’utilisateur créées via l’UI

Gérer les UDF avec l’API Cloud

Gérer les UDF avec Terraform