overloads 속성

overloads 속성 (함수)

overloads 속성은 같은 사용자 정의 함수(UDF)에 대해 여러 인자 시그니처(signature)를 정의할 수 있게 해 줘요. 같은 함수명을 서로 다른 입력 타입으로 호출할 수 있고, 웨어하우스가 인자 타입에 따라 올바른 버전을 호출해요.

출처: 문서

본문

💡 알고 계셨나요? dbt v1.12부터 또는 dbt "v1 Latest" 릴리스 트랙에서 사용할 수 있어요.

functions/<filename>.yml

functions:
  - name: <function name>
    arguments:
      - name: <arg name>
        data_type: <string>
    returns:
      data_type: <string>
    overloads:
      - defined_in: <string>       # required, name of the SQL, Python, or JavaScript file
        arguments:                 # optional
          - name: <arg name>       # required if arguments is specified
            data_type: <string>    # required if arguments is specified, warehouse-specific
            description: <markdown_string>
            default_value: <string | boolean | integer> # optional, Snowflake and Postgres only
        returns:                   # optional, inherits from root function if omitted
          data_type: <string>      # required if returns is specified, warehouse-specific
          description: <markdown_string>
      - defined_in: ...            # declare additional overloads

Definition

overloads 속성은 같은 사용자 정의 함수 UDF에 대해 여러 인자 시그니처를 정의할 수 있게 해 줘요. 각 변형마다 별도의 UDF를 만들지 않고도 같은 함수명을 서로 다른 입력 타입으로 호출할 수 있어요. 웨어하우스는 인자 타입에 따라 올바른 버전을 호출해요. overloads는 Snowflake와 Postgres의 SQL UDF, 그리고 Snowflake의 Python·JavaScript UDF에서 지원돼요. 각 오버로드는 함수 본문을 담은 별도 파일을 참조하며, 선택적으로 arguments와 returns를 가질 수 있어요. 모든 오버로드는 하나의 DAG 노드(루트 함수)로 묶이므로 함께 빌드·선택돼요. 재시도 시 dbt는 성공한 오버로드를 건너뛰고 실패한 것만 다시 실행해요.

Behavior

dbt는 개별 실패와 무관하게 모든 오버로드를 실행해서 어떤 오버로드가 성공·실패했는지 전체 그림을 볼 수 있게 해 줘요. 다음 동작이 적용돼요:

어떤 오버로드가 실패하면 dbt는 함수 노드를 PARTIAL_SUCCESS로 표시하고 다운스트림 노드를 건너뛰어요.
dbt retry는 이미 성공한 오버로드를 건너뛰고 이전에 실패한 것만 다시 실행해요.
state:modified는 어떤 오버로드의 함수 본문·인자·반환 타입 변경을 감지하고 루트 함수 노드를 수정된 것으로 표시해요.

Properties

overloads 목록의 각 항목은 다음 속성을 지원해요.

defined_in

오버로드의 함수 본문을 담은 파일 이름(확장자 제외)이에요. 파일은 functions/ 디렉터리에 있어야 해요. 예를 들어 defined_in: null_if_empty_numeric은 SQL UDF라면 functions/null_if_empty_numeric.sql, Python UDF라면 functions/null_if_empty_numeric.py, JavaScript UDF라면 functions/null_if_empty_numeric.js를 참조해요. 각 오버로드는 고유한 파일을 참조해야 해요. 루트 함수의 파일과 모든 defined_in 값은 서로 달라야 해요. dbt는 다음과 같은 경우 파싱 에러를 발생시켜요:

defined_in 값이 루트 함수 자신의 파일과 일치할 때
두 오버로드가 같은 파일을 참조할 때
참조하는 파일이 functions/ 디렉터리에 없을 때

arguments

오버로드의 인자 목록이에요. function arguments와 같은 구조를 따르죠.

returns

오버로드의 반환 타입이에요. returns와 같은 구조를 따르죠. 생략하면 오버로드는 루트 함수의 반환 타입을 상속해요.

Example

SQL

functions/null_if_empty.yml

functions:
  - name: null_if_empty
    arguments:
      - name: val
        data_type: varchar
    returns:
      data_type: varchar
    overloads:
      - defined_in: null_if_empty_numeric
        arguments:
          - name: val
            data_type: numeric
        returns:
          data_type: numeric

각 오버로드 본문에 별도의 SQL 파일을 만들어요. 이 예시에서 기본 함수는 빈 문자열을, 오버로드는 숫자 값을 처리해요. functions/null_if_empty.sql

-- syntax for Snowflake
CASE WHEN val = '' THEN NULL ELSE val END
-- syntax for Postgres
SELECT CASE WHEN val = '' THEN NULL ELSE val END

functions/null_if_empty_numeric.sql

-- syntax for Snowflake
CASE WHEN val = 0 THEN NULL ELSE val END
-- syntax for Postgres
SELECT CASE WHEN val = 0 THEN NULL ELSE val END

Python

functions/null_if_empty.yml

functions:
  - name: null_if_empty
    config:
      runtime_version: "3.11"
      entry_point: main
    arguments:
      - name: val
        data_type: varchar
    returns:
      data_type: varchar
    overloads:
      - defined_in: null_if_empty_numeric
        arguments:
          - name: val
            data_type: numeric
        returns:
          data_type: numeric

각 오버로드 본문에 별도의 Python 파일을 만들어요. functions/null_if_empty.py

def main(val):
    return None if val == '' else val

functions/null_if_empty_numeric.py

def main(val):
    return None if val == 0 else val

JavaScript

functions/null_if_empty.yml

functions:
  - name: null_if_empty
    arguments:
      - name: val
        data_type: varchar
    returns:
      data_type: varchar
    overloads:
      - defined_in: null_if_empty_numeric
        arguments:
          - name: val
            data_type: numeric
        returns:
          data_type: numeric

각 오버로드 본문에 별도의 JavaScript 파일을 만들어요. functions/null_if_empty.js

if (val === '') return null;
return val;

functions/null_if_empty_numeric.js

if (val === 0) return null;
return val;

overloads 속성