Product Documentation

Appearance

All platforms

WASM_RUNNER ​

Execute a base64-encoded WASM math function written in C.

Before calling, enable the feature with the enable_wasm_udfs configuration variable.

WASM_RUNNER(base64_module, function_name [, arg1, arg2, ...])
WASM_RUNNER_F64(base64_module, function_name [, arg1, arg2, ...])
WASM_RUNNER_F32(base64_module, function_name [, arg1, arg2, ...])
WASM_RUNNER_I64(base64_module, function_name [, arg1, arg2, ...])
WASM_RUNNER_I32(base64_module, function_name [, arg1, arg2, ...])

WASM_RUNNER (a synonym for WASM_RUNNER_F64) returns a FLOAT8 result. It expects the WASM module function to return double and will error if the C function return type is not so. The number of arguments that the WASM C function has must match the number of arguments passed in after the base64_module and function_name.

The other variants of the function are also strict in terms of the expected return type from the C function and the number of arguments. These variants exist to support native math at the corresponding precision. The C math functions may provide a mix of int32, in64, float and double arguments.

Arguments ​

base64_module
A literal string containing the Base64-encoded WASM binary. This binary must export a C-style function that takes numeric inputs and returns a numeric result. This must be a string literal, it cannot be an expression.
function_name
A literal string matching the exact name of the function inside the WASM module. This must be a string literal, it cannot be an expression.
arg1 ... argN
One or more SQL numeric arguments. Supported input types are:
  • FLOAT4 (float)
  • FLOAT8 (double)
  • INT (int32)
  • BIGINT (int64)
  • NUMERIC (arbitrary precision)

Return Type ​

  • FLOAT4 - WASM_RUNNER_F32
  • FLOAT8 - WASM_RUNNER
  • FLOAT8 - WASM_RUNNER_F64
  • INT - WASM_RUNNER_I32
  • BIGINT - WASM_RUNNER_I64

Type Conversion and Precision ​

WARNING

In the case of NUMERIC values all input arguments are first converted to a 64-bit IEEE double (FLOAT8) inside WASM_RUNNER. The value returned is also a FLOAT8.

Example ​

sql
SELECT 
    val, 
    WASM_RUNNER('AGFzbQEAAAABCgJgAnx8AXxgAAADBQQAAQEABAUBcAEBAQUDAQACBggBfwFBgIgECwcUAgZtZW1vcnkCAAdiaW5fYWRkAAMKJgQHACAAIAGgCwIACw4AEIGAgIAAEIGAgIAACwoAIAAgARAAEAIL',
    'bin_add',
    val,
    val) 
FROM gentable 
WHERE val < 5;

Running this query results in:

 val | wasm_runner
-----+-------------
   1 |           2
   2 |           4
   3 |           6
   4 |           8

In the example above, the first argument to WASM_RUNNER is a base64 string representing the WASM bytecode for the C function:

c
double bin_add(double a, double b) {
  return a + b;
}

See the WASM_RUNNER how-to guide for details on how to build C-based math functions.

NULL Handling ​

If any argument passed to WASM_RUNNER is NULL, the function immediately returns NULL without invoking the WASM module. This matches standard PostgreSQL behavior for mathematical UDFs: every NULL input yields a NULL output.

Example:

sql
SELECT WASM_RUNNER('<base64>', 'f', 10.0, NULL, 5.0);
-- returns NULL

In the case where the table contains a NULL value, WASM_RUNNER returns NULL for the NULL input value:

sql
SELECT
    val,
    WASM_RUNNER('AGFzbQEAAAABCgJgAnx8AXxgAAADBQQAAQEABAUBcAEBAQUDAQACBggBfwFBgIgECwcUAgZtZW1vcnkCAAdiaW5fYWRkAAMKJgQHACAAIAGgCwIACw4AEIGAgIAAEIGAgIAACwoAIAAgARAAEAIL', 
    'bin_add',
    val,
    val)
FROM gentable;

Which produces:

 val | wasm_runner
-----+-------------
     |
   0 |           0
   1 |           2
   2 |           4
   3 |           6
(5 rows)

Division by Zero ​

If the WASM function itself performs a division (integer or floating) by zero, or triggers any runtime trap, WASM_RUNNER generates a SQL error. A division-by-zero error aborts the query (or transaction savepoint), raising an error such as:

ERROR:  division by zero

Not a Number ​

An attempt to take the square root of a negative number in a WASM function will yield the result NaN.

Memory Bounds Checking ​

Any attempt by a C math function to access memory outside of the linear memory block reserved for the function when executed in Yellowbrick will result in:

ERROR:  memory out of bounds

Configuring WASM Function Memory ​

The amount of memory allocated per WASM function can be set using the configuration variable wasm_memory_kib. Acceptable values can range from 128 KiB to 2048 KiB:

set wasm_memory_kib to 1024;

The default value is 512 KiB.

WARNING

Note that every thread and every instance of WASM_RUNNER on a compute node will allocate wasm_memory_kib of memory per query. Reduce the value of wasm_memory_kib if the resources used by queries running WASM modules are excessive.