Skip to content

Commit 674a23d

Browse files
soyeric128soyeric128
authored
docs: js & wasm udf (#804)
* Update 03-udf.md * Update 03-udf.md * Update 03-udf.md * Update 03-udf.md
1 parent 5fc99dc commit 674a23d

File tree

1 file changed

+98
-6
lines changed

1 file changed

+98
-6
lines changed

‎docs/en/guides/54-query/03-udf.md

Lines changed: 98 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,18 @@ title: User-Defined Function
33
---
44
import IndexOverviewList from '@site/src/components/IndexOverviewList';
55

6-
User-Defined Functions (UDFs) enable you to define your custom operations using anonymous lambda expressions to process data within Databend. Key features of user-defined functions include:
6+
User-Defined Functions (UDFs) offer enhanced flexibility by supporting both anonymous lambda expressions and predefined handlers (JavaScript & WebAssembly) for defining UDFs. These features allow users to create custom operations tailored to their specific data processing needs. Databend UDFs are categorized into the following types:
77

8-
- Customized Data Transformations: UDFs empower you to perform data transformations that may not be achievable through built-in Databend functions alone. This customization is particularly valuable for handling unique data formats or implementing specific business logic.
8+
- [Lambda UDFs](#lambda-udf)
9+
- [Embedded UDFs](#embedded-udfs)
910

10-
- Code Reusability: UDFs can be easily reused across multiple queries, saving time and effort in coding and maintaining data processing logic.
11+
Databend provides a variety of commands to manage UDFs. For details, see [User-Defined Function](/sql/sql-commands/ddl/udf/).
1112

12-
## Managing UDFs
13+
## Lambda UDF
1314

14-
Databend provides a variety of commands to manage UDFs. For details, see [User-Defined Function](/sql/sql-commands/ddl/udf/).
15+
A lambda UDF allows users to define custom operations using anonymous functions (lambda expressions) directly within their queries. These lambda expressions are often concise and can be used to perform specific data transformations or computations that may not be achievable using built-in functions alone.
1516

16-
## Usage Examples
17+
### Usage Examples
1718

1819
This example creates UDFs to extract specific values from JSON data within a table using SQL queries.
1920

@@ -35,4 +36,95 @@ SELECT get_v1(data), get_v2(data) FROM json_table;
3536
+------------+------------+
3637
| 1.5 | 20.5 |
3738
+------------+------------+
39+
```
40+
41+
## Embedded UDFs
42+
43+
Embedded UDFs allow you to embed code written in the following programming languages within SQL:
44+
45+
- [JavaScript](#javascript)
46+
- [WebAssembly](#webassembly)
47+
48+
:::note
49+
If your program content is large, you can compress it and then pass it to the stage. See the [Usage Examples](#usage-examples-2) for WebAssembly.
50+
:::
51+
52+
### JavaScript
53+
54+
A JavaScript UDF allows you to invoke JavaScript code from a SQL query via Databend's built-in handler, enabling seamless integration of JavaScript logic within your SQL queries.
55+
56+
#### Data Type Mappings
57+
58+
The following table shows the type mapping between Databend and JavaScript:
59+
60+
| Databend Type | JS Type |
61+
|-------------------|------------|
62+
| NULL | null |
63+
| BOOLEAN | Boolean |
64+
| TINYINT | Number |
65+
| TINYINT UNSIGNED | Number |
66+
| SMALLINT | Number |
67+
| SMALLINT UNSIGNED | Number |
68+
| INT | Number |
69+
| INT UNSIGNED | Number |
70+
| BIGINT | Number |
71+
| BIGINT UNSIGNED | Number |
72+
| FLOAT | Number |
73+
| DOUBLE | Number |
74+
| STRING | String |
75+
| DATE / TIMESTAMP | Date |
76+
| DECIMAL | BigDecimal |
77+
| BINARY | Uint8Array |
78+
79+
#### Usage Examples
80+
81+
This example defines a JavaScript UDF named "gcd_js" to calculate the greatest common divisor (GCD) of two integers, and applies it within a SQL query:
82+
83+
```sql
84+
CREATE FUNCTION gcd_js (INT, INT) RETURNS BIGINT LANGUAGE javascript HANDLER = 'gcd_js' AS $$
85+
export function gcd_js(a, b) {
86+
while (b != 0) {
87+
let t = b;
88+
b = a % b;
89+
a = t;
90+
}
91+
return a;
92+
}
93+
$$
94+
95+
SELECT
96+
number,
97+
gcd_js((number * 3), (number * 6))
98+
FROM
99+
numbers(5)
100+
WHERE
101+
(number > 0)
102+
ORDER BY 1;
103+
```
104+
105+
### WebAssembly
106+
107+
A WebAssembly UDF allows users to define custom logic or operations using languages that compile to WebAssembly. These UDFs can then be invoked directly within SQL queries to perform specific computations or data transformations.
108+
109+
#### Usage Examples
110+
111+
In this example, the "wasm_gcd" function is created to compute the greatest common divisor (GCD) of two integers. The function is defined using WebAssembly and its implementation resides in the 'test10_udf_wasm_gcd.wasm.zst' binary file.
112+
113+
Prior to its execution, the function implementation undergoes a series of steps. First, it is compiled into a binary file, followed by compression into 'test10_udf_wasm_gcd.wasm.zst'. Finally, the compressed file is uploaded to a stage in advance.
114+
115+
:::note
116+
The function can be implemented in Rust, as demonstrated in the example available at https://github.com/risingwavelabs/arrow-udf/blob/main/arrow-udf-wasm/examples/wasm.rs
117+
:::
118+
119+
```sql
120+
CREATE FUNCTION wasm_gcd (INT, INT) RETURNS INT LANGUAGE wasm HANDLER = 'wasm_gcd(int4,int4)->int4' AS $$@data/udf/test10_udf_wasm_gcd.wasm.zst$$;
121+
122+
SELECT
123+
number,
124+
wasm_gcd((number * 3), (number * 6))
125+
FROM
126+
numbers(5)
127+
WHERE
128+
(number > 0)
129+
ORDER BY 1;
38130
```

0 commit comments

Comments
 (0)