> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Documentation des fonctions définies par l’utilisateur WebAssembly
# Fonctions définies par l’utilisateur WebAssembly
export const ExperimentalBadge = () => {
return
Fonctionnalité expérimentale
;
};
export const CloudNotSupportedBadge = () => {
return
Non pris en charge par ClickHouse Cloud
;
};
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 :
```xml theme={null}
true
wasmtime
```
Implémentations du moteur disponibles :
* `wasmtime` (par défaut, recommandé) — utilise [WasmTime](https://github.com/bytecodealliance/wasmtime)
* `wasmedge` — utilise [WasmEdge](https://github.com/WasmEdge/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](https://en.wikipedia.org/wiki/Collatz_conjecture).
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)](https://github.com/WebAssembly/wabt) ou la commande `parse` de [wasm-tools](https://github.com/bytecodealliance/wasm-tools).
```bash theme={null}
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 :
```sql theme={null}
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 :
```sql theme={null}
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](https://oeis.org/A006577).
```text theme={null}
[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
```sql theme={null}
INSERT INTO system.webassembly_modules (name, code)
SELECT 'my_module', base64Decode('AGFzbQEAAAA...');
```
Si nécessaire, fournissez le hash d’intégrité :
```sql theme={null}
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 :
```text theme={null}
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` :
```bash theme={null}
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 :
```sql theme={null}
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` :
```sql theme={null}
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
```sql theme={null}
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.
```sql theme={null}
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** :
```sql theme={null}
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](https://www.assemblyscript.org). 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](https://www.assemblyscript.org) ; 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 :
```sql theme={null}
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](https://en.wikipedia.org/wiki/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.
```c theme={null}
#include
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) :
```bash theme={null}
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 :
```bash theme={null}
cat str_reverse.wasm | clickhouse client -q "INSERT INTO system.webassembly_modules (name, code) SELECT 'str_reverse', code FROM input('code String') FORMAT RawBlob"
```
```sql theme={null}
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);
```
```text theme={null}
001
101
201
```
### ABI ASSEMBLYSCRIPT
Cible les modules produits par le compilateur [AssemblyScript](https://www.assemblyscript.org). 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](https://github.com/AssemblyScript/assemblyscript/issues/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 :
```bash theme={null}
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**:
```typescript theme={null}
// 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 :
```sql theme={null}
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](https://crates.io/crates/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 :
```rust theme={null}
use clickhouse_wasm_udf_bindgen::clickhouse_udf;
#[clickhouse_udf]
pub fn some_udf(data: String) -> HashMap {
// 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 :
```sql theme={null}
SET webassembly_udf_max_fuel = 200000;
SELECT my_wasm_udf(column) FROM table;
```
## Voir aussi
* [Présentation des UDF ClickHouse](/fr/reference/functions/regular-functions/udf)