UDFs Пользовательские Определенные Функции

Исполняемые Пользовательские Определенные Функции

Private preview in ClickHouse Cloud

примечание

Эта функция поддерживается в частном предварительном просмотре в ClickHouse Cloud. Пожалуйста, свяжитесь с поддержкой ClickHouse по адресу https://clickhouse.cloud/support для получения доступа.

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

Конфигурация исполняемых пользовательских определенных функций может находиться в одном или нескольких xml-файлах. Путь к конфигурации указывается в параметре user_defined_executable_functions_config.

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

• name - имя функции.
• command - имя скрипта для выполнения или команда, если execute_direct равно false.
• argument - описание аргумента с type и необязательным name аргумента. Каждый аргумент описывается в отдельной настройке. Указание имени необходимо, если имена аргументов являются частью сериализации для формата пользовательской функции, такого как Native или JSONEachRow. Значение имени аргумента по умолчанию - c + номер_аргумента.
• format - формат в котором аргументы передаются команде.
• return_type - тип возвращаемого значения.
• return_name - имя возвращаемого значения. Указание имени возврата необходимо, если имя возврата является частью сериализации для формата пользовательской функции, такого как Native или JSONEachRow. Необязательно. Значение по умолчанию — result.
• type - исполняемый тип. Если type установлен на executable, тогда запускается одиночная команда. Если он установлен на executable_pool, тогда создается пул команд.
• max_command_execution_time - максимальное время выполнения в секундах для обработки блока данных. Эта настройка действительна только для команд executable_pool. Необязательно. Значение по умолчанию - 10.
• command_termination_timeout - время в секундах, в течение которого команда должна завершиться после закрытия её канала. После этого времени SIGTERM отправляется процессу, выполняющему команду. Необязательно. Значение по умолчанию - 10.
• command_read_timeout - тайм-аут для чтения данных из стандартного вывода команды в миллисекундах. Значение по умолчанию 10000. Необязательный параметр.
• command_write_timeout - тайм-аут для записи данных в стандартный ввод команды в миллисекундах. Значение по умолчанию 10000. Необязательный параметр.
• pool_size - размер пула команд. Необязательно. Значение по умолчанию - 16.
• send_chunk_header - управляет тем, следует ли отправлять количество строк перед отправкой порции данных для обработки. Необязательно. Значение по умолчанию - false.
• execute_direct - Если execute_direct = 1, тогда command будет искаться внутри папки user_scripts, указанной в user_scripts_path. Дополнительные параметры скрипта могут быть указаны с разделителем пробелом. Пример: script_name arg1 arg2. Если execute_direct = 0, command передается как аргумент для bin/sh -c. Значение по умолчанию - 1. Необязательный параметр.
• lifetime - интервал перезагрузки функции в секундах. Если он установлен на 0, то функция не перезагружается. Значение по умолчанию - 0. Необязательный параметр.

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

Примеры

Встроенный скрипт

Создание test_function_sum с ручным указанием execute_direct на 0 с использованием XML конфигурации. Файл test_function.xml (/etc/clickhouse-server/test_function.xml с настройками по умолчанию).

Запрос:

Результат:

Скрипт на Python

Читает значение из STDIN и возвращает его как строку:

Создание test_function с использованием XML конфигурации. Файл test_function.xml (/etc/clickhouse-server/test_function.xml с настройками по умолчанию).

Файл скрипта внутри папки user_scripts test_function.py (/var/lib/clickhouse/user_scripts/test_function.py с настройками по умолчанию).

Запрос:

Результат:

Читает два значения из STDIN и возвращает их сумму в виде JSON объекта:

Создание test_function_sum_json с именованными аргументами и форматом JSONEachRow с использованием XML конфигурации. Файл test_function.xml (/etc/clickhouse-server/test_function.xml с настройками по умолчанию).

Файл скрипта внутри папки user_scripts test_function_sum_json.py (/var/lib/clickhouse/user_scripts/test_function_sum_json.py с настройками по умолчанию).

Запрос:

Результат:

Используйте параметры в настройке command:

Исполняемые пользовательские определенные функции могут принимать постоянные параметры, настроенные в настройке command (работает только для пользовательских определенных функций с типом executable). Это также требует опции execute_direct (чтобы избежать уязвимостей, связанных с расширением аргументов оболочки). Файл test_function_parameter_python.xml (/etc/clickhouse-server/test_function_parameter_python.xml с настройками по умолчанию).

Файл скрипта внутри папки user_scripts test_function_parameter_python.py (/var/lib/clickhouse/user_scripts/test_function_parameter_python.py с настройками по умолчанию).

Запрос:

Результат:

Скрипт оболочки

Скрипт оболочки, который умножает каждое значение на 2:

Исполняемые пользовательские определенные функции могут использоваться с оболочными скриптами. Файл test_function_shell.xml (/etc/clickhouse-server/test_function_shell.xml с настройками по умолчанию).

Файл скрипта внутри папки user_scripts test_shell.sh (/var/lib/clickhouse/user_scripts/test_shell.sh с настройками по умолчанию).

Запрос:

Результат:

Обработка Ошибок

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

Оценка Выражений Аргументов

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

Выполнение Функций для Распределенной Обработки Запросов

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

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

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

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

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

SQL Пользовательские Определенные Функции

Пользовательские функции из лямбда-выражений могут быть созданы с использованием оператора CREATE FUNCTION. Для удаления этих функций используйте оператор DROP FUNCTION.

Связанный Контент

Пользовательские определенные функции в ClickHouse Cloud