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

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

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

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

  1. С помощью SQL
  2. С помощью UI и собственного кода (закрытая предварительная версия)

Пользовательские функции 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

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

Private preview in ClickHouse Cloud

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

Примечание

Если вы хотите попробовать эту возможность, обратитесь в службу поддержки, чтобы получить доступ к закрытой предварительной версии.

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

Создайте файл 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

Теперь упакуйте файл в ZIP-архив:

zip is_business_hours.zip main.py

Создайте 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. В меню выберите User-defined functions.
  3. Для UDF isBusinessHours нажмите на три точки в столбце Actions, затем выберите создать новую версию
  4. Загрузите zip-архив с изменённым кодом или измените настройки, затем нажмите создать новую версию

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