SQL UDF와 Executable UDF — 쿼리 안에서 반복 로직을 재사용하는 두 가지 방법
ClickHouse Nullable 타입 및 UDF(SQL/Executable) 공식 문서 종합 (웹 리서치, 2026) — ClickHouse 공식 문서(sql-reference/data-types/nullable, sql-reference/statements/create/function, sql-reference/functions/udf) ClickHouse 공식 문서 CREATE FUNCTION 및 User Defined Functions(UDF)
이 모듈을 다 읽으면
- SQL UDF(CREATE FUNCTION)의 람다식 문법과 제약(재귀 불가 등)을 설명할 수 있다
- Executable UDF가 SQL UDF와 근본적으로 다른 지점(외부 프로그램 호출)을 설명할 수 있다
여러 쿼리에 걸쳐 반복되는 표현식이나, SQL로 표현하기엔 너무 복잡한 로직(외부 언어의 라이브러리가 필요한 경우 등)을 재사용 가능한 함수로 감싸는 두 가지 ClickHouse UDF 메커니즘을 정리한다.
SQL UDF — CREATE FUNCTION으로 람다식을 이름 붙여 재사용
CREATE FUNCTION 이름 AS (매개변수) -> 표현식 문법으로, 파라미터·상수·연산자·다른 함수 호출을 조합한 람다식에 이름을 붙여 재사용할 수 있다 — 예를 들어 반복적으로 쓰는 계산식(linear_equation(x, slope, intercept) 같은)을 한 번 정의해두고 여러 쿼리에서 함수처럼 호출하는 식이다. 제약으로는 함수 이름이 고유해야 하고, 재귀 호출이 불가능하며, 함수 본문에서 쓰는 모든 변수는 반드시 매개변수로 선언돼야 한다.
핵심 포인트
- CREATE FUNCTION 이름 AS (매개변수) -> 표현식 문법으로 람다식에 이름을 붙여 재사용 — 매 쿼리마다 표현식을 다시 쓰지 않아도 됨
- 제약: 이름 유일성 필요, 재귀 호출 불가, 함수 본문의 모든 변수는 매개변수로 선언돼야 함
Executable UDF — 외부 프로그램을 stdin/stdout으로 호출
SQL UDF로는 표현할 수 없는 복잡한 로직(외부 라이브러리, 머신러닝 모델 추론 등)이 필요하면 Executable UDF를 쓴다 — 이는 ClickHouse가 외부 실행 파일이나 스크립트(Python 등)를 호출해 데이터를 처리하게 해주는 방식이다. 핵심 계약은 그 외부 프로그램이 인자를 STDIN으로 읽고 결과를 STDOUT으로 출력해야 하며, 한 번에 모든 데이터를 처리하는 게 아니라 청크 단위로 인자를 받아 처리한 뒤 다음 청크를 기다리는 방식으로 반복 처리해야 한다는 점이다 — 데이터 포맷은 TabSeparated, JSON, Native 등을 지원한다.
핵심 포인트
- Executable UDF는 외부 실행파일/스크립트(Python 등)를 호출 — SQL로 표현 불가능한 복잡한 로직(외부 라이브러리, ML 추론)에 적합
- 외부 프로그램은 STDIN으로 인자를 읽고 STDOUT으로 결과를 출력, 청크 단위로 반복 처리하는 방식이 핵심 계약
설정과 배치 — XML 설정 파일과 user_scripts_path
Executable UDF의 설정은 user_defined_executable_functions_config 파라미터가 가리키는 하나 이상의 XML 파일에 위치하며, 실제 스크립트 파일 자체는 user_scripts_path 설정이 가리키는 디렉터리(기본값 /var/lib/clickhouse/user_scripts)에 둬야 한다 — 즉 함수의 '정의(어떤 이름으로 어떤 스크립트를 어떤 포맷으로 호출할지)'와 '실제 실행 파일'이 각각 다른 위치에 분리돼 관리된다는 점이 SQL UDF(순수하게 CREATE FUNCTION 하나로 끝나는)와 대비되는 운영상의 차이다.
핵심 포인트
- Executable UDF 설정은 XML 파일(user_defined_executable_functions_config)에, 실제 스크립트는 user_scripts_path 디렉터리(기본 /var/lib/clickhouse/user_scripts)에 분리돼 위치
- 정의와 실행파일이 분리 관리된다는 점이 CREATE FUNCTION 하나로 끝나는 SQL UDF와 대비되는 운영상의 차이