Перейти к основному содержимому
Перейти к основному содержимому

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

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

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

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

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

UDF в 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;
  1. Выполните следующую команду, чтобы протестировать только что созданную UDF:
SELECT isBusinessHours('2026-03-20 10:00:00'::DateTime), isBusinessHours('2026-03-20 23:00:00'::DateTime);

Должен получиться следующий результат:

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

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

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

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

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

Beta feature. Learn more.

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

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

Создайте файл 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, перечислив в нём эти зависимости. Например:

requests>=2.28.0
numpy>=1.23.0
Примечание

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

Зависимости пакета и локальные файлы​

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

zip is_business_hours.zip main.py requirements.txt

Вы можете использовать os.path.dirname(os.path.abspath(__file__)) в своём Python-коде, чтобы ссылаться на базовый каталог локального пути bundled. Это возвращает абсолютный путь к каталогу, в котором находится 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-архив содержит только обычные файлы и каталоги — загрузки с символическими ссылками не пройдут проверку.

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

  1. На главной странице консоли Cloud нажмите название своей организации в меню в левом нижнем углу.
  2. Выберите в меню Пользовательские функции.
  3. На странице пользовательских функций нажмите Set up a UDF. Справа на экране откроется панель настройки.
  4. Введите имя функции. В этом примере используйте isBusinessHours.
  5. Выберите тип функции: Executable pool или Executable:
    • Executable pool: Поддерживается пул постоянных процессов, и для операций чтения из пула берётся процесс.
    • Executable: Скрипт выполняется при каждом запросе.
  6. В этом примере используйте настройки по умолчанию. Полный список параметров настройки см. в разделе Executable user-defined functions.
  7. Нажмите Browse File, чтобы загрузить файл .zip, созданный в начале этого руководства.
  8. Добавьте новый аргумент. В этом примере добавьте аргумент timestamp с типом DateTime.
  9. Выберите тип возвращаемого значения. В этом примере выберите Bool.
  10. Нажмите Create UDF. В диалоговом окне отображается текущий статус сборки.
    • Если возникнут какие-либо проблемы, статус изменится на error.
    • В противном случае статус меняется с building на provisioning. Чтобы завершить provisioning, ваш сервис должен быть активен. Если сервис бездействует, нажмите Wake Up Service на панели UDF details рядом с именем сервиса.
    • После завершения статус изменится на deployed.

Протестируйте свой 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

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

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

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