- Executable UDFs 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 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 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).
- Experimental driver-based executable UDFs permiten que un “driver” proporcionado por el operador convierta, en el momento de crear la función, un fragmento de código proporcionado en
CREATE FUNCTION ... ENGINE = DriverName(...) AS '...'en una UDF ejecutable (por ejemplo, compilándolo). Se basan en las UDFs ejecutables y requieren configuración del driver del lado del servidor.
Funciones ejecutables definidas por el usuario
En ClickHouse Cloud, las UDF ejecutables están en beta pública y se crean a través de la UI de la consola de Cloud. Consulte Funciones definidas por el usuario en Cloud para ver el flujo de trabajo específico de Cloud.
user_defined_executable_functions_config.
La configuración de una función contiene las siguientes opciones:
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
test_function_sum manualmente, estableciendo execute_direct en 0 mediante una configuración XML o YAML.
- XML
- YAML
Archivo
test_function.xml (/etc/clickhouse-server/test_function.xml con la configuración de rutas predeterminada)./etc/clickhouse-server/test_function.xml
Query
Result
UDF a partir de un script de Python
STDIN y lo devuelve como una cadena.
Cree test_function mediante una configuración XML o YAML.
- XML
- YAML
Archivo
test_function.xml (/etc/clickhouse-server/test_function.xml con la ruta predeterminada)./etc/clickhouse-server/test_function.xml
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).
Query
Result
Leer dos valores de STDIN y devolver su suma como un objeto JSON
test_function_sum_json con argumentos con nombre y el formato JSONEachRow mediante configuración XML o YAML.
- XML
- YAML
Archivo
test_function.xml (/etc/clickhouse-server/test_function.xml con la ruta predeterminada)./etc/clickhouse-server/test_function.xml
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).
Query
Result
Usar parámetros en la opción command
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.
- XML
- YAML
Archivo
test_function_parameter_python.xml (/etc/clickhouse-server/test_function_parameter_python.xml con la ruta predeterminada)./etc/clickhouse-server/test_function_parameter_python.xml
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).
Query
Result
UDF desde un script de shell
- XML
- YAML
Archivo
test_function_shell.xml (/etc/clickhouse-server/test_function_shell.xml con la ruta predeterminada)./etc/clickhouse-server/test_function_shell.xml
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).
/var/lib/clickhouse/user_scripts/test_shell.sh
Query
Result
Manejo de errores
Evaluación de las expresiones de los argumentos
&&, || 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
SELECT f(sum(g(x))) FROM distributed_table GROUP BY h(y),
- si una
distributed_tabletiene 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_tabletiene solo un segmento, todas las funciones ‘f’, ‘g’ y ‘h’ se ejecutan en el servidor de ese segmento.
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
Funciones definidas por el usuario de WebAssembly
Inicio rápido
Más información
Funciones definidas por el usuario ejecutables basadas en drivers
Esta es una funcionalidad experimental que puede cambiar de maneras incompatibles con versiones anteriores en versiones futuras. Habilítela con la configuración del servidor
allow_experimental_executable_udf_drivers.ENGINE = DriverName(...), ClickHouse ejecuta el create_command del driver y le pasa la firma de la función y el cuerpo del código; el driver compila o procesa de otro modo el cuerpo e imprime una configuración de UDF ejecutable, que ClickHouse luego almacena y carga.
Esto permite a los administradores ofrecer a los usuarios una forma segura y restringida de definir funciones en un lenguaje arbitrario (por ejemplo, C compilado dentro de un contenedor aislado) sin darles acceso a los archivos de configuración ni al sistema de archivos del servidor. El conjunto de drivers disponibles está controlado por completo por el operador.
Habilitar drivers
-
Active la opción Experimental en la configuración del servidor:
-
Haga que
user_defined_executable_function_drivers_configapunte a uno o varios archivos de configuración de drivers (se admite un patrón glob) y, opcionalmente, establezcadynamic_user_defined_executable_functions_path, el directorio donde se almacenan las configuraciones generadas de UDF ejecutables:
SYSTEM RELOAD CONFIG, por lo que se pueden agregar, modificar o eliminar drivers sin reiniciar el servidor.
Configuración del driver
<driver> de nivel superior. Se admiten los siguientes campos:
Ejemplo de configuración del driver:
Contrato de invocación del driver
CREATE FUNCTION, se invoca create_command con las variables env configuradas y los siguientes argumentos:
--name <function_name>--return <return_type>(si hay una cláusulaRETURNS)--args <signature>(si hay una cláusulaARGUMENTS), donde la firma es la lista de argumentos declarados; por ejemplo,x UInt8, y DateTime--<key> <value>para cada argumento de engine declarado proporcionado enENGINE = DriverName(key = value)
AS) se envía a la entrada estándar del comando. El comando debe imprimir la configuración de una UDF ejecutable en su salida estándar. El formato se detecta automáticamente: la salida que comienza con < se trata como XML; de lo contrario, como YAML. El nombre de la función definido en la configuración generada debe coincidir con el nombre que se está creando. Si create_command finaliza con un código distinto de cero, la instrucción falla con una excepción que incluye el código de salida y el error estándar del driver.
drop_command, cuando está presente, se invoca de la misma manera (sin un cuerpo de código en stdin) cuando se elimina la función.
Crear una función
create_command del driver, escribe la configuración generada en dynamic_user_defined_executable_functions_path y el cargador existente de UDF ejecutables la detecta. Luego, la función puede llamarse como cualquier otra función.
Eliminar una función
DROP FUNCTION invoca el drop_command del driver (si existe), elimina la configuración dinámica generada y el directorio de trabajo de cada función, recarga el cargador de UDF ejecutables y elimina la consulta persistida.
Persistencia y reinicio
ATTACH FUNCTION ... en el directorio de objetos SQL definidos por el usuario, por lo que la función sobrevive a un reinicio del servidor. Al iniciarse, las configuraciones generadas en dynamic_user_defined_executable_functions_path se cargan directamente sin volver a ejecutar el driver. Si una sentencia ATTACH FUNCTION almacenada no tiene una configuración generada correspondiente (por ejemplo, si se perdió el directorio dinámico), el driver se vuelve a ejecutar para recrearla.
Limitaciones
- La funcionalidad es experimental y está habilitada mediante
allow_experimental_executable_udf_drivers. - Las funciones basadas en drivers no son compatibles con el almacenamiento replicado de funciones definidas por el usuario (
ON CLUSTERy<user_defined_zookeeper_path>), porque solo se replica la consulta original, no los artefactos generados. - La operación
RESTOREde una función basada en drivers incluida en una copia de seguridad conserva la consulta, pero no vuelve a ejecutar el driver; la configuración generada se materializa más adelante durante la recuperación tras el reinicio.
Ejemplo de drivers de C
programs/server/user_defined_executable_function_drivers_config.d/ que compilan y ejecutan el cuerpo de una función en C. Son ejemplos y no se instalan mediante paquetes:
DockerC- compila y ejecuta el código dentro de contenedores de Docker aislados (--network=none --read-only --cap-drop=ALL --security-opt=no-new-privileges, además de límites de memoria/CPU/PID), y produce una UDFexecutable_pool.GVisorC- una variante que ejecuta el binario compilado con el runtimerunscde gVisor.UnsafeC- compila y ejecuta el código directamente en el host sin aislamiento. Como indica el nombre, no proporciona ningún aislamiento y está pensado solo para entornos de confianza y pruebas.