Cloud의 사용자 정의 함수

사용자 정의 함수(UDF)를 사용하면 1,000개가 넘는 기본 제공 FUNCTION만으로는 제공되지 않는 ClickHouse의 기능까지 확장할 수 있습니다.

ClickHouse Cloud에서 사용자 정의 함수를 생성하고 관리하는 방법은 여러 가지입니다:

1. SQL 사용
2. UI와 직접 작성한 코드 사용(공개 베타)
3. Cloud API 사용(베타)
4. Terraform 사용(베타)

SQL UDF는 람다 표현식으로 CREATE FUNCTION SQL 문을 사용해 생성할 수 있습니다.

이 예시에서는 간단한 실행형 사용자 정의 함수 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. 방금 생성한 UDF를 삭제하려면 DROP FUNCTION 명령을 사용할 수 있습니다:

DROP FUNCTION isBusinessHours

이는 다음을 의미합니다:

• 세션 수준 설정(SET 문로 설정)은 UDF 실행 Context로 전달되지 않습니다
• 사용자 프로필 설정은 UDF에 상속되지 않습니다
• 쿼리 수준 설정은 UDF 실행 중에는 적용되지 않습니다

ClickHouse Cloud는 UI를 통해 사용자 정의 함수를 생성할 수 있는 환경을 제공합니다.

이 예시에서는 특정 타임스탬프가 일반적인 업무 시간에 해당하는지 확인하는 동일한 간단한 실행형 사용자 정의 함수 isBusinessHours를 생성합니다. 이전에는 SQL로 이를 생성했지만, 이번에는 Python으로 작성하고 UI를 통해 구성합니다.

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 requirements.txt

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')

zip is_business_hours.zip main.py

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

true    false

UI에서 제공되는 모든 기능은 ClickHouse Cloud API를 통해 프로그래밍 방식으로도 사용할 수 있습니다. UDF 엔드포인트를 사용하면 소스 아카이브 업로드, FUNCTION 및 버전 생성, 서비스 ATTACH, 정리 등 UDF의 전체 수명 주기를 스크립트로 처리할 수 있습니다.

API를 통해 UDF를 생성하고 배포하는 일반적인 워크플로는 다음과 같습니다.

1. 사전 서명된 application/zip 업로드 URL을 받기 위해 업로드 URL을 생성한 다음, 해당 URL로 ZIP 아카이브를 업로드합니다. 각 업로드 ID는 생성 또는 버전 생성 시도에 한 번만 사용할 수 있습니다. 재시도할 때는 새 업로드 URL을 요청하십시오.
2. 업로드한 아카이브로부터 FUNCTION 이름, 런타임, 인수 및 반환 유형을 지정하여 UDF를 생성합니다.
3. UDF를 서비스에 ATTACH합니다. 버전을 생략하면 준비된 최신 버전이 ATTACH됩니다. 서비스가 실행 중이어야 하며, 유휴 상태인 서비스는 먼저 시작할 수 있습니다.

전체 엔드포인트 목록은 다음과 같습니다.

요청 및 응답 스키마는 UDF API 참조를 확인하십시오.

공식 ClickHouse Terraform 프로바이더에는 Infrastructure as Code 방식으로 UDF를 관리할 수 있는 2개의 리소스가 포함되어 있습니다.

• clickhouse_udf는 FUNCTION 자체를 관리합니다. FUNCTION 소스 코드가 포함된 ZIP 아카이브를 사용하며, 아카이브 hash가 변경될 때마다 새 버전을 publish하고 빌드가 완료될 때까지 기다립니다.
• clickhouse_udf_attachment는 UDF 버전을 서비스에 ATTACH합니다. 서비스에는 한 번에 FUNCTION의 버전을 최대 1개만 ATTACH할 수 있습니다. 고정 버전 번호를 지정하거나 clickhouse_udf.<name>.version을 참조하여 서비스를 최신 버전으로 자동 업데이트할 수 있습니다.

예를 들어, 앞선 예시의 isBusinessHours UDF를 Terraform으로 배포하려면 다음과 같이 합니다.

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
}

ATTACH는 준비된 상태인 버전에서만 성공하며, 완료하는 데 몇 분이 걸릴 수 있습니다. 유휴 상태의 서비스는 자동으로 시작됩니다. clickhouse_udf 리소스를 삭제하면 해당 FUNCTION의 모든 버전이 제거되고 모든 서비스에서 분리됩니다.