Пользовательские функции в Cloud

Добавьте в Cloud собственные исполняемые функции Python

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

В ClickHouse Cloud есть два способа создать пользовательские функции:

1. С помощью SQL
2. С помощью интерфейса и собственного кода (публичная бета)

​

Пользовательские функции SQL

Пользовательские функции SQL можно создавать с помощью оператора CREATE FUNCTION на основе лямбда-выражения.

В этом примере мы создадим простую исполняемую пользовательскую функцию isBusinessHours. Функция будет проверять, попадает ли указанная временная метка в стандартные рабочие часы, и возвращать true, если да, и false — если нет.

1. Войдите в Cloud Console и откройте консоль SQL
2. Напишите следующий SQL-запрос, чтобы создать функцию isBusinessHours:

CREATE FUNCTION isBusinessHours AS (ts) ->
toDayOfWeek(ts) BETWEEN 1 AND 5
AND toHour(ts) BETWEEN 9 AND 17;

3. Чтобы протестировать только что созданную UDF, выполните следующую команду:

SELECT isBusinessHours('2026-03-20 10:00:00'::DateTime), isBusinessHours('2026-03-20 23:00:00'::DateTime);

Вы должны получить такой результат:

1   0

4. Вы можете использовать команду DROP FUNCTION, чтобы удалить только что созданную UDF:

DROP FUNCTION isBusinessHours

Важно

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

Это означает:

• Настройки уровня сеанса (заданные через оператор SET) не передаются в контекст выполнения UDF
• Настройки профиля пользователя не наследуются UDF
• Настройки уровня запроса не применяются при выполнении UDF

​

Пользовательские функции, созданные через интерфейс

ClickHouse Cloud позволяет создавать пользовательские функции через интерфейс.

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

1. ​

   Создайте Python-файл

   Создайте новый файл main.py на локальной машине:

   cat > main.py << 'EOF'
   import sys
   from datetime import datetime
   
   for line in sys.stdin:
       ts = datetime.fromisoformat(line.strip())
       result = 1 if (0 <= ts.weekday() <= 4 and 9 <= ts.hour <= 17) else 0
       print(result)
       sys.stdout.flush()
   EOF
   

   Если ваш Python-скрипт импортирует сторонние пакеты, перечислите их в файле requirements.txt, и ClickHouse Cloud установит их автоматически. Вместо этого можно добавить зависимости прямо в ZIP-архив, но тогда потребуется включить кэшированные пакеты для обеих архитектур CPU, поэтому вариант с requirements.txt проще. Например:

   requests>=2.28.0
   numpy>=1.23.0
   

   ClickHouse Cloud ожидает, что в zip-архиве, который вы загрузите через интерфейс на следующем шаге, будет файл main.py. Если назвать файл иначе, возникнет ошибка.

2. ​

   Пакеты зависимостей и локальные файлы

   Чтобы включить пакеты зависимостей и любые дополнительные локальные файлы (например, wheel-файлы, файлы конфигурации или файлы данных), поместите их в тот же каталог, где находятся main.py и requirements.txt. При создании ZIP-архива включите в него все файлы:

   zip is_business_hours.zip main.py requirements.txt
   

   В коде Python вы можете сослаться на базовый каталог локального упакованного path, используя os.path.dirname(os.path.abspath(__file__)). Это возвращает абсолютный path к каталогу, в котором находится ваш main.py внутри ZIP-архива, что позволяет получать доступ к другим упакованным файлам:

   import os
   
   # Get the base directory of the bundled files
   base_dir = os.path.dirname(os.path.abspath(__file__))
   config_path = os.path.join(base_dir, 'config.json')
   

   Это полезно, когда вам нужно:

   • Получить доступ к файлам конфигурации, включённым в ваш UDF
   • Загрузить wheel-пакеты для пользовательских зависимостей
   • Указать дополнительные скрипты или файлы данных

   Теперь сожмите файл в ZIP-архив:

   zip is_business_hours.zip main.py
   

   Символические ссылки запрещены

   ClickHouse Cloud отклоняет архивы UDF, содержащие символические ссылки. Убедитесь, что ваш ZIP-архив содержит только обычные файлы и каталоги — загрузка архивов с символическими ссылками не пройдет проверку.

3. ​

   Создание UDF через интерфейс

   1. На главной странице Cloud Console нажмите имя вашей организации в меню в левом нижнем углу.
   2. Выберите в меню Пользовательские функции.
   3. На странице пользовательских функций нажмите Настроить UDF. Справа откроется панель конфигурации.
   4. Введите имя функции. В этом примере используйте isBusinessHours.
   5. Выберите тип функции: Executable pool или Executable:
      • Executable pool: Поддерживается пул постоянных процессов, и для операций чтения процесс берётся из этого пула.
      • Executable: Скрипт запускается для каждого запроса.
   6. В этом примере используйте настройки по умолчанию. Полный список параметров конфигурации см. в разделе Исполняемые пользовательские функции.
   7. Нажмите Выбрать файл, чтобы загрузить файл .zip, созданный в начале этого руководства.
   8. Добавьте новый аргумент. В этом примере добавьте аргумент timestamp с типом DateTime.
   9. Выберите тип возвращаемого значения. В этом примере выберите Bool.
   10. Нажмите Создать UDF. В диалоговом окне отобразится текущий статус сборки.
       • Если возникнут какие-либо проблемы, статус изменится на ошибка.
       • В противном случае статус последовательно изменится с сборка на подготовка. Для завершения подготовки ваш сервис должен быть активен. Если сервис находится в состоянии бездействия, нажмите Пробудить сервис на панели Сведения о UDF рядом с именем сервиса.
       • После завершения статус изменится на развернуто.
4. ​

   Протестируйте свою UDF

   1. вернитесь на главную страницу SQL Console, нажав в левом верхнем углу страницы Settings - return to your service view
   2. нажмите SQL Console в меню слева
   3. введите следующий запрос:

   SELECT isBusinessHours('2026-03-20 10:00:00'::DateTime), isBusinessHours('2026-03-20 23:00:00'::DateTime);
   

   Вы увидите результат:

   true    false
   
5. ​

   Создайте новую версию

   Чтобы изменить код UDF, создайте новую версию. Панель Edit управляет только тем, каким сервисам назначена UDF; загрузка файла в этой панели не заменит уже развернутый код.

   1. На главной странице Cloud Console нажмите имя своей организации в меню в левом нижнем углу.
   2. В меню выберите Пользовательские функции.
   3. Для UDF isBusinessHours нажмите на три точки в разделе Действия, затем выберите Создать новую версию
   4. Загрузите ZIP-архив с измененным кодом или измените настройки, затем нажмите Создать новую версию

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