> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Документация по пользовательским функциям (UDF)

# Пользовательские функции (UDF)

export const ExperimentalBadge = () => {
  return <div className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            Экспериментальная возможность. <u><a href="/docs/docs/beta-and-experimental-features#experimental-features">Подробнее.</a></u>
        </div>;
};

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            Не поддерживается в ClickHouse Cloud
        </div>;
};

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <Icon />
                <span>Бета</span>
            </a>;
  }
  return <div className="betaBadge">
            <Icon />
            <span>
                Возможность в статусе бета. 
                <u>
                    <a href="/docs/docs/beta-and-experimental-features#beta-features">
                        Подробнее.
                    </a>
                </u>
            </span>
        </div>;
};

ClickHouse поддерживает несколько типов пользовательских функций (UDF):

* [исполняемые пользовательские функции](#executable-user-defined-functions) запускают внешнюю программу или скрипт (Python, Bash и т. д.) и потоково передают им блоки данных через STDIN / STDOUT. Используйте их для интеграции существующего кода или инструментов без перекомпиляции ClickHouse. По сравнению с внутрипроцессными вариантами у них выше накладные расходы на каждый вызов, поэтому они лучше подходят для более сложной логики или случаев, когда нужна другая среда выполнения.
* [пользовательские функции SQL](#sql-user-defined-functions) определяются с помощью `CREATE FUNCTION` исключительно на SQL. Они подставляются/разворачиваются в план запроса (без отдельного процесса), что делает их лёгкими и идеально подходящими для повторного использования логики выражений или упрощения сложных вычисляемых столбцов.
* [Экспериментальные пользовательские функции WebAssembly](#webassembly-user-defined-functions) выполняют код, скомпилированный в WebAssembly, внутри песочницы в процессе сервера. Они обеспечивают меньшие накладные расходы на каждый вызов, чем внешние исполняемые файлы, и лучшую изоляцию, чем нативные расширения, что делает их подходящими для пользовательских алгоритмов, написанных на языках, которые можно компилировать в WASM (например, C/C++/Rust).
* [Экспериментальные исполняемые пользовательские функции на основе драйвера](#driver-based-executable-user-defined-functions) позволяют предоставляемому оператором "драйверу" преобразовывать фрагмент кода, указанный в `CREATE FUNCTION ... ENGINE = DriverName(...) AS '...'`, в исполняемую пользовательскую функцию при создании функции (например, путём компиляции). Они основаны на исполняемых пользовательских функциях и требуют серверной конфигурации драйвера.

<div id="executable-user-defined-functions">
  ## Исполняемые пользовательские функции
</div>

<BetaBadge />

<Note>
  В ClickHouse Cloud исполняемые UDF находятся в публичной бета-версии и создаются через интерфейс консоли Cloud. См. [Пользовательские функции в Cloud](/docs/ru/products/cloud/features/sql-console-features/user-defined-functions), чтобы ознакомиться со специальным процессом для Cloud.
</Note>

ClickHouse может вызывать любую внешнюю исполняемую программу или скрипт для обработки данных.

Конфигурация исполняемых пользовательских функций может находиться в одном или нескольких XML-файлах.
Путь к конфигурации задаётся параметром [`user_defined_executable_functions_config`](/docs/ru/reference/settings/server-settings/settings#user_defined_executable_functions_config).

Конфигурация функции включает следующие настройки:

| Параметр                      | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Обязательно   | Значение по умолчанию  |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ---------------------- |
| `name`                        | Имя функции                                                                                                                                                                                                                                                                                                                                                                                                                                               | Да            | -                      |
| `command`                     | Имя скрипта для выполнения или команда, если `execute_direct` имеет значение false                                                                                                                                                                                                                                                                                                                                                                        | Да            | -                      |
| `argument`                    | Описание аргумента с указанием `type` и необязательного `name`. Каждый аргумент задается отдельной настройкой. Указывать имя необходимо, если имена аргументов входят в сериализацию формата пользовательской функции, такого как [Native](/docs/ru/reference/formats/Native) или [JSONEachRow](/docs/ru/reference/formats/JSON/JSONEachRow)                                                                                                                        | Да            | `c` + argument\_number |
| `format`                      | [Формат](/docs/ru/reference/formats/index), в котором аргументы передаются команде. Ожидается, что вывод команды также будет в этом формате                                                                                                                                                                                                                                                                                                                    | Да            | -                      |
| `return_type`                 | Тип возвращаемого значения                                                                                                                                                                                                                                                                                                                                                                                                                                | Да            | -                      |
| `return_name`                 | Имя возвращаемого значения. Указывать его необходимо, если оно входит в сериализацию формата пользовательской функции, такого как [Native](/docs/ru/reference/formats/Native) или [JSONEachRow](/docs/ru/reference/formats/JSON/JSONEachRow)                                                                                                                                                                                                                        | Необязательно | `result`               |
| `type`                        | Тип executable. Если для `type` задано значение `executable`, запускается одна команда. Если задано значение `executable_pool`, создается пул команд                                                                                                                                                                                                                                                                                                      | Да            | -                      |
| `max_command_execution_time`  | Максимальное время выполнения обработки блока данных в секундах. Эта настройка применима только к командам `executable_pool`                                                                                                                                                                                                                                                                                                                              | Необязательно | `10`                   |
| `command_termination_timeout` | Время в секундах, в течение которого команда должна завершиться после закрытия ее канала. По истечении этого времени процессу, выполняющему команду, отправляется `SIGTERM`                                                                                                                                                                                                                                                                               | Необязательно | `10`                   |
| `command_read_timeout`        | Тайм-аут чтения данных из stdout команды в миллисекундах                                                                                                                                                                                                                                                                                                                                                                                                  | Необязательно | `10000`                |
| `command_write_timeout`       | Тайм-аут записи данных в stdin команды в миллисекундах                                                                                                                                                                                                                                                                                                                                                                                                    | Необязательно | `10000`                |
| `pool_size`                   | Размер пула команд                                                                                                                                                                                                                                                                                                                                                                                                                                        | Необязательно | `16`                   |
| `send_chunk_header`           | Определяет, нужно ли отправлять количество строк перед передачей фрагмента данных процессу                                                                                                                                                                                                                                                                                                                                                                | Необязательно | `false`                |
| `execute_direct`              | Если `execute_direct` = `1`, `command` будет искаться в каталоге user\_scripts, указанном в [user\_scripts\_path](/docs/ru/reference/settings/server-settings/settings#user_scripts_path). Дополнительные аргументы скрипта можно указать, разделив их пробелами. Пример: `script_name arg1 arg2`. Если `execute_direct` = `0`, `command` передается как аргумент в `bin/sh -c`                                                                                | Необязательно | `1`                    |
| `lifetime`                    | Интервал перезагрузки функции в секундах. Если задано значение `0`, функция не перезагружается                                                                                                                                                                                                                                                                                                                                                            | Необязательно | `0`                    |
| `deterministic`               | Является ли функция детерминированной (возвращает один и тот же результат для одних и тех же входных данных)                                                                                                                                                                                                                                                                                                                                              | Необязательно | `false`                |
| `stderr_reaction`             | Как обрабатывать вывод команды в stderr. Значения: `none` (игнорировать), `log` (сразу записывать весь stderr в лог), `log_first` (записывать в лог первые 4 KiB после завершения), `log_last` (записывать в лог последние 4 KiB после завершения), `throw` (немедленно сгенерировать исключение при любом выводе в stderr). При использовании `log_first` или `log_last` с ненулевым кодом выхода содержимое stderr включается в сообщение об исключении | Необязательно | `log_last`             |
| `check_exit_code`             | Если true, ClickHouse проверяет код завершения команды. Ненулевой код завершения вызывает исключение                                                                                                                                                                                                                                                                                                                                                      | Необязательно | `true`                 |

Команда должна читать аргументы из `STDIN` и выводить результат в `STDOUT`. Команда должна обрабатывать аргументы итеративно. То есть после обработки одного фрагмента аргументов она должна ждать следующий.

<div id="executable-user-defined-functions">
  ## Исполняемые пользовательские функции
</div>

<div id="examples">
  ## Примеры
</div>

<div id="udf-inline">
  ### UDF из встроенного скрипта
</div>

Создайте `test_function_sum`, вручную задав `execute_direct` значение `0`, с помощью конфигурации XML или YAML.

<Tabs>
  <Tab title="XML">
    Файл `test_function.xml` (`/etc/clickhouse-server/test_function.xml` при настройках пути по умолчанию).

    ```xml title="/etc/clickhouse-server/test_function.xml" theme={null}
    <functions>
        <function>
            <type>executable</type>
            <name>test_function_sum</name>
            <return_type>UInt64</return_type>
            <argument>
                <type>UInt64</type>
                <name>lhs</name>
            </argument>
            <argument>
                <type>UInt64</type>
                <name>rhs</name>
            </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>
            <execute_direct>0</execute_direct>
            <deterministic>true</deterministic>
        </function>
    </functions>
    ```
  </Tab>

  <Tab title="YAML">
    Файл `test_function.yaml` (`/etc/clickhouse-server/test_function.yaml` при настройках пути по умолчанию).

    ```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
    ```
  </Tab>
</Tabs>

<br />

```sql title="Query" theme={null}
SELECT test_function_sum(2, 2);
```

```text title="Result" theme={null}
┌─test_function_sum(2, 2)─┐
│                       4 │
└─────────────────────────┘
```

<div id="udf-python">
  ### UDF из скрипта Python
</div>

В этом примере мы создаём UDF, которая считывает значение из `STDIN` и возвращает его в виде строки.

Создайте `test_function`, используя конфигурацию XML или YAML.

<Tabs>
  <Tab title="XML">
    Файл `test_function.xml` (`/etc/clickhouse-server/test_function.xml` при использовании путей по умолчанию).

    ```xml title="/etc/clickhouse-server/test_function.xml" theme={null}
    <functions>
        <function>
            <type>executable</type>
            <name>test_function_python</name>
            <return_type>String</return_type>
            <argument>
                <type>UInt64</type>
                <name>value</name>
            </argument>
            <format>TabSeparated</format>
            <command>test_function.py</command>
        </function>
    </functions>
    ```
  </Tab>

  <Tab title="YAML">
    Файл `test_function.yaml` (`/etc/clickhouse-server/test_function.yaml` при использовании путей по умолчанию).

    ```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
    ```
  </Tab>
</Tabs>

<br />

Создайте файл скрипта `test_function.py` в папке `user_scripts` (`/var/lib/clickhouse/user_scripts/test_function.py` при использовании путей по умолчанию).

```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                 │
└─────────────────────────┘
```

<div id="udf-stdin">
  ### Прочитайте два значения из `STDIN` и верните их сумму в виде объекта JSON
</div>

Создайте `test_function_sum_json` с именованными аргументами и форматом [JSONEachRow](/docs/ru/reference/formats/JSON/JSONEachRow), используя конфигурацию в XML или YAML.

<Tabs>
  <Tab title="XML">
    Файл `test_function.xml` (`/etc/clickhouse-server/test_function.xml` при настройках путей по умолчанию).

    ```xml title="/etc/clickhouse-server/test_function.xml" theme={null}
    <functions>
        <function>
            <type>executable</type>
            <name>test_function_sum_json</name>
            <return_type>UInt64</return_type>
            <return_name>result_name</return_name>
            <argument>
                <type>UInt64</type>
                <name>argument_1</name>
            </argument>
            <argument>
                <type>UInt64</type>
                <name>argument_2</name>
            </argument>
            <format>JSONEachRow</format>
            <command>test_function_sum_json.py</command>
        </function>
    </functions>
    ```
  </Tab>

  <Tab title="YAML">
    Файл `test_function.yaml` (`/etc/clickhouse-server/test_function.yaml` при настройках путей по умолчанию).

    ```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
    ```
  </Tab>
</Tabs>

<br />

Создайте файл скрипта `test_function_sum_json.py` в папке `user_scripts` (`/var/lib/clickhouse/user_scripts/test_function_sum_json.py` при настройках путей по умолчанию).

```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 │
└──────────────────────────────┘
```

<div id="udf-parameters-in-command">
  ### Использование параметров в настройке `command`
</div>

Пользовательские функции типа `executable` могут принимать константные параметры, заданные в настройке `command` (это работает только для пользовательских функций типа `executable`).
Также требуется параметр `execute_direct`, чтобы исключить уязвимость, связанную с подстановкой аргументов командной оболочкой.

<Tabs>
  <Tab title="XML">
    Файл `test_function_parameter_python.xml` (`/etc/clickhouse-server/test_function_parameter_python.xml`, если используются пути по умолчанию).

    ```xml title="/etc/clickhouse-server/test_function_parameter_python.xml" theme={null}
    <functions>
        <function>
            <type>executable</type>
            <execute_direct>true</execute_direct>
            <name>test_function_parameter_python</name>
            <return_type>String</return_type>
            <argument>
                <type>UInt64</type>
            </argument>
            <format>TabSeparated</format>
            <command>test_function_parameter_python.py {test_parameter:UInt64}</command>
        </function>
    </functions>
    ```
  </Tab>

  <Tab title="YAML">
    Файл `test_function_parameter_python.yaml` (`/etc/clickhouse-server/test_function_parameter_python.yaml`, если используются пути по умолчанию).

    ```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}
    ```
  </Tab>
</Tabs>

<br />

Создайте файл скрипта `test_function_parameter_python.py` в каталоге `user_scripts` (`/var/lib/clickhouse/user_scripts/test_function_parameter_python.py`, если используются пути по умолчанию).

```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                  │
└──────────────────────────────────────┘
```

<div id="udf-shell-script">
  ### UDF из shell-скрипта
</div>

В этом примере мы создаём shell-скрипт, который умножает каждое значение на 2.

<Tabs>
  <Tab title="XML">
    Файл `test_function_shell.xml` (`/etc/clickhouse-server/test_function_shell.xml` при пути по умолчанию).

    ```xml title="/etc/clickhouse-server/test_function_shell.xml" theme={null}
    <functions>
        <function>
            <type>executable</type>
            <name>test_shell</name>
            <return_type>String</return_type>
            <argument>
                <type>UInt8</type>
                <name>value</name>
            </argument>
            <format>TabSeparated</format>
            <command>test_shell.sh</command>
        </function>
    </functions>
    ```
  </Tab>

  <Tab title="YAML">
    Файл `test_function_shell.yaml` (`/etc/clickhouse-server/test_function_shell.yaml` при пути по умолчанию).

    ```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
    ```
  </Tab>
</Tabs>

<br />

Создайте файл скрипта `test_shell.sh` в папке `user_scripts` (`/var/lib/clickhouse/user_scripts/test_shell.sh` при пути по умолчанию).

```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                 │
    └────────────────────┘
```

<div id="error-handling">
  ## Обработка ошибок
</div>

Некоторые функции могут сгенерировать исключение, если данные некорректны.
В этом случае запрос отменяется, а клиенту возвращается текст ошибки.
При распределённой обработке, если исключение возникает на одном из серверов, остальные серверы также пытаются прервать запрос.

<div id="evaluation-of-argument-expressions">
  ## Вычисление выражений аргументов
</div>

Почти во всех языках программирования для некоторых операторов один из аргументов может не вычисляться.
Обычно это операторы `&&`, `||` и `?:`.
В ClickHouse аргументы функций (операторов) вычисляются всегда.
Это связано с тем, что вычисляются сразу целые части столбцов, а не каждая строка отдельно.

<div id="performing-functions-for-distributed-query-processing">
  ## Выполнение функций при распределённой обработке запросов
</div>

При распределённой обработке запросов на удалённых серверах выполняется как можно больше этапов обработки запроса, а остальные этапы (слияние промежуточных результатов и всё последующее) — на сервере-инициаторе запроса.

Это означает, что функции могут выполняться на разных серверах.
Например, в запросе `SELECT f(sum(g(x))) FROM distributed_table GROUP BY h(y),`

* если `distributed_table` содержит как минимум два сегмента, функции 'g' и 'h' выполняются на удалённых серверах, а функция 'f' — на сервере-инициаторе запроса.
* если `distributed_table` содержит только один сегмент, все функции 'f', 'g' и 'h' выполняются на сервере этого сегмента.

Результат функции обычно не зависит от того, на каком сервере она выполняется. Однако иногда это важно.
Например, функции, работающие со словарями, используют словарь, доступный на том сервере, где они выполняются.
Ещё один пример — функция `hostName`, которая возвращает имя сервера, на котором она выполняется, чтобы можно было использовать `GROUP BY` по серверам в запросе `SELECT`.

Если функция в запросе выполняется на сервере-инициаторе запроса, но её нужно выполнить на удалённых серверах, можно обернуть её в агрегатную функцию 'any' или добавить в ключ `GROUP BY`.

<div id="sql-user-defined-functions">
  ## Пользовательские функции SQL
</div>

Пользовательские функции на основе лямбда-выражений можно создавать с помощью оператора [CREATE FUNCTION](/docs/ru/reference/statements/create/function). Для удаления этих функций используйте оператор [DROP FUNCTION](/docs/ru/reference/statements/drop#drop-function).

<div id="webassembly-user-defined-functions">
  ## Пользовательские функции WebAssembly
</div>

<CloudNotSupportedBadge />

<ExperimentalBadge />

Пользовательские функции WebAssembly (WASM UDF) позволяют выполнять пользовательский код, скомпилированный в WebAssembly, внутри процесса сервера ClickHouse.

<div id="quick-start">
  ### Быстрый старт
</div>

Включите экспериментальную поддержку WebAssembly в конфигурации ClickHouse:

```xml theme={null}
<clickhouse>
    <allow_experimental_webassembly_udf>true</allow_experimental_webassembly_udf>
</clickhouse>
```

Вставьте скомпилированный модуль WASM в системную таблицу:

```sql theme={null}
INSERT INTO system.webassembly_modules (name, code)
SELECT 'my_module', base64Decode('AGFzbQEAAAA...');
```

Создайте функцию с помощью модуля WASM:

```sql theme={null}
CREATE FUNCTION my_function
LANGUAGE WASM
ABI ROW_DIRECT
FROM 'my_module'
ARGUMENTS (x UInt32, y UInt32)
RETURNS UInt32;
```

Используйте FUNCTION в своих запросах:

```sql theme={null}
SELECT my_function(10, 20);
```

<div id="more-information">
  ### Дополнительная информация
</div>

Подробнее см. в документации [Пользовательские функции WebAssembly](/docs/ru/reference/functions/regular-functions/wasm_udf).

<div id="driver-based-executable-user-defined-functions">
  ## Исполняемые пользовательские функции на базе драйверов
</div>

<CloudNotSupportedBadge />

<ExperimentalBadge />

<Note>
  Это экспериментальная возможность, которая в будущих релизах может измениться с нарушением обратной совместимости. Включите её с помощью настройки сервера [`allow_experimental_executable_udf_drivers`](/docs/ru/reference/settings/server-settings/settings#allow_experimental_executable_udf_drivers).
</Note>

*Драйвер* — это предоставляемый оператором адаптер, который превращает фрагмент пользовательского кода в исполняемую [пользовательскую функцию](#executable-user-defined-functions). Когда функция создаётся с `ENGINE = DriverName(...)`, ClickHouse запускает `create_command` драйвера, передавая ему сигнатуру функции и тело кода; драйвер компилирует тело или иным образом его обрабатывает и выводит конфигурацию исполняемой пользовательской функции, которую ClickHouse затем сохраняет и загружает.

Это позволяет администраторам дать пользователям безопасный и строго ограниченный способ определять функции на произвольном языке (например, на C, компилируемом внутри изолированного контейнера), не предоставляя им доступ к конфигурационным файлам или файловой системе сервера. Набор доступных драйверов полностью контролируется оператором.

<div id="enabling-drivers">
  ### Включение драйверов
</div>

Исполняемые UDF на базе драйверов по умолчанию отключены. Чтобы их включить:

1. Установите экспериментальный флаг в конфигурации сервера:

   ```xml theme={null}
   <clickhouse>
       <allow_experimental_executable_udf_drivers>true</allow_experimental_executable_udf_drivers>
   </clickhouse>
   ```

2. Укажите в `user_defined_executable_function_drivers_config` один или несколько файлов конфигурации драйверов (поддерживаются glob-шаблоны) и при необходимости задайте [`dynamic_user_defined_executable_functions_path`](/docs/ru/reference/settings/server-settings/settings#dynamic_user_defined_executable_functions_path) — каталог, где хранятся сгенерированные конфигурации исполняемых UDF:

   ```xml theme={null}
   <clickhouse>
       <user_defined_executable_function_drivers_config>user_defined_executable_function_drivers_config.d/*_driver.xml</user_defined_executable_function_drivers_config>
       <dynamic_user_defined_executable_functions_path>/var/lib/clickhouse/dynamic_user_defined_executable_functions/</dynamic_user_defined_executable_functions_path>
   </clickhouse>
   ```

Реестр драйверов загружается при запуске сервера и обновляется командой `SYSTEM RELOAD CONFIG`, поэтому драйверы можно добавлять, изменять или удалять без перезапуска сервера.

<div id="driver-configuration">
  ### Конфигурация драйвера
</div>

Драйвер описывается XML- или YAML-файлом с корневым элементом `<driver>`. Поддерживаются следующие поля:

| Поле               | Описание                                                                                                                                                                                | Обязательно |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `name`             | Имя драйвера, используемое в `CREATE FUNCTION ... ENGINE = <name>(...)`.                                                                                                                | Да          |
| `create_command`   | Путь к программе, которая вызывается для создания UDF из фрагмента кода. Относительные пути разрешаются относительно файла конфигурации драйвера.                                       | Да          |
| `drop_command`     | Путь к программе, которая вызывается при удалении функции, основанной на этом драйвере.                                                                                                 | Нет         |
| `engine_arguments` | Объявляет аргументы, допустимые внутри `ENGINE = DriverName(...)`. Каждый дочерний элемент — имя аргумента; дочерний элемент `<required>true</required>` помечает его как обязательный. | Нет         |
| `env`              | Переменные окружения, экспортируемые при вызове команд драйвера.                                                                                                                        | Нет         |

Пример конфигурации драйвера:

```xml theme={null}
<clickhouse>
    <driver>
        <name>DockerC</name>
        <create_command>../user_defined_executable_function_drivers/docker_c_create.sh</create_command>
        <drop_command>../user_defined_executable_function_drivers/docker_c_drop.sh</drop_command>
        <engine_arguments>
            <opt_level><required>false</required></opt_level>
        </engine_arguments>
        <env>
            <CLICKHOUSE_C_DRIVER_MEMORY>256m</CLICKHOUSE_C_DRIVER_MEMORY>
            <CLICKHOUSE_C_DRIVER_CPUS>1.0</CLICKHOUSE_C_DRIVER_CPUS>
        </env>
    </driver>
</clickhouse>
```

<div id="driver-invocation-contract">
  #### Контракт вызова драйвера
</div>

При выполнении `CREATE FUNCTION` вызывается `create_command` с заданными переменными `env` и следующими аргументами:

* `--name <function_name>`
* `--return <return_type>` (если указана секция `RETURNS`)
* `--args <signature>` (если указана секция `ARGUMENTS`), где signature — это объявленный список аргументов, например `x UInt8, y DateTime`
* `--<key> <value>` для каждого объявленного аргумента движка, указанного в `ENGINE = DriverName(key = value)`

Тело пользовательского кода (текст после `AS`) передаётся на стандартный ввод команды. Команда должна вывести конфигурацию исполняемой UDF в стандартный вывод. Формат определяется автоматически: вывод, начинающийся с `<`, обрабатывается как XML, иначе — как YAML. Имя функции, заданное в сгенерированной конфигурации, должно совпадать с именем создаваемой функции. Если `create_command` завершается с ненулевым кодом выхода, оператор завершается ошибкой с исключением, включающим код выхода и содержимое стандартного потока ошибок драйвера.

`drop_command`, если он указан, вызывается таким же образом (без тела кода в stdin) при удалении функции.

<div id="creating-a-function-with-a-driver">
  ### Создание FUNCTION
</div>

```sql theme={null}
CREATE [OR REPLACE] FUNCTION [IF NOT EXISTS] name [ON CLUSTER cluster]
    ARGUMENTS (a UInt8, b String) RETURNS UInt64
    ENGINE = DriverName(key1 = 'value1', key2 = 42)
    AS '...code body...'
```

ClickHouse выполняет `create_command` драйвера, записывает сгенерированную конфигурацию в [`dynamic_user_defined_executable_functions_path`](/docs/ru/reference/settings/server-settings/settings#dynamic_user_defined_executable_functions_path), после чего её подхватывает существующий загрузчик исполняемых UDF. После этого функцию можно вызывать как и любую другую функцию.

<div id="dropping-a-function-with-a-driver">
  ### Удаление функции
</div>

```sql theme={null}
DROP FUNCTION [IF EXISTS] name [ON CLUSTER cluster]
```

`DROP FUNCTION` вызывает `drop_command` драйвера (если она задана), удаляет сгенерированную динамическую конфигурацию и отдельный рабочий каталог функции, перезагружает загрузчик исполняемых UDF и удаляет сохранённый запрос.

<div id="driver-persistence-and-restart">
  ### Сохранение и перезапуск
</div>

Исходный запрос сохраняется в виде оператора `ATTACH FUNCTION ...` в каталоге пользовательских SQL-объектов, поэтому функция сохраняется после перезапуска сервера. При запуске сгенерированные конфигурации из [`dynamic_user_defined_executable_functions_path`](/docs/ru/reference/settings/server-settings/settings#dynamic_user_defined_executable_functions_path) загружаются напрямую, без повторного запуска драйвера. Если для сохранённого `ATTACH FUNCTION` нет соответствующей сгенерированной конфигурации (например, если динамический каталог был утерян), драйвер запускается повторно, чтобы создать её заново.

<div id="driver-limitations">
  ### Ограничения
</div>

* Эта возможность экспериментальная и доступна только при включении `allow_experimental_executable_udf_drivers`.
* Исполняемые UDF на базе драйверов не поддерживаются с реплицируемым хранилищем пользовательских функций (`ON CLUSTER` и `<user_defined_zookeeper_path>`), поскольку реплицируется только исходный запрос, а не сгенерированные артефакты.
* `RESTORE` исполняемого UDF на базе драйверов из резервной копии сохраняет запрос, но не запускает драйвер повторно; сгенерированная конфигурация материализуется позже в процессе восстановления при перезапуске.

<div id="example-c-drivers">
  ### Пример драйверов на C
</div>

В дереве исходного кода есть демонстрационные драйверы в `programs/server/user_defined_executable_function_drivers_config.d/`, которые компилируют и выполняют тело функции на C. Это лишь примеры, и **пакеты их не устанавливают**:

* `DockerC` - компилирует и выполняет код внутри изолированных контейнеров Docker (`--network=none --read-only --cap-drop=ALL --security-opt=no-new-privileges`, а также с ограничениями по памяти/CPU/PID), создавая UDF `executable_pool`.
* `GVisorC` - вариант, запускающий скомпилированный бинарный файл в среде выполнения `runsc` от [gVisor](https://gvisor.dev/).
* `UnsafeC` - компилирует и выполняет код напрямую на хосте, без песочницы. Как следует из названия, он не обеспечивает никакой изоляции и предназначен только для доверенных окружений и тестирования.

Эти драйверы-примеры служат отправной точкой; прежде чем открывать к ним доступ недоверенным пользователям, проверьте и при необходимости усильте изоляцию для вашей среды.

<div id="related-content">
  ## См. также
</div>

* [Пользовательские функции в ClickHouse Cloud](https://clickhouse.com/blog/user-defined-functions-clickhouse-udfs)
