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

1. С помощью SQL
2. С помощью консоли и собственного кода
3. С помощью Cloud API (бета)
4. С помощью Terraform (бета)

​

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

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

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

​

Исполняемые пользовательские функции

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

requests>=2.28.0
numpy>=1.23.0

zip is_business_hours.zip main.py

zip -r ../is_business_hours.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')

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

true    false

​

Нативная среда выполнения (скомпилированные бинарные файлы)

my-udf.zip
├── amd64/
│   ├── main            # linux/amd64 executable
│   └── my_data.json    # optional data files
└── arm64/
    ├── main            # linux/arm64 executable
    └── my_data.json

rustup target add x86_64-unknown-linux-musl aarch64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl
cargo build --release --target aarch64-unknown-linux-musl

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o amd64/main .
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o arm64/main .

​

Справочник по конфигурации

​

Форматы и заголовки фрагментов

​

Сетевой доступ

​

Лимит памяти

​

Детерминированные функции и кэш запросов

​

Перезапуск сервиса

​

Мониторинг

SELECT
    event_time,
    query_duration_ms,
    ProfileEvents['ExecutableUserDefinedFunctionInvocations']                              AS udf_invocations,
    round(ProfileEvents['ExecutableUserDefinedFunctionElapsedMicroseconds'] / 1e6, 2)     AS udf_wall_s,
    round(ProfileEvents['ExecutableUserDefinedFunctionPoolWaitMicroseconds'] / 1e6, 2)    AS udf_pool_wait_s,
    round((ProfileEvents['ExecutableUserDefinedFunctionUserTimeMicroseconds']
         + ProfileEvents['ExecutableUserDefinedFunctionSystemTimeMicroseconds']) / 1e6, 2) AS udf_cpu_s
FROM system.query_log
WHERE type = 'QueryFinish'
  AND ProfileEvents['ExecutableUserDefinedFunctionInvocations'] > 0
ORDER BY event_time DESC
LIMIT 20;

​

Рекомендации по производительности

​

Устранение неполадок

Code: 754. DB::Exception: User defined function 'isBusinessHours' failed. Command: '...', Arguments: [...]. Original error: ... Child process was exited with return code 1: Stderr: <...>

• Запрос зависает, а затем завершается с ошибкой по тайм-ауту: процесс буферизовал вывод в строково-ориентированном формате без Send chunk header. Включите этот параметр и сбрасывайте вывод после каждого фрагмента, а при использовании формата Native — после каждого блока.
• Код возврата 1 и трассировка стека MemoryError (Python): превышен лимит памяти. Увеличьте значение лимита памяти или сократите потребление памяти каждым процессом.
• Периодические сбои при типе executable под высокой нагрузкой: переключитесь на executable_pool.
• Статус сборки — error: в корне zip-архива отсутствует main.py (Python) или amd64/main и arm64/main (Native), либо архив содержит символические ссылки.
• Не удаётся создать функцию: её имя совпадает с именем встроенной функции.

​

Управление пользовательскими функциями (UDF) через Cloud API

1. Создайте URL для загрузки, чтобы получить предварительно подписанный URL для загрузки application/zip, а затем загрузите по нему ZIP-архив. Каждый ID загрузки можно использовать только для одной попытки создания UDF или её версии; при повторной попытке запросите новый URL для загрузки.
2. Создайте UDF из загруженного архива, указав имя функции, среду выполнения, аргументы и возвращаемый тип.
3. Подключите UDF к сервису. Если версия не указана, подключается последняя готовая версия. Сервис должен быть запущен; бездействующие сервисы можно предварительно активировать.

​

Управление пользовательскими функциями (UDF) с помощью Terraform

• clickhouse_udf управляет самой функцией. Он принимает ZIP-архив с исходным кодом функции и публикует новую версию при изменении хеша архива, дожидаясь завершения сборки.
• clickhouse_udf_attachment подключает версию UDF к сервису. К сервису можно одновременно подключить не более одной версии функции. Можно закрепить конкретный номер версии или сослаться на clickhouse_udf.<name>.version, чтобы автоматически обновлять сервисы до последней версии.

resource "clickhouse_udf" "is_business_hours" {
  function_name = "isBusinessHours"
  runtime       = "python3.11"
  type          = "executable_pool"
  return_type   = "Bool"

  arguments = [
    { name = "timestamp", type = "DateTime" },
  ]

  source_archive_path = "${path.module}/is_business_hours.zip"
  source_archive_hash = filebase64sha256("${path.module}/is_business_hours.zip")
}

resource "clickhouse_udf_attachment" "production" {
  function_name = clickhouse_udf.is_business_hours.function_name
  service_id    = var.service_id
  version       = clickhouse_udf.is_business_hours.version
}

resource "clickhouse_udf_attachment" "dev" {
  function_name = clickhouse_udf.is_business_hours.function_name
  service_id    = var.dev_service_id
  version       = clickhouse_udf.is_business_hours.version
}

resource "clickhouse_udf_attachment" "prod" {
  function_name = clickhouse_udf.is_business_hours.function_name
  service_id    = var.prod_service_id
  version       = var.prod_udf_version
}