Fonctions définies par l’utilisateur WebAssembly

Documentation des fonctions définies par l’utilisateur WebAssembly

ClickHouse permet de créer des fonctions définies par l’utilisateur (UDF) écrites en WebAssembly. Vous pouvez ainsi exécuter une logique personnalisée écrite dans des langages comme Rust, C, C++ ou d’autres, après les avoir compilés en modules WebAssembly.

​

Vue d’ensemble

Un module WebAssembly est un fichier binaire compilé qui contient une ou plusieurs fonctions pouvant être appelées depuis ClickHouse. Considérez un module comme une bibliothèque ou un objet partagé que vous chargez une seule fois et réutilisez à de multiples reprises.

Les modules WebAssembly contenant des UDF peuvent être écrits dans n’importe quel langage pouvant être compilé en WebAssembly, comme Rust, C ou C++.

Le code compilé en WebAssembly (code « invité ») et exécuté par ClickHouse (« host ») s’exécute dans un environnement isolé de type sandbox, avec accès uniquement à un espace mémoire dédié.

Le code invité exporte des fonctions que ClickHouse peut invoquer ; cela inclut les fonctions qui implémentent votre logique personnalisée (utilisée pour définir des UDF), ainsi que les fonctions utilitaires nécessaires à la gestion de la mémoire et à l’échange de données entre ClickHouse et le code WebAssembly.

Votre code doit être compilé en WebAssembly « autonome » (alias wasm32-unknown-unknown), sans dépendre d’un système d’exploitation ni d’une bibliothèque standard. En outre, seule la cible WebAssembly 32 bits par défaut est prise en charge (pas d’extension wasm64). Le module doit respecter l’un des protocoles de communication (ABI) pris en charge pour interagir avec ClickHouse.

Une fois compilé, le code binaire du module est chargé dans ClickHouse en l’insérant dans la table system.webassembly_modules. Après cela, vous pouvez créer des UDF qui référencent les fonctions exportées par le module à l’aide de l’instruction CREATE FUNCTION ... LANGUAGE WASM.

​

Prérequis

Activez la prise en charge de WebAssembly dans la configuration de ClickHouse :

<clickhouse>
    <allow_experimental_webassembly_udf>true</allow_experimental_webassembly_udf>
    <webassembly_udf_engine>wasmtime</webassembly_udf_engine>
</clickhouse>

Implémentations du moteur disponibles :

• wasmtime (par défaut, recommandé) — utilise WasmTime
• wasmedge — utilise WasmEdge

​

Quick Start

Cet exemple illustre le workflow complet de création d’une UDF WebAssembly en implémentant un calculateur de la conjecture de Collatz.

Nous écrirons le code au format texte WebAssembly (WAT), qui est une représentation lisible par l’humain de WebAssembly ; aucun langage de programmation n’est donc nécessaire à ce stade. ClickHouse exige que le module soit au format binaire ; nous utiliserons donc un transpileur pour convertir le WAT en WASM. Pour effectuer cette conversion, vous pouvez utiliser wat2wasm du WebAssembly Binary Toolkit (WABT) ou la commande parse de wasm-tools.

cat << 'EOF' | wasm-tools parse | clickhouse client -q "INSERT INTO system.webassembly_modules (name, code) SELECT 'collatz', code FROM input('code String') FORMAT RawBlob"
(module
  (func $next (param $n i32) (result i32)
    local.get $n i32.const 1 i32.and
    (if (result i32)
      (then local.get $n i32.const 3 i32.mul i32.const 1 i32.add)
      (else local.get $n i32.const 2 i32.div_u)))
  (func $steps (export "steps") (param $n i32) (result i32)
    (local $count i32)
    local.get $n i32.const 1 i32.lt_u
    (if (then i32.const 0 return))
    (block $done (loop $loop
      local.get $n i32.const 1 i32.eq br_if $done
      local.get $n call $next local.set $n
      local.get $count i32.const 1 i32.add local.set $count
      br $loop))
    local.get $count)
)
EOF

Dans l’extrait ci-dessus, nous envoyons directement le code binaire WASM au clickhouse client à l’aide de FORMAT RawBlob afin de l’insérer dans la table system.webassembly_modules.

Nous définissons ensuite l’UDF qui fait référence à la fonction steps exportée par le module :

CREATE FUNCTION collatz_steps LANGUAGE WASM ARGUMENTS (n UInt32) RETURNS UInt32 FROM 'collatz' :: 'steps';

Notez que nous indiquons le nom de la fonction du module après ::, car il diffère du nom de l’UDF.

Nous pouvons maintenant utiliser la fonction collatz_steps dans nos requêtes :

SELECT groupArray(collatz_steps(number :: UInt32))
FROM numbers(1, 100)
FORMAT TSV

La colonne number est explicitement convertie en UInt32, car les fonctions WebAssembly attendent une correspondance exacte avec les types spécifiés dans la signature de l’instruction CREATE FUNCTION.

Le résultat obtenu est la séquence des étapes de Collatz pour les nombres de 1 à 100, correspondant à la suite A006577 de l’OEIS.

[0,1,7,2,5,8,16,3,19,6,14,9,9,17,17,4,12,20,20,7,7,15,15,10,23,10,111,18,18,18,106,5,26,13,13,21,21,21,34,8,109,8,29,16,16,16,104,11,24,24,24,11,11,112,112,19,32,19,32,19,19,107,107,6,27,27,27,14,14,14,102,22,115,22,14,22,22,35,35,9,22,110,110,9,9,30,30,17,30,17,92,17,17,105,105,12,118,25,25,25]

​

Gérer les modules WASM via la table système

Les modules WebAssembly sont stockés dans la table system.webassembly_modules, qui a la structure suivante :

• Colonnes
  • name String — Nom du module. Non vide, caractères de mot uniquement.
  • code String — Code WASM binaire brut. En écriture seule ; les lectures renvoient une chaîne vide.
  • hash UInt256 — SHA256 du binaire du module (zéro s’il est présent sur le disk mais pas encore chargé).

La gestion des modules s’effectue via les opérations SQL standard sur cette table :

​

Insérer un module

INSERT INTO system.webassembly_modules (name, code)
SELECT 'my_module', base64Decode('AGFzbQEAAAA...');

Si nécessaire, fournissez le hash d’intégrité :

INSERT INTO system.webassembly_modules (name, code, hash)
SELECT 'my_module', base64Decode('...'), reinterpretAsUInt256(unhex('369f...c57d'));

Si le hash fourni ne correspond pas au SHA256 calculé pour le code du module, l’insertion échoue. Cela peut être utile lors du chargement de modules depuis des sources externes telles que S3 ou HTTP.

​

Distribuer un module à l’échelle d’un cluster

system.webassembly_modules est une table propre à chaque instance — un INSERT n’atteint que la réplique qui gère la connection. Il n’existe pas de forme ON CLUSTER pour l’instruction INSERT, donc un CREATE FUNCTION ... ON CLUSTER exécuté ensuite échouera sur les répliques qui ne disposent pas du module :

Code: 674. DB::Exception: WebAssembly module 'collatz' not found:
while adding user defined function `collatz_steps`. (RESOURCE_NOT_FOUND)

Pour répliquer un insert sur tous les nœuds, écrivez dans la fonction de table cluster plutôt que dans la table locale system.webassembly_modules :

cat collatz.wasm | clickhouse client -q "
  INSERT INTO FUNCTION cluster('default', 'system', 'webassembly_modules') (name, code)
  SELECT 'collatz', code FROM input('code String') FORMAT RawBlob"

Cette approche repose sur le fait que le chemin sous-jacent d’écriture distribuée passe par chaque réplique au sein de chaque shard, ce qui ne se produit que lorsque le cluster est configuré avec internal_replication=false. Avec internal_replication=true (la valeur par défaut pour les clusters qui utilisent ReplicatedMergeTree pour gérer eux-mêmes la réplication), l’insert est envoyé à une seule réplique saine par shard, et system.webassembly_modules n’est pas répliquée par ce chemin ; certaines répliques n’auront donc toujours pas le module. Dans cette configuration, vous devez effectuer un insert sur chaque réplique individuellement, par exemple en parcourant system.clusters et en écrivant via remote(...) pour chaque hôte, ou en copiant le binaire dans user_scripts/wasm/ sur chaque hôte.

Vous pouvez vérifier internal_replication pour un cluster avec SELECT cluster, shard_num, internal_replication FROM system.clusters.

Après l’insert diffusé, le module est présent sur chaque réplique et CREATE FUNCTION ... ON CLUSTER aboutit :

CREATE FUNCTION collatz_steps ON CLUSTER 'default'
LANGUAGE WASM FROM 'collatz' :: 'steps'
ARGUMENTS (n UInt32) RETURNS UInt32;

Vous pouvez vérifier que le module est chargé sur toutes les répliques avec clusterAllReplicas :

SELECT hostName(), name FROM clusterAllReplicas('default', system.webassembly_modules) WHERE name = 'collatz';

Les insertions dans system.webassembly_modules sont idempotentes pour une même paire (name, hash) ; il est donc sans risque de réexécuter l’insert distribué, et c’est un moyen raisonnable de rétablir l’état après le remplacement d’une réplique. Notez que les serveurs nouvellement ajoutés ne reçoivent pas rétroactivement les modules existants — vous devez réexécuter l’insert sur le cluster mis à jour, ou placer le binaire dans le répertoire user_scripts/wasm/ sur le nouvel hôte.

​

Lister les modules

SELECT name, lower(hex(reinterpretAsFixedString(hash))) AS sha256 FROM system.webassembly_modules

   ┌─name────┬─sha256───────────────────────────────────────────────────────────┐
1. │ collatz │ a084a10b7b5cb07db198bc93bf1f3c1f8cb8ef279df7a4f6b66b1cdd55d79c48 │
   └─────────┴──────────────────────────────────────────────────────────────────┘

​

Supprimer un module

La suppression s’effectue à l’aide de l’instruction DELETE FROM system.webassembly_modules WHERE name = '...'. Le prédicat doit être soit name = 'literal' pour une correspondance exacte, soit name LIKE 'pattern' pour supprimer tous les modules dont le nom correspond au motif ; aucune autre forme n’est acceptée.

DELETE FROM system.webassembly_modules WHERE name = 'collatz';

-- Bulk-delete every module whose name starts with `tmp_` (literal underscore is escaped as `\_`):
DELETE FROM system.webassembly_modules WHERE name LIKE 'tmp\_%';

Si des UDFs existantes font référence à l’un des modules correspondants, la suppression échoue ; vous devez donc d’abord supprimer ces UDFs.

​

Créer une UDF WebAssembly

Syntaxe :

CREATE [OR REPLACE] FUNCTION function_name
LANGUAGE WASM
FROM 'module_name' [:: 'source_function_name']
ARGUMENTS ( [name type[, ...]] | [type[, ...]] )
RETURNS return_type
[ABI ROW_DIRECT | ABI BUFFERED_V1 | ABI ASSEMBLYSCRIPT]
[DETERMINISTIC]
[SHA256_HASH 'hex']
[SETTINGS key = value[, ...]];

Paramètres :

• function_name : Nom de la fonction dans ClickHouse. Peut être différent du nom de la fonction exportée par le module.
• FROM 'module_name' :: 'source_function_name' : Nom du module WASM chargé et nom de la fonction du module WASM à utiliser (par défaut : function_name)
• ARGUMENTS : Liste des noms et types d’arguments (les noms sont facultatifs et utilisés pour les formats de sérialisation qui prennent en charge les champs nommés)
• ABI : Version de l’interface binaire d’application
  • ROW_DIRECT : Correspondance de types directe, traitement ligne par ligne
  • BUFFERED_V1 : Traitement par blocs avec sérialisation
  • ASSEMBLYSCRIPT : Traitement ligne par ligne pour les modules produits par le compilateur AssemblyScript. Les types numériques sont mappés vers les primitives d’AssemblyScript ; le String de ClickHouse est mappé vers le string d’AssemblyScript.
• DETERMINISTIC : Déclare la fonction comme déterministe — elle renvoie toujours le même résultat pour la même entrée. Lorsqu’elle est spécifiée, ClickHouse peut précalculer les appels dont tous les arguments sont des constantes : la fonction est évaluée une seule fois lors de l’analyse de la requête, puis le résultat est réutilisé pour chaque ligne.
• SHA256_HASH : Hash attendu du module pour vérification (rempli automatiquement s’il est omis) ; peut être utilisé pour garantir que le bon module WASM est chargé sur différentes répliques.
• SETTINGS : Paramètres propres à la fonction
  • serialization_format String — Format utilisé pour sérialiser les blocs d’arguments transmis au module et analyser le résultat renvoyé. Utilisé uniquement par ABI BUFFERED_V1. Valeurs prises en charge : MsgPack, JSONEachRow, CSV, TSV, TSVRaw, RowBinary et Buffers. Valeur par défaut : MsgPack. Les formats par blocs tels que Buffers doivent renvoyer une seule colonne dont le type correspond à la signature de fonction déclarée.
  • webassembly_udf_enable_fuel Bool — Active un budget de fuel limité pour la fonction. Valeur par défaut : true. Lorsque false, le paramètre de requête webassembly_udf_max_fuel est ignoré pour cette fonction. La désactivation des limites de fuel peut améliorer les performances lors de l’utilisation du moteur wasmtime. Cependant, pour du code invité non fiable ou bogué, cela peut augmenter le risque d’exécution incontrôlée.

​

Versions d’ABI

Pour interagir avec ClickHouse, les modules WebAssembly doivent respecter l’une des ABI (interfaces binaires d’application) prises en charge.

• ROW_DIRECT : correspondance directe des types (types primitifs Int32, UInt32, Int64, UInt64, Float32, Float64 uniquement)
• BUFFERED_V1 : types complexes avec sérialisation
• ASSEMBLYSCRIPT : interopération ligne par ligne avec les modules AssemblyScript ; prend en charge les types numériques et String.

​

ABI ROW_DIRECT

Appelle directement une fonction WASM exportée pour chaque ligne.

• Les arguments et les types de retour doivent être des types numériques Int32/UInt32/Int64/UInt64/Float32/Float64/Int128/UInt128.
• Les chaînes de caractères ne sont pas prises en charge par cette ABI.
• Les signatures doivent correspondre à l’export WASM (i32/i64/f32/f64/v128).
• Le module n’a pas besoin d’exporter de fonctions de support.

Par exemple, pour une fonction ayant la signature :

(func (param i32 i64 f32) (result f64) ...)

Peut être créé ainsi :

CREATE FUNCTION my_func ARGUMENTS (Int32, UInt64, Float32) RETURNS Float64 ...

WebAssembly ne distingue pas les arguments signés des arguments non signés, mais utilise plutôt des instructions différentes pour interpréter les valeurs. La taille de l’argument doit donc correspondre exactement, tandis que le caractère signé ou non est déterminé par les opérations à l’intérieur de la fonction.

​

ABI BUFFERED_V1

Cette ABI est expérimentale et est susceptible d’évoluer dans les prochaines versions.

Traite des blocs entiers en une seule fois via une (dé)sérialisation dans la mémoire WASM. Prend en charge tous les types d’arguments et de retour.

Les données sont échangées via des buffers dans la mémoire WASM. Un buffer est une structure de 8 octets contenant un pointeur vers les données et leur taille (deux valeurs u32 au format little-endian). Les buffers sont transmis par handle — un pointeur vers cette structure, et non vers les données elles-mêmes. Le code invité doit exporter deux fonctions permettant de créer et de détruire ces buffers.

Pour chaque bloc d’entrée, ClickHouse :

1. Sérialise les colonnes d’arguments à l’aide du serialization_format de la fonction (MsgPack par défaut). Les formats basés sur les lignes écrivent les valeurs ligne par ligne, avec les valeurs d’arguments dans l’ordre de leur déclaration dans ARGUMENTS ; les formats comportant des champs nommés utilisent les noms des arguments. Déclarez donc ces derniers dans ARGUMENTS lorsque vous utilisez de tels formats.
2. Appelle clickhouse_create_buffer, exportée par le module, et copie les données sérialisées dans la mémoire pointée par le buffer renvoyé.
3. Appelle la fonction définie par l’utilisateur avec deux arguments i32 : le handle du buffer d’entrée (0 si la fonction n’a aucun argument) et le nombre de lignes. La fonction renvoie un unique i32 — le handle du buffer de résultat, que le code invité alloue lui-même ; renvoyer 0 fait échouer la requête avec une erreur.
4. Lit le buffer de résultat : il doit contenir exactement une colonne avec exactement le même nombre de lignes, sérialisée dans le même format. Pour les formats comportant des champs nommés, tels que JSONEachRow, la colonne de résultat doit être nommée result.
5. Appelle clickhouse_destroy_buffer sur les handles du buffer d’entrée (le cas échéant) et du buffer de résultat. Le code invité ne doit pas libérer lui-même le buffer de résultat ni renvoyer le handle d’entrée comme résultat — il serait alors détruit deux fois.

La fonction est invoquée une fois par bloc d’entrée : une requête volumineuse est divisée en plusieurs blocs par le pipeline de requête (le nombre maximal de lignes par appel peut également être limité par le paramètre webassembly_udf_max_input_block_size). Le nombre de lignes transmis à chaque appel correspond donc à la taille de ce bloc, et non à celle de la requête entière.

Les octets exacts contenus dans les buffers sont définis par le format choisi, et le code invité doit les décoder et les encoder lui-même. En particulier, pour les valeurs String :

• MsgPack : ClickHouse écrit les valeurs String à l’aide de la famille de types bin (0xc4/0xc5/0xc6), et non de la famille str. Les deux familles sont acceptées lors de l’analyse du résultat.
• RowBinary : chaque String est préfixée de sa longueur en octets sous forme de varint non signé (LEB128), et non d’un entier à largeur fixe.
• JSONEachRow : chaque ligne de résultat doit être un objet avec la clé result, par exemple {"result":"value"}.

(module
  ;; Allocate a new buffer of specified size
  ;; Returns: handle to Buffer structure (not direct data pointer!) with pointer to data and size
  (func (export "clickhouse_create_buffer")
    (param $size i32)    ;; Size of data to allocate
    (result i32))        ;; Returns buffer handle with enough space

  ;; Free a buffer by its handle
  (func (export "clickhouse_destroy_buffer")
    (param $handle i32)  ;; Buffer handle to free
    (result))            ;; No return value

    ;; User-defined function
    (func (export "user_defined_function1")
      (param $input_buffer_handle i32)  ;; Input buffer handle
      (param $n i32)                    ;; Number of rows in input
      (result i32))                     ;; Returns output buffer handle
)

Exemple complet en C freestanding : str_reverse inverse les octets de chaque chaîne d’entrée en utilisant serialization_format = 'RowBinary'. Les instances de module sont réutilisées d’un bloc à l’autre ; clickhouse_destroy_buffer doit donc réellement libérer la mémoire. Ici, l’allocator se réinitialise une fois tous les buffers détruits.

#include <stdint.h>

typedef struct {
    uint8_t * data;
    uint32_t size;
} ClickHouseBuffer;

#define HEAP_SIZE (1 << 24)
static _Alignas(16) uint8_t heap[HEAP_SIZE];
static uint32_t heap_pos = 0;
static uint32_t live_buffers = 0;

__attribute__((export_name("clickhouse_create_buffer")))
ClickHouseBuffer * clickhouse_create_buffer(uint32_t size)
{
    uint32_t total = (sizeof(ClickHouseBuffer) + size + 15u) & ~15u;
    if (heap_pos + total > HEAP_SIZE)
        return 0; /* a zero handle makes the host fail the query with an error */
    ClickHouseBuffer * buf = (ClickHouseBuffer *) &heap[heap_pos];
    buf->data = &heap[heap_pos + sizeof(ClickHouseBuffer)];
    buf->size = size;
    heap_pos += total;
    ++live_buffers;
    return buf;
}

__attribute__((export_name("clickhouse_destroy_buffer")))
void clickhouse_destroy_buffer(ClickHouseBuffer * buf)
{
    if (--live_buffers == 0)
        heap_pos = 0;
}

/* RowBinary prefixes each String with its byte length as an unsigned varint (LEB128) */
static uint64_t read_varint(const uint8_t ** pp)
{
    uint64_t value = 0;
    for (int shift = 0;; shift += 7)
    {
        uint8_t b = *(*pp)++;
        value |= (uint64_t)(b & 0x7f) << shift;
        if (!(b & 0x80))
            return value;
    }
}

static void write_varint(uint8_t ** pp, uint64_t value)
{
    while (value >= 0x80)
    {
        *(*pp)++ = (uint8_t)(value | 0x80);
        value >>= 7;
    }
    *(*pp)++ = (uint8_t)value;
}

/* Reverses the bytes of each input string */
__attribute__((export_name("str_reverse")))
ClickHouseBuffer * str_reverse(ClickHouseBuffer * input, uint32_t num_rows)
{
    ClickHouseBuffer * out = clickhouse_create_buffer(input->size);
    if (!out)
        return 0;
    const uint8_t * in = input->data;
    uint8_t * o = out->data;
    for (uint32_t row = 0; row < num_rows; ++row)
    {
        uint64_t len = read_varint(&in);
        write_varint(&o, len);
        for (uint64_t i = 0; i < len; ++i)
            o[i] = in[len - 1 - i];
        in += len;
        o += len;
    }
    out->size = (uint32_t)(o - out->data);
    return out;
}

Compilez avec clang et wasm-ld (fourni avec LLVM/lld) :

clang --target=wasm32 -ffreestanding -nostdlib -fno-builtin -c str_reverse.c
wasm-ld --no-entry str_reverse.o -o str_reverse.wasm

Les fonctions doivent être visibles parmi les exports du module : marquez-les avec __attribute__((export_name("..."))) comme ci-dessus, ou établissez l’édition de liens avec wasm-ld --export-all. -fno-builtin empêche clang de convertir les simples boucles sur les octets en appels à memcpy/memset, qui ne sont pas disponibles sans bibliothèque standard.

Chargez le module et créez la fonction :

cat str_reverse.wasm | clickhouse client -q "INSERT INTO system.webassembly_modules (name, code) SELECT 'str_reverse', code FROM input('code String') FORMAT RawBlob"

CREATE FUNCTION str_reverse LANGUAGE WASM ABI BUFFERED_V1
FROM 'str_reverse' :: 'str_reverse'
ARGUMENTS (s String) RETURNS String
SETTINGS serialization_format = 'RowBinary';

SELECT str_reverse(toString(number + 100)) FROM numbers(3);

001
101
201

​

ABI ASSEMBLYSCRIPT

Cible les modules produits par le compilateur AssemblyScript. Chaque ligne déclenche un appel à la fonction exportée, en convertissant les valeurs ClickHouse en types primitifs AssemblyScript et en objets string.

Types pris en charge :

• Numériques : Int8/UInt8, Int16/UInt16 (élargis en i32 à l’interface), Int32/UInt32, Int64/UInt64, Float32, Float64

• String — correspond à string en AssemblyScript (UTF-16 dans la mémoire WASM). ClickHouse gère automatiquement la conversion UTF-8 ↔ UTF-16.

• Les classes AssemblyScript personnalisées ne sont pas prises en charge comme types d’argument ou de retour — leurs identifiants de classe à l’exécution ne sont pas stables d’une compilation à l’autre (voir AssemblyScript#2982).

Exigences du module :

Le module doit être compilé avec le runtime géré d’AssemblyScript afin que __new, __pin et __unpin soient exportés. La gestion standard des chaînes entrantes/sortantes s’appuie sur eux. Invocation recommandée :

asc src.ts --runtime incremental --exportRuntime -o src.wasm

AssemblyScript importe également env.abort pour les interruptions d’exécution (mémoire insuffisante, vérification des limites, etc.). ClickHouse fournit automatiquement cet import : lorsqu’un abort est déclenché, la requête en cours échoue avec une exception WASM_ERROR qui inclut le message AssemblyScript décodé et l’emplacement dans le code source.

Exemple:

// src.ts
export function add(a: u32, b: u32): u32 {
  return a + b;
}

export function greet(name: string): string {
  return "Hello, " + name + "!";
}

Après compilation avec asc et chargement du fichier .wasm obtenu dans system.webassembly_modules, déclarez les UDFs comme suit :

CREATE FUNCTION as_add
    LANGUAGE WASM ABI ASSEMBLYSCRIPT
    FROM 'as_example' :: 'add'
    ARGUMENTS (a UInt32, b UInt32) RETURNS UInt32;

CREATE FUNCTION as_greet
    LANGUAGE WASM ABI ASSEMBLYSCRIPT
    FROM 'as_example' :: 'greet'
    ARGUMENTS (name String) RETURNS String;

​

Remarque sur le développement de UDFs en Rust

Pour les programmes Rust, nous fournissons une crate utilitaire clickhouse-wasm-udf afin de simplifier le développement de WebAssembly UDFs pour ClickHouse. Cette crate fournit des fonctions de gestion de la mémoire. Vous n’avez donc pas besoin d’implémenter manuellement les fonctions clickhouse_create_buffer et clickhouse_destroy_buffer : il vous suffit d’ajouter la crate comme dépendance. Des macros #[clickhouse_wasm_udf] sont également disponibles pour encapsuler vos fonctions Rust habituelles dans le format ABI requis.

Avec cette crate, vous pouvez écrire des UDFs comme ceci :

use clickhouse_wasm_udf_bindgen::clickhouse_udf;

#[clickhouse_udf]
pub fn some_udf(data: String) -> HashMap<String, String> {
    // Your implementation here
}

Les macros généreront une fonction wrapper qui accepte et renvoie des structures de buffer, et gérera automatiquement la sérialisation/désérialisation à l’aide de serde.

​

API hôte disponible pour les modules

Les fonctions hôte suivantes peuvent être importées et utilisées par les modules :

• clickhouse_server_version() -> i64 — renvoie la version du serveur ClickHouse sous forme d’entier (p. ex. 25011001 pour v25.11.1.1).
• clickhouse_throw(ptr: i32, size: i32) — lève une erreur avec le message fourni. Accepte un pointeur vers l’emplacement mémoire contenant la chaîne du message d’erreur ainsi que la taille de cette chaîne.
• clickhouse_log(ptr: i32, size: i32) — écrit un message dans le journal texte du serveur ClickHouse.
• clickhouse_random(ptr: i32, size: i32) — remplit la mémoire avec des octets aléatoires.
• env.abort(message: i32, fileName: i32, line: i32, column: i32) — fournie pour les modules compatibles avec AssemblyScript. Son appel (ou le déclenchement d’un trap du runtime AssemblyScript qui l’appelle) met fin à l’UDF avec une exception WASM_ERROR contenant le message décodé et l’emplacement dans le code source. Les modules qui n’importent pas env.abort ne sont pas affectés.

​

Paramètres

Les paramètres suivants, au niveau de la requête, contrôlent l’exécution des UDF WebAssembly :

• webassembly_udf_max_fuel — Limite de fuel par exécution d’une instance d’UDF WebAssembly. Chaque instruction WebAssembly consomme une certaine quantité de fuel. La valeur est multipliée par 1024 avant d’être transmise au runtime, ainsi webassembly_udf_max_fuel = 1 correspond à environ 1024 unités de fuel. Définissez-la sur 0 pour supprimer toute limite finie. S’applique uniquement aux fonctions dont le paramètre par fonction webassembly_udf_enable_fuel est true, ce qui est la valeur par défaut.

• webassembly_udf_max_memory — Limite de mémoire, en octets, par instance d’UDF WebAssembly.

• webassembly_udf_max_input_block_size — Nombre maximal de lignes transmises à une UDF WebAssembly dans un seul bloc. Définissez 0 pour traiter toutes les lignes en une seule fois.

• webassembly_udf_max_instances — Nombre maximal d’instances d’UDF WebAssembly pouvant s’exécuter en parallèle par fonction.

Exemple d’utilisation :

SET webassembly_udf_max_fuel = 200000;
SELECT my_wasm_udf(column) FROM table;

​

Voir aussi

• Présentation des UDF ClickHouse