> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-86180b7b.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Documentación sobre funciones definidas por el usuario (UDFs)
# Funciones definidas por el usuario (UDFs)
export const ExperimentalBadge = () => {
return ;
};
export const CloudNotSupportedBadge = () => {
return
Not supported in ClickHouse Cloud
;
};
export const PrivatePreviewBadge = () => {
return
{'Private preview in ClickHouse Cloud'}
;
};
# UDFs Funciones definidas por el usuario
ClickHouse admite varios tipos de funciones definidas por el usuario (UDFs):
* [Executable UDFs](#executable-user-defined-functions) inician un programa o script externo (Python, Bash, etc.) y envían bloques de datos a través de STDIN / STDOUT. Úselas para integrar código o herramientas existentes sin recompilar ClickHouse. Tienen una mayor sobrecarga por llamada en comparación con las opciones dentro del proceso y son más adecuadas para lógica más pesada o cuando se requiere un entorno de ejecución diferente.
* [SQL UDFs](#sql-user-defined-functions) se definen con `CREATE FUNCTION` únicamente en SQL. Se insertan o expanden en el plan de consulta (sin cambiar de proceso), lo que las hace ligeras e ideales para reutilizar lógica de expresiones o simplificar columnas calculadas complejas.
* [Experimental WebAssembly UDFs](#webassembly-user-defined-functions) ejecutan código compilado en WebAssembly dentro de un entorno aislado en el proceso del servidor. Ofrecen una menor sobrecarga por llamada que los ejecutables externos, con mejor aislamiento que las extensiones nativas, lo que las hace adecuadas para algoritmos personalizados escritos en lenguajes que pueden compilarse a WASM (p. ej., C/C++/Rust).
## Funciones ejecutables definidas por el usuario
Esta funcionalidad está disponible en vista previa privada en ClickHouse Cloud.
Póngase en contacto con soporte de ClickHouse en [https://clickhouse.cloud/support](https://clickhouse.cloud/support) para obtener acceso.
ClickHouse puede invocar cualquier programa ejecutable externo o script para procesar datos.
La configuración de las funciones ejecutables definidas por el usuario puede encontrarse en uno o varios archivos XML.
La ruta de la configuración se especifica en el parámetro [`user_defined_executable_functions_config`](/es/reference/settings/server-settings/settings#user_defined_executable_functions_config).
La configuración de una función contiene las siguientes opciones:
| Parámetro | Descripción | Obligatorio | Valor predeterminado |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------- |
| `name` | Nombre de la función | Sí | - |
| `command` | Nombre del script que se debe ejecutar, o comando si `execute_direct` es false | Sí | - |
| `argument` | Descripción del argumento con el `type` y, opcionalmente, el `name` del argumento. Cada argumento se describe en un ajuste independiente. Es necesario especificar el nombre si los nombres de los argumentos forman parte de la serialización en un formato de función definida por el usuario como [Native](/es/reference/formats/Native) o [JSONEachRow](/es/reference/formats/JSON/JSONEachRow) | Sí | `c` + argument\_number |
| `format` | Un [formato](/es/reference/formats) en el que se pasan los argumentos al comando. Se espera que la salida del comando también use el mismo formato | Sí | - |
| `return_type` | El tipo del valor devuelto | Sí | - |
| `return_name` | Nombre del valor devuelto. Es necesario especificar el nombre de retorno si forma parte de la serialización en un formato de función definida por el usuario como [Native](/es/reference/formats/Native) o [JSONEachRow](/es/reference/formats/JSON/JSONEachRow) | Opcional | `result` |
| `type` | Un tipo ejecutable. Si `type` está establecido en `executable`, se inicia un único comando. Si está establecido en `executable_pool`, se crea un pool de comandos | Sí | - |
| `max_command_execution_time` | Tiempo máximo de ejecución, en segundos, para procesar un bloque de datos. Este ajuste solo es válido para comandos `executable_pool` | Opcional | `10` |
| `command_termination_timeout` | Tiempo, en segundos, durante el cual un comando debe finalizar después de que se cierre su pipe. Transcurrido ese tiempo, se envía `SIGTERM` al proceso que ejecuta el comando | Opcional | `10` |
| `command_read_timeout` | Tiempo de espera para leer datos del stdout del comando, en milisegundos | Opcional | `10000` |
| `command_write_timeout` | Tiempo de espera para escribir datos en el stdin del comando, en milisegundos | Opcional | `10000` |
| `pool_size` | Tamaño del pool de comandos | Opcional | `16` |
| `send_chunk_header` | Controla si se debe enviar el recuento de filas antes de enviar un fragmento de datos al proceso | Opcional | `false` |
| `execute_direct` | Si `execute_direct` = `1`, `command` se buscará dentro de la carpeta user\_scripts especificada por [user\_scripts\_path](/es/reference/settings/server-settings/settings#user_scripts_path). Se pueden especificar argumentos adicionales del script usando espacios en blanco como separador. Ejemplo: `script_name arg1 arg2`. Si `execute_direct` = `0`, `command` se pasa como argumento a `bin/sh -c` | Opcional | `1` |
| `lifetime` | Intervalo de recarga de una función, en segundos. Si está establecido en `0`, la función no se recarga | Opcional | `0` |
| `deterministic` | Si la función es determinista (devuelve el mismo resultado para la misma entrada) | Opcional | `false` |
| `stderr_reaction` | Cómo manejar la salida de stderr del comando. Valores: `none` (ignorar), `log` (registrar inmediatamente todo stderr), `log_first` (registrar los primeros 4 KiB después de finalizar), `log_last` (registrar los últimos 4 KiB después de finalizar), `throw` (lanzar una excepción inmediatamente ante cualquier salida en stderr). Al usar `log_first` o `log_last` con un código de salida distinto de cero, el contenido de stderr se incluye en el mensaje de excepción | Opcional | `log_last` |
| `check_exit_code` | Si es true, ClickHouse comprobará el código de salida del comando. Un código de salida distinto de cero provoca una excepción | Opcional | `true` |
El comando debe leer los argumentos desde `STDIN` y escribir el resultado en `STDOUT`. El comando debe procesar los argumentos de forma iterativa. Es decir, después de procesar un fragmento de argumentos, debe esperar al siguiente fragmento.
## Funciones ejecutables definidas por el usuario
## Ejemplos
### UDF a partir de un script inline
Cree `test_function_sum` manualmente, estableciendo `execute_direct` en `0` mediante una configuración XML o YAML.
Archivo `test_function.xml` (`/etc/clickhouse-server/test_function.xml` con la configuración de rutas predeterminada).
```xml title="/etc/clickhouse-server/test_function.xml" theme={null}
executable
test_function_sum
UInt64
UInt64
lhs
UInt64
rhs
TabSeparated
cd /; clickhouse-local --input-format TabSeparated --output-format TabSeparated --structure 'x UInt64, y UInt64' --query "SELECT x + y FROM table"
0
true
```
Archivo `test_function.yaml` (`/etc/clickhouse-server/test_function.yaml` con la configuración de rutas predeterminada).
```yml title="/etc/clickhouse-server/test_function.yaml" theme={null}
functions:
type: executable
name: test_function_sum
return_type: UInt64
argument:
- type: UInt64
name: lhs
- type: UInt64
name: rhs
format: TabSeparated
command: 'cd /; clickhouse-local --input-format TabSeparated --output-format TabSeparated --structure ''x UInt64, y UInt64'' --query "SELECT x + y FROM table"'
execute_direct: 0
deterministic: true
```
```sql title="Query" theme={null}
SELECT test_function_sum(2, 2);
```
```text title="Result" theme={null}
┌─test_function_sum(2, 2)─┐
│ 4 │
└─────────────────────────┘
```
### UDF a partir de un script de Python
En este ejemplo, creamos una UDF que lee un valor de `STDIN` y lo devuelve como una cadena.
Cree `test_function` mediante una configuración XML o YAML.
Archivo `test_function.xml` (`/etc/clickhouse-server/test_function.xml` con la ruta predeterminada).
```xml title="/etc/clickhouse-server/test_function.xml" theme={null}
executable
test_function_python
String
UInt64
value
TabSeparated
test_function.py
```
Archivo `test_function.yaml` (`/etc/clickhouse-server/test_function.yaml` con la ruta predeterminada).
```yml title="/etc/clickhouse-server/test_function.yaml" theme={null}
functions:
type: executable
name: test_function_python
return_type: String
argument:
- type: UInt64
name: value
format: TabSeparated
command: test_function.py
```
Cree el archivo de script `test_function.py` dentro de la carpeta `user_scripts` (`/var/lib/clickhouse/user_scripts/test_function.py` con la ruta predeterminada).
```python theme={null}
#!/usr/bin/python3
import sys
if __name__ == '__main__':
for line in sys.stdin:
print("Value " + line, end='')
sys.stdout.flush()
```
```sql title="Query" theme={null}
SELECT test_function_python(toUInt64(2));
```
```text title="Result" theme={null}
┌─test_function_python(2)─┐
│ Value 2 │
└─────────────────────────┘
```
### Leer dos valores de `STDIN` y devolver su suma como un objeto JSON
Cree `test_function_sum_json` con argumentos con nombre y el formato [JSONEachRow](/es/reference/formats/JSON/JSONEachRow) mediante configuración XML o YAML.
Archivo `test_function.xml` (`/etc/clickhouse-server/test_function.xml` con la ruta predeterminada).
```xml title="/etc/clickhouse-server/test_function.xml" theme={null}
executable
test_function_sum_json
UInt64
result_name
UInt64
argument_1
UInt64
argument_2
JSONEachRow
test_function_sum_json.py
```
Archivo `test_function.yaml` (`/etc/clickhouse-server/test_function.yaml` con la ruta predeterminada).
```yml title="/etc/clickhouse-server/test_function.yaml" theme={null}
functions:
type: executable
name: test_function_sum_json
return_type: UInt64
return_name: result_name
argument:
- type: UInt64
name: argument_1
- type: UInt64
name: argument_2
format: JSONEachRow
command: test_function_sum_json.py
```
Cree el archivo de script `test_function_sum_json.py` dentro de la carpeta `user_scripts` (`/var/lib/clickhouse/user_scripts/test_function_sum_json.py` con la ruta predeterminada).
```python theme={null}
#!/usr/bin/python3
import sys
import json
if __name__ == '__main__':
for line in sys.stdin:
value = json.loads(line)
first_arg = int(value['argument_1'])
second_arg = int(value['argument_2'])
result = {'result_name': first_arg + second_arg}
print(json.dumps(result), end='\n')
sys.stdout.flush()
```
```sql title="Query" theme={null}
SELECT test_function_sum_json(2, 2);
```
```text title="Result" theme={null}
┌─test_function_sum_json(2, 2)─┐
│ 4 │
└──────────────────────────────┘
```
### Usar parámetros en la opción `command`
Las funciones definidas por el usuario ejecutables pueden aceptar parámetros constantes configurados en la opción `command` (esto solo funciona para funciones definidas por el usuario de tipo `executable`).
También requiere la opción `execute_direct` para garantizar que no exista ninguna vulnerabilidad por expansión de argumentos del shell.
Archivo `test_function_parameter_python.xml` (`/etc/clickhouse-server/test_function_parameter_python.xml` con la ruta predeterminada).
```xml title="/etc/clickhouse-server/test_function_parameter_python.xml" theme={null}
executable
true
test_function_parameter_python
String
UInt64
TabSeparated
test_function_parameter_python.py {test_parameter:UInt64}
```
Archivo `test_function_parameter_python.yaml` (`/etc/clickhouse-server/test_function_parameter_python.yaml` con la ruta predeterminada).
```yml title="/etc/clickhouse-server/test_function_parameter_python.yaml" theme={null}
functions:
type: executable
execute_direct: true
name: test_function_parameter_python
return_type: String
argument:
- type: UInt64
format: TabSeparated
command: test_function_parameter_python.py {test_parameter:UInt64}
```
Cree el archivo de script `test_function_parameter_python.py` dentro de la carpeta `user_scripts` (`/var/lib/clickhouse/user_scripts/test_function_parameter_python.py` con la ruta predeterminada).
```python theme={null}
#!/usr/bin/python3
import sys
if __name__ == "__main__":
for line in sys.stdin:
print("Parameter " + str(sys.argv[1]) + " value " + str(line), end="")
sys.stdout.flush()
```
```sql title="Query" theme={null}
SELECT test_function_parameter_python(1)(2);
```
```text title="Result" theme={null}
┌─test_function_parameter_python(1)(2)─┐
│ Parameter 1 value 2 │
└──────────────────────────────────────┘
```
### UDF desde un script de shell
En este ejemplo, creamos un script de shell que multiplica cada valor por 2.
Archivo `test_function_shell.xml` (`/etc/clickhouse-server/test_function_shell.xml` con la ruta predeterminada).
```xml title="/etc/clickhouse-server/test_function_shell.xml" theme={null}
executable
test_shell
String
UInt8
value
TabSeparated
test_shell.sh
```
Archivo `test_function_shell.yaml` (`/etc/clickhouse-server/test_function_shell.yaml` con la ruta predeterminada).
```yml title="/etc/clickhouse-server/test_function_shell.yaml" theme={null}
functions:
type: executable
name: test_shell
return_type: String
argument:
- type: UInt8
name: value
format: TabSeparated
command: test_shell.sh
```
Cree el archivo de script `test_shell.sh` dentro de la carpeta `user_scripts` (`/var/lib/clickhouse/user_scripts/test_shell.sh` con la ruta predeterminada).
```bash title="/var/lib/clickhouse/user_scripts/test_shell.sh" theme={null}
#!/bin/bash
while read read_data;
do printf "$(expr $read_data \* 2)\n";
done
```
```sql title="Query" theme={null}
SELECT test_shell(number) FROM numbers(10);
```
```text title="Result" theme={null}
┌─test_shell(number)─┐
1. │ 0 │
2. │ 2 │
3. │ 4 │
4. │ 6 │
5. │ 8 │
6. │ 10 │
7. │ 12 │
8. │ 14 │
9. │ 16 │
10. │ 18 │
└────────────────────┘
```
## Manejo de errores
Algunas funciones pueden lanzar una excepción si los datos no son válidos.
En ese caso, la consulta se cancela y se devuelve un mensaje de error al cliente.
En el procesamiento distribuido, cuando se produce una excepción en uno de los servidores, los demás servidores también intentan cancelar la consulta.
## Evaluación de las expresiones de los argumentos
En casi todos los lenguajes de programación, puede que uno de los argumentos no se evalúe para ciertos operadores.
Normalmente, se trata de los operadores `&&`, `||` y `?:`.
En ClickHouse, los argumentos de las funciones (operadores) siempre se evalúan.
Esto se debe a que se evalúan partes enteras de las columnas de una sola vez, en lugar de calcular cada fila por separado.
## Ejecución de funciones para el procesamiento distribuido de consultas
En el procesamiento distribuido de consultas, se realizan en servidores remotos tantas etapas del procesamiento de la consulta como sea posible, y el resto de las etapas (la fusión de resultados intermedios y todo lo posterior) se realiza en el servidor solicitante.
Esto significa que las funciones pueden ejecutarse en distintos servidores.
Por ejemplo, en la consulta `SELECT f(sum(g(x))) FROM distributed_table GROUP BY h(y),`
* si una `distributed_table` tiene al menos dos segmentos, las funciones 'g' y 'h' se ejecutan en servidores remotos, y la función 'f' se ejecuta en el servidor solicitante.
* si una `distributed_table` tiene solo un segmento, todas las funciones 'f', 'g' y 'h' se ejecutan en el servidor de ese segmento.
El resultado de una función normalmente no depende del servidor en el que se ejecute. Sin embargo, a veces esto sí es importante.
Por ejemplo, las funciones que trabajan con diccionarios usan el diccionario que existe en el servidor en el que se están ejecutando.
Otro ejemplo es la función `hostName`, que devuelve el nombre del servidor en el que se está ejecutando, para poder hacer `GROUP BY` por servidores en una consulta `SELECT`.
Si una función de una consulta se ejecuta en el servidor solicitante, pero necesita ejecutarla en servidores remotos, puede envolverla en una función de agregación 'any' o añadirla a una clave de `GROUP BY`.
## Funciones SQL definidas por el usuario
Las funciones personalizadas a partir de expresiones lambda se pueden crear mediante la [sentencia CREATE FUNCTION](/es/reference/statements/create/function). Para eliminar estas funciones, utilice la [sentencia DROP FUNCTION](/es/reference/statements/drop#drop-function).
## Funciones definidas por el usuario de WebAssembly
Las funciones definidas por el usuario (UDFs) de WebAssembly (WASM) permiten ejecutar código personalizado compilado a WebAssembly dentro del proceso del servidor de ClickHouse.
### Inicio rápido
Habilite la compatibilidad experimental con WebAssembly en la configuración de ClickHouse:
```xml theme={null}
true
```
Inserte el módulo WASM compilado en la tabla del sistema:
```sql theme={null}
INSERT INTO system.webassembly_modules (name, code)
SELECT 'my_module', base64Decode('AGFzbQEAAAA...');
```
Cree una función con su módulo WASM:
```sql theme={null}
CREATE FUNCTION my_function
LANGUAGE WASM
ABI ROW_DIRECT
FROM 'my_module'
ARGUMENTS (x UInt32, y UInt32)
RETURNS UInt32;
```
Utilice la función en sus consultas:
```sql theme={null}
SELECT my_function(10, 20);
```
### Más información
Consulta la documentación sobre [funciones definidas por el usuario de WebAssembly](/es/reference/functions/regular-functions/wasm_udf) para más información.
## Contenido relacionado
* [Funciones definidas por el usuario en ClickHouse Cloud](https://clickhouse.com/blog/user-defined-functions-clickhouse-udfs)