Merge pull request #29331 from lehasm/alexey-sm-DOCSUP-15139-document--RELOAD-FUNCTION

DOCSUP-15139: document user defined functions (XML config)

docs/en/sql-reference/functions/index.md

@@ -59,9 +59,68 @@ A lambda function that accepts multiple arguments can also be passed to a higher
 
 For some functions the first argument (the lambda function) can be omitted. In this case, identical mapping is assumed.
 
-## User Defined Functions {#user-defined-functions}
+## SQL User Defined Functions {#user-defined-functions}
+
+Custom functions from lambda expressions can be created using the [CREATE FUNCTION](../statements/create/function.md) statement. To delete these functions use the [DROP FUNCTION](../statements/drop.md#drop-function) statement.
+
+## Executable User Defined Functions {#executable-user-defined-functions}
+ClickHouse can call any external executable program or script to process data. Describe such functions in a [configuration file](../../operations/configuration-files.md) and add the path of that file to the main configuration in `user_defined_executable_functions_config` setting. If a wildcard symbol `*` is used in the path, then all files matching the pattern are loaded. Example:
+``` xml
+<user_defined_executable_functions_config>*_function.xml</user_defined_executable_functions_config>
+```
+User defined function configurations are searched relative to the path specified in the `user_files_path` setting.
+
+A function configuration contains the following settings:
+
+-   `name` - a function name.
+-   `command` - a command or a script to execute.
+-   `argument` - argument description with the `type` of an argument. Each argument is described in a separate setting.
+-   `format` - a [format](../../interfaces/formats.md) in which arguments are passed to the command.
+-   `return_type` - the type of a returned value.
+-   `type` - an executable type. If `type` is set to `executable` then single command is started. If it is set to `executable_pool` then a pool of commands is created.
+-   `max_command_execution_time` - maximum execution time in seconds for processing block of data. This setting is valid for `executable_pool` commands only. Optional. Default value is `10`.
+-   `command_termination_timeout` - time in seconds during which a command should finish after its pipe is closed. After that time `SIGTERM` is sent to the process executing the command. This setting is valid for `executable_pool` commands only. Optional. Default value is `10`.
+-   `pool_size` - the size of a command pool. Optional. Default value is `16`.
+-   `lifetime` - the reload interval of a function in seconds. If it is set to `0` then the function is not reloaded.
+-   `send_chunk_header` - controls whether to send row count before sending a chunk of data to process. Optional. Default value is `false`.
+
+The command must read arguments from `STDIN` and must output the result to `STDOUT`. The command must process arguments iteratively. That is after processing a chunk of arguments it must wait for the next chunk.
+
+**Example**
+Creating `test_function` using XML configuration:
+```
+<functions>
+    <function>
+        <type>executable</type>
+        <name>test_function</name>
+        <return_type>UInt64</return_type>
+        <argument>
+            <type>UInt64</type>
+        </argument>
+        <argument>
+            <type>UInt64</type>
+        </argument>
+        <format>TabSeparated</format>
+        <command>cd /; clickhouse-local --input-format TabSeparated --output-format TabSeparated --structure 'x UInt64, y UInt64' --query "SELECT x + y FROM table"</command>
+        <lifetime>0</lifetime>
+    </function>
+</functions>
+```
+
+Query:
+
+``` sql
+SELECT test_function(toUInt64(2), toUInt64(2));
+```
+
+Result:
+
+``` text
+┌─test_function(toUInt64(2), toUInt64(2))─┐
+│                                       4 │
+└─────────────────────────────────────────┘
+```
 
-Custom functions can be created using the [CREATE FUNCTION](../statements/create/function.md) statement. To delete these functions use the [DROP FUNCTION](../statements/drop.md#drop-function) statement.
 
 ## Error Handling {#error-handling}
 

docs/en/sql-reference/statements/grant.md

@@ -155,6 +155,8 @@ Hierarchy of privileges:
         -   `SYSTEM RELOAD CONFIG`
         -   `SYSTEM RELOAD DICTIONARY`
             -   `SYSTEM RELOAD EMBEDDED DICTIONARIES`
+        -   `SYSTEM RELOAD FUNCTION`
+        -   `SYSTEM RELOAD FUNCTIONS`
     -   `SYSTEM MERGES`
     -   `SYSTEM TTL MERGES`
     -   `SYSTEM FETCHES`

docs/en/sql-reference/statements/system.md

@@ -12,6 +12,8 @@ The list of available `SYSTEM` statements:
 -   [RELOAD DICTIONARY](#query_language-system-reload-dictionary)
 -   [RELOAD MODELS](#query_language-system-reload-models)
 -   [RELOAD MODEL](#query_language-system-reload-model)
+-   [RELOAD FUNCTIONS](#query_language-system-reload-functions)
+-   [RELOAD FUNCTION](#query_language-system-reload-functions)
 -   [DROP DNS CACHE](#query_language-system-drop-dns-cache)
 -   [DROP MARK CACHE](#query_language-system-drop-mark-cache)
 -   [DROP UNCOMPRESSED CACHE](#query_language-system-drop-uncompressed-cache)
@@ -83,6 +85,17 @@ Completely reloads a CatBoost model `model_name` if the configuration was update
 SYSTEM RELOAD MODEL <model_name>
 ```
 
+## RELOAD FUNCTIONS {#query_language-system-reload-functions}
+
+Reloads all registered [executable user defined functions](../functions/index.md#executable-user-defined-functions) or one of them from a configuration file.
+
+**Syntax**
+
+```sql
+RELOAD FUNCTIONS
+RELOAD FUNCTION function_name
+```
+
 ## DROP DNS CACHE {#query_language-system-drop-dns-cache}
 
 Resets ClickHouse’s internal DNS cache. Sometimes (for old ClickHouse versions) it is necessary to use this command when changing the infrastructure (changing the IP address of another ClickHouse server or the server used by dictionaries).

docs/ru/sql-reference/functions/index.md

@@ -58,9 +58,68 @@ str -> str != Referer
 
 Для некоторых функций первый аргумент (лямбда-функция) может отсутствовать. В этом случае подразумевается тождественное отображение.
 
-## Пользовательские функции {#user-defined-functions}
+## Пользовательские функции SQL {#user-defined-functions}
 
-Функции можно создавать с помощью выражения [CREATE FUNCTION](../statements/create/function.md). Для удаления таких функций используется выражение [DROP FUNCTION](../statements/drop.md#drop-function).
+Функции можно создавать из лямбда выражений с помощью [CREATE FUNCTION](../statements/create/function.md). Для удаления таких функций используется выражение [DROP FUNCTION](../statements/drop.md#drop-function).
+
+## Исполняемые пользовательские функции {#executable-user-defined-functions}
+ClickHouse может вызывать внешнюю программу или скрипт для обработки данных. Такие функции описываются в [конфигурационном файле](../../operations/configuration-files.md). Путь к нему должен быть указан в настройке `user_defined_executable_functions_config` в основной конфигурации. В пути можно использовать символ подстановки `*`, тогда будут загружены все файлы, соответствующие шаблону. Пример:
+``` xml
+<user_defined_executable_functions_config>*_function.xml</user_defined_executable_functions_config>
+```
+Файлы с описанием функций ищутся относительно каталога, заданного в настройке `user_files_path`.
+
+Конфигурация функции содержит следующие настройки:
+
+-   `name` - имя функции.
+-   `command` - исполняемая команда или скрипт.
+-   `argument` - описание аргумента, содержащее его тип во вложенной настройке `type`. Каждый аргумент описывается отдельно.
+-   `format` - [формат](../../interfaces/formats.md) передачи аргументов.
+-   `return_type` - тип возвращаемого значения.
+-   `type` - вариант запуска команды. Если задан вариант `executable`, то запускается одна команда. При указании `executable_pool` создается пул команд.
+-   `max_command_execution_time` - максимальное время в секундах, которое отводится на обработку блока данных. Эта настройка применима только для команд с вариантом запуска `executable_pool`. Необязательная настройка. Значение по умолчанию `10`.
+-   `command_termination_timeout` - максимальное время завершения команды в секундах после закрытия конвейера. Если команда не завершается, то процессу отправляется сигнал `SIGTERM`. Эта настройка применима только для команд с вариантом запуска `executable_pool`. Необязательная настройка. Значение по умолчанию `10`.
+-   `pool_size` - размер пула команд. Необязательная настройка. Значение по умолчанию `16`.
+-   `lifetime` - интервал перезагрузки функций в секундах. Если задан `0`, то функция не перезагружается.
+-   `send_chunk_header` - управляет отправкой количества строк перед отправкой блока данных для обработки. Необязательная настройка. Значение по умолчанию `false`.
+
+Команда должна читать аргументы из `STDIN` и выводить результат в `STDOUT`. Обработка должна выполняться в цикле. То есть после обработки группы аргументов команда должна ожидать следующую группу.
+
+**Пример**
+
+XML конфигурация, описывающая функцию `test_function`:
+```
+<functions>
+    <function>
+        <type>executable</type>
+        <name>test_function</name>
+        <return_type>UInt64</return_type>
+        <argument>
+            <type>UInt64</type>
+        </argument>
+        <argument>
+            <type>UInt64</type>
+        </argument>
+        <format>TabSeparated</format>
+        <command>cd /; clickhouse-local --input-format TabSeparated --output-format TabSeparated --structure 'x UInt64, y UInt64' --query "SELECT x + y FROM table"</command>
+        <lifetime>0</lifetime>
+    </function>
+</functions>
+```
+
+Запрос:
+
+``` sql
+SELECT test_function(toUInt64(2), toUInt64(2));
+```
+
+Результат:
+
+``` text
+┌─test_function(toUInt64(2), toUInt64(2))─┐
+│                                       4 │
+└─────────────────────────────────────────┘
+```
 
 ## Обработка ошибок {#obrabotka-oshibok}
 

docs/ru/sql-reference/statements/grant.md

@@ -157,6 +157,8 @@ GRANT SELECT(x,y) ON db.table TO john WITH GRANT OPTION
         - `SYSTEM RELOAD CONFIG`
         - `SYSTEM RELOAD DICTIONARY`
             - `SYSTEM RELOAD EMBEDDED DICTIONARIES`
+        -   `SYSTEM RELOAD FUNCTION`
+        -   `SYSTEM RELOAD FUNCTIONS`
     - `SYSTEM MERGES`
     - `SYSTEM TTL MERGES`
     - `SYSTEM FETCHES`

docs/ru/sql-reference/statements/system.md

@@ -10,6 +10,8 @@ toc_title: SYSTEM
 -   [RELOAD DICTIONARY](#query_language-system-reload-dictionary)
 -   [RELOAD MODELS](#query_language-system-reload-models)
 -   [RELOAD MODEL](#query_language-system-reload-model)
+-   [RELOAD FUNCTIONS](#query_language-system-reload-functions)
+-   [RELOAD FUNCTION](#query_language-system-reload-functions)
 -   [DROP DNS CACHE](#query_language-system-drop-dns-cache)
 -   [DROP MARK CACHE](#query_language-system-drop-mark-cache)
 -   [DROP UNCOMPRESSED CACHE](#query_language-system-drop-uncompressed-cache)
@@ -80,6 +82,17 @@ SYSTEM RELOAD MODELS
 SYSTEM RELOAD MODEL <model_name>
 ```
 
+## RELOAD FUNCTIONS {#query_language-system-reload-functions}
+
+Перезагружает все зарегистрированные [исполняемые пользовательские функции](../functions/index.md#executable-user-defined-functions) или одну из них из файла конфигурации.
+
+**Синтаксис**
+
+```sql
+RELOAD FUNCTIONS
+RELOAD FUNCTION function_name
+```
+
 ## DROP DNS CACHE {#query_language-system-drop-dns-cache}
 
 Сбрасывает внутренний DNS кеш ClickHouse. Иногда (для старых версий ClickHouse) необходимо использовать эту команду при изменении инфраструктуры (смене IP адреса у другого ClickHouse сервера или сервера, используемого словарями).