Cloud의 사용자 정의 FUNCTION

사용자 정의 FUNCTION(UDF)를 사용하면 1,000개가 넘는 기본 제공 FUNCTION만으로는 제공되지 않는 ClickHouse의 기능까지 확장할 수 있습니다. ClickHouse Cloud에서 사용자 정의 FUNCTION을 생성하고 관리하는 방법은 여러 가지입니다:

SQL 사용
UI와 직접 작성한 코드 사용(공개 베타)
Cloud API 사용(베타)
Terraform 사용(알파)

SQL 사용자 정의 함수

SQL UDF는 람다 표현식으로 CREATE FUNCTION SQL 문을 사용해 생성할 수 있습니다. 이 예시에서는 간단한 실행형 사용자 정의 함수 isBusinessHours를 생성합니다. 이 함수는 특정 타임스탬프가 일반적인 업무 시간 내에 해당하는지 확인하고, 해당하면 true를, 그렇지 않으면 false를 반환합니다.

Cloud Console에 로그인한 다음 SQL 콘솔을 엽니다
다음 SQL 쿼리를 작성하여 isBusinessHours 함수를 생성합니다:

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

새로 생성한 UDF를 테스트하려면 아래 명령을 실행하세요:

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

다음과 같은 결과가 반환됩니다:

1   0

방금 생성한 UDF를 삭제하려면 DROP FUNCTION 명령을 사용할 수 있습니다:

DROP FUNCTION isBusinessHours

중요ClickHouse Cloud의 UDF는 사용자 수준 설정을 상속하지 않습니다. UDF는 기본 시스템 설정으로 실행됩니다.

이는 다음을 의미합니다:

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

UI를 통해 생성한 사용자 정의 함수

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

Python 스크립트에서 서드파티 패키지를 import하는 경우, 해당 패키지를 requirements.txt 파일에 나열하면 ClickHouse Cloud가 이를 설치합니다. ZIP에 의존성을 직접 번들할 수도 있지만, 이 경우 두 CPU 아키텍처 모두에 대한 캐시된 패키지를 포함해야 하므로 requirements.txt를 사용하는 편이 더 간단합니다. 예시는 다음과 같습니다:

requests>=2.28.0
numpy>=1.23.0

ClickHouse Cloud는 다음 단계에서 UI를 통해 업로드할 zip 파일에 main.py가 포함되어 있다고 가정합니다. 파일 이름을 다르게 지정하면 오류가 발생합니다.

번들 종속성 및 로컬 파일

종속성 패키지와 추가 로컬 파일(예: wheel 파일, 설정 파일, 데이터 파일)을 포함하려면 main.py 및 requirements.txt와 같은 디렉터리에 배치하십시오. ZIP 아카이브를 만들 때는 모든 파일을 포함하십시오:

zip is_business_hours.zip main.py requirements.txt

Python 코드에서 os.path.dirname(os.path.abspath(__file__))를 사용하면 로컬에 번들된 기본 디렉터리 경로를 참조할 수 있습니다. 이 값은 ZIP 아카이브 내에서 main.py가 위치한 디렉터리의 절대 경로를 반환하므로, 함께 번들된 다른 파일에도 접근할 수 있습니다:

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 번들에는 일반 파일과 디렉터리만 포함되도록 하십시오 — 심볼릭 링크가 포함된 업로드는 유효성 검사에 실패합니다.

UI를 통해 UDF 만들기

Cloud Console 홈 페이지에서 왼쪽 하단 메뉴의 조직 이름을 클릭합니다.
메뉴에서 사용자 정의 함수를 선택합니다.
사용자 정의 함수 페이지에서 UDF 설정을 클릭합니다. 화면 오른쪽에 구성 패널이 열립니다.
함수 이름을 입력합니다. 이 예시에서는 isBusinessHours를 사용합니다.
함수 유형으로 실행형 풀 또는 실행형 중 하나를 선택합니다:
- 실행형 풀: 지속적으로 유지되는 프로세스 풀이 관리되며, 읽기 시 풀에서 프로세스를 가져와 사용합니다.
- 실행형: 모든 쿼리마다 스크립트가 실행됩니다.
이 예시에서는 기본 설정을 사용합니다. 전체 구성 매개변수 목록은 Executable user-defined functions를 참조하십시오.
파일 찾아보기를 클릭하여 이 튜토리얼 시작 부분에서 만든 .zip 파일을 업로드합니다.
새 인수를 추가합니다. 이 예시에서는 유형이 DateTime인 인수 timestamp를 추가합니다.
반환 유형을 선택합니다. 이 예시에서는 Bool을 선택합니다.
UDF 만들기를 클릭합니다. 현재 빌드 상태를 보여주는 대화 상자가 표시됩니다.
- 문제가 있으면 상태가 오류로 변경됩니다.
- 그렇지 않으면 상태가 빌드 중에서 프로비저닝 중으로 진행됩니다. 프로비저닝을 완료하려면 서비스가 실행 중이어야 합니다. 서비스가 유휴 상태이면 서비스 이름 옆의 UDF 세부 정보 패널에서 서비스 깨우기를 클릭합니다.
- 완료되면 상태가 배포됨으로 변경됩니다。

UDF를 테스트해 보세요

페이지 왼쪽 상단의 Settings - return to your service view를 클릭하여 SQL 콘솔의 홈 페이지로 돌아가세요
왼쪽 메뉴에서 SQL 콘솔을 클릭하세요
다음 쿼리를 작성하세요:

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

다음과 같은 결과가 표시됩니다:

true    false

새 버전 만들기

UDF의 코드를 변경하려면 새 버전을 만드십시오. Edit 패널은 UDF가 할당된 서비스를 관리하는 용도로만 사용되며, 여기에서 파일을 업로드해도 배포된 코드가 교체되지는 않습니다.

Cloud Console 홈페이지에서 왼쪽 하단 메뉴의 조직 이름을 클릭합니다.
메뉴에서 사용자 정의 함수를 선택합니다.
isBusinessHours UDF의 Actions 아래에 있는 점 3개를 선택한 다음 새 버전 만들기를 클릭합니다.
수정된 코드가 포함된 zip 파일을 업로드하거나 설정을 변경한 다음 새 버전 만들기를 클릭합니다.

이제 UI를 통해 첫 번째 사용자 정의 함수를 성공적으로 추가하고, 해당 함수가 실행되는 것을 확인했으며, 필요할 경우 새 버전을 만드는 방법도 확인했습니다.

Cloud API를 사용하여 UDF 관리

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

이 엔드포인트는 베타이며 API 계약은 변경될 수 있습니다.

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

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

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

엔드포인트	설명
UDF 업로드 URL 생성	org 범위의 사전 서명된 `application/zip` 업로드 URL을 생성합니다
UDF 생성	업로드된 아카이브로부터 새 UDF를 생성합니다
UDF 목록	organization에 있는 각 UDF의 최신 버전을 반환합니다
UDF 가져오기	UDF의 최신 버전을 반환합니다
UDF 삭제	UDF의 모든 버전을 삭제하고 모든 서비스에서 분리합니다
UDF 버전 생성	소스 아카이브를 사용하여 버전을 할당하고 UDF 빌드를 시작합니다
UDF 버전 목록	UDF의 모든 버전을 반환합니다
UDF 버전 삭제	어떤 서비스에도 ATTACH되지 않은 UDF 버전을 삭제합니다
UDF를 서비스에 ATTACH	필요한 경우 현재 버전을 교체하여 UDF 버전 하나를 서비스에 ATTACH합니다
UDF ATTACH 목록	UDF의 현재 서비스 ATTACH 정보를 반환합니다
UDF ATTACH 가져오기	UDF가 특정 서비스에 현재 ATTACH된 상태를 반환합니다
서비스에서 UDF 분리	서비스에서 UDF를 분리합니다

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

Terraform으로 UDF 관리

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

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

이 리소스는 프로바이더 버전 3.24.0 이상에서 사용할 수 있습니다. 알파 상태이므로 향후 프로바이더 버전에서 동작이 변경될 수 있습니다.

예를 들어, 앞선 예시의 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 resource를 삭제하면 해당 FUNCTION의 모든 버전이 제거되고 모든 서비스에서 분리됩니다.

ClickHouse Cloud

Bring Your Own Cloud

ClickHouse Private

SQL 사용자 정의 함수

UI를 통해 생성한 사용자 정의 함수

Cloud API를 사용하여 UDF 관리

Terraform으로 UDF 관리

​SQL 사용자 정의 함수

​UI를 통해 생성한 사용자 정의 함수

​Cloud API를 사용하여 UDF 관리

​Terraform으로 UDF 관리

SQL 사용자 정의 함수

UI를 통해 생성한 사용자 정의 함수

Cloud API를 사용하여 UDF 관리

Terraform으로 UDF 관리