유틸리티 함수

유틸리티 함수 (Utility Functions)

이 페이지는 특정 함수 유형으로 분류하기 어렵지만 널리 유용한 함수들을 모아 둔 거예요. 스칼라 유틸리티 함수와 테이블 함수를 살펴볼게요.

출처: 문서

본문

스칼라 유틸리티 함수 (Scalar Utility Functions)

아래 함수들은 특정 함수 유형으로 분류하기 어렵고 널리 유용해요.

이름	설명
`alias(column)`	열의 이름을 반환해요.
`can_cast_implicitly(source_value, target_value)`	소스 값의 타입에서 대상 값으로 암시적으로 캐스팅할 수 있는지 여부.
`checkpoint(database)`	(선택) database의 WAL을 트랜잭션을 방해하지 않고 파일과 동기화해요.
`coalesce(expr, ...)`	`NULL`이 아닌 값으로 평가되는 첫 번째 표현식을 반환해요. 1개 이상의 파라미터를 받아요. 각 표현식은 열, 리터럴 값, 함수 결과 등이 될 수 있어요.
`constant_or_null(arg1, arg2)`	`arg2`가 `NULL`이면 `NULL`, 아니면 `arg1`을 반환해요.
`count_if(x)`	집계 함수; `x`가 `true` 또는 0이 아닌 숫자면 행이 1을, 아니면 0을 기여해요.
`create_sort_key(parameters...)`	입력 파라미터와 정렬 한정자 세트를 기반으로 이진 비교 가능한 정렬 키를 구성해요.
`current_catalog()`	현재 활성 카탈로그의 이름을 반환해요. 기본은 memory.
`current_database()`	현재 활성 데이터베이스의 이름을 반환해요.
`current_query()`	현재 쿼리를 문자열로 반환해요.
`current_schema()`	현재 활성 스키마의 이름을 반환해요. 기본은 main.
`current_schemas(boolean)`	스키마 목록을 반환해요. 암시적 스키마를 포함하려면 `true` 파라미터를 전달해요.
`current_setting('setting_name')`	구성 설정의 현재 값을 반환해요.
`currval('sequence_name')`	시퀀스의 현재 값을 반환해요. `currval` 호출 전에 `nextval`을 최소 한 번 호출해야 해요.
`error(message)`	주어진 오류 `message`를 던져요.
`equi_width_bins(min, max, bincount, nice := false)`	구간 `[min, max]`를 `bin_count`개의 동일 크기 부분 구간으로 나눈 분할의 상한 경계를 반환해요(예: `histogram`과 함께 사용). `nice = true`면 `min`, `max`, `bincount`를 더 보기 좋은 결과를 위해 조정할 수 있어요.
`force_checkpoint(database)`	(선택) database의 WAL을 트랜잭션을 방해하며 파일과 동기화해요.
`gen_random_uuid()`	`eeccb8c5-9943-b2bb-bb5e-222f4e14b687` 같은 무작위 UUID를 반환해요.
`getenv(var)`	환경 변수 `var`의 값을 반환해요. 커맨드라인 클라이언트에서만 사용 가능해요.
`getvariable('variable_name')`	`variable_name`이라는 SQL 변수의 값을 반환하거나, 설정되지 않았으면 `NULL`을 반환해요.
`hash(value)`	`value`의 해시를 담은 `UBIGINT`를 반환해요. 사용되는 해시 함수는 DuckDB 버전에 따라 바뀔 수 있어요.
`icu_sort_key(string, collator)`	특정 로케일에 따라 특수 문자를 정렬하는 데 쓰는 대리 정렬 키. Collator 파라미터는 선택적이에요. ICU 익스텐션이 설치된 경우에만 사용 가능해요.
`if(a, b, c)`	삼항 조건 연산자.
`ifnull(expr, other)`	두 인자 버전의 coalesce.
`is_histogram_other_bin(arg)`	`arg`가 `histogram_exact` 함수 목적상 데이터 타입의 "캐치올 요소"일 때 `true`를 반환해요. 이는 `histogram` 함수 목적상 데이터 타입의 "가장 오른쪽 경계"와 동일해요.
`md5(string)`	`string`의 MD5 해시를 `VARCHAR`로 반환해요.
`md5_number(string)`	`string`의 MD5 해시를 `UHUGEINT`로 반환해요.
`md5_number_lower(string)`	`string`의 MD5 해시 하위 64비트 세그먼트를 `UBIGINT`로 반환해요.
`md5_number_upper(string)`	`string`의 MD5 해시 상위 64비트 세그먼트를 `UBIGINT`로 반환해요.
`nextval('sequence_name')`	시퀀스의 다음 값을 반환해요.
`nullif(a, b)`	`a = b`면 `NULL`, 아니면 `a`를 반환해요. `CASE WHEN a = b THEN NULL ELSE a END`와 동일.
`parse_formatted_bytes(string)`	사람이 읽을 수 있는 바이트 크기 문자열(예: `'16 KiB'`)을 `UBIGINT` 바이트 수로 파싱해요. 잘못된 입력이면 오류를 던져요.
`pg_typeof(expression)`	표현식 결과의 데이터 타입 이름을 소문자로 반환해요. PostgreSQL 호환용.
`query(``query_string``)`	`query_string`에 정의된 쿼리를 파싱하고 실행하는 테이블 함수. 상수 문자열만 허용돼요. 경고: 이 함수는 임의의 쿼리를 호출할 수 있어 데이터베이스 상태를 변경할 수 있어요.
`query_table(``tbl_name``)`	`tbl_name`에 주어진 테이블을 반환하는 테이블 함수.
`query_table(``tbl_names``, [``by_name``])`	`tbl_names`에 주어진 테이블들의 합집합을 반환하는 테이블 함수. 선택적 `by_name` 파라미터가 `true`면 `UNION ALL BY NAME` 시맨틱을 사용해요.
`read_blob(source)`	`source`(파일 이름, 파일 이름 목록, 또는 glob 패턴)의 내용을 `BLOB`으로 반환해요. 자세한 내용은 `read_blob` 가이드를 참고해요.
`read_text(source)`	`source`(파일 이름, 파일 이름 목록, 또는 glob 패턴)의 내용을 `VARCHAR`로 반환해요. 파일 내용은 먼저 유효한 UTF-8인지 검증돼요. `read_text`가 유효하지 않은 UTF-8 파일을 읽으려 하면 대신 `read_blob`을 사용하라는 오류가 던져져요. 자세한 내용은 `read_text` 가이드를 참고해요.
`replace_type(value, source_type, target_type)`	`value`에서 타입이 `source_type`인 모든 필드를 `target_type`으로 재귀적으로 캐스팅해요. 타입은 `NULL::VARCHAR`처럼 `NULL` 타입 값으로 제공돼요.
`sha1(string)`	`string`의 SHA-1 해시가 담긴 `VARCHAR`를 반환해요.
`sha256(string)`	`string`의 SHA-256 해시가 담긴 `VARCHAR`를 반환해요.
`sleep_ms(milliseconds)`	지정한 밀리초만큼 실행을 일시 중지해요. `NULL`을 반환해요.
`stats(expression)`	표현식에 대한 통계가 담긴 문자열을 반환해요. 표현식은 열, 상수, SQL 표현식일 수 있어요.
`txid_current()`	현재 트랜잭션의 식별자인 `BIGINT` 값을 반환해요. 현재 트랜잭션에 값이 없으면 새로 할당해요.
`typeof(expression)`	표현식 결과의 데이터 타입 이름을 반환해요.
`uuid()`	`eeccb8c5-9943-b2bb-bb5e-222f4e14b687` 같은 무작위 UUID(UUIDv4)를 반환해요.
`uuidv4()`	`eeccb8c5-9943-b2bb-bb5e-222f4e14b687` 같은 무작위 UUID(UUIDv4)를 반환해요.
`uuidv7()`	`81964ebe-00b1-7e1d-b0f9-43c29b6fb8f5` 같은 무작위 UUIDv7을 반환해요.
`uuid_extract_timestamp(uuidv7)`	UUIDv7 값에서 `TIMESTAMP WITH TIME ZONE`을 추출해요.
`uuid_extract_version(uuid)`	UUID 버전(`4` 또는 `7`)을 추출해요.
`version()`	현재 활성 DuckDB 버전을 이 형식으로 반환해요.

`alias(column)`

| 설명 | 열의 이름을 반환해요. | | 예시 | alias(column1) | | 결과 | column1 |

`can_cast_implicitly(source_value, target_value)`

| 설명 | 소스 값의 타입에서 대상 값으로 암시적으로 캐스팅할 수 있는지 여부. | | 예시 | can_cast_implicitly(1::BIGINT, 1::SMALLINT) | | 결과 | false |

`checkpoint(database)`

| 설명 | (선택) database의 WAL을 트랜잭션을 방해하지 않고 파일과 동기화해요. | | 예시 | checkpoint(my_db) | | 결과 | 성공 Boolean |

`coalesce(expr, ...)`

| 설명 | NULL이 아닌 값으로 평가되는 첫 번째 표현식을 반환해요. 1개 이상의 파라미터를 받아요. 각 표현식은 열, 리터럴 값, 함수 결과 등이 될 수 있어요. | | 예시 | coalesce(NULL, NULL, 'default_string') | | 결과 | default_string |

`constant_or_null(arg1, arg2)`

| 설명 | arg2가 NULL이면 NULL, 아니면 arg1을 반환해요. | | 예시 | constant_or_null(42, NULL) | | 결과 | NULL |

`count_if(x)`

| 설명 | 집계 함수; x가 true 또는 0이 아닌 숫자면 행이 1을, 아니면 0을 기여해요. | | 예시 | count_if(42) | | 결과 | 1 |

`create_sort_key(parameters...)`

| 설명 | 입력 파라미터와 정렬 한정자 세트를 기반으로 이진 비교 가능한 정렬 키를 구성해요. | | 예시 | create_sort_key('abc', 'ASC NULLS FIRST'); | | 결과 | \x02bcd\x00 |

`current_catalog()`

| 설명 | 현재 활성 카탈로그의 이름을 반환해요. 기본은 memory. | | 예시 | current_catalog() | | 결과 | memory |

`current_database()`

| 설명 | 현재 활성 데이터베이스의 이름을 반환해요. | | 예시 | current_database() | | 결과 | memory |

`current_query()`

| 설명 | 현재 쿼리를 문자열로 반환해요. | | 예시 | current_query() | | 결과 | SELECT current_query(); |

`current_schema()`

| 설명 | 현재 활성 스키마의 이름을 반환해요. 기본은 main. | | 예시 | current_schema() | | 결과 | main |

`current_schemas(boolean)`

| 설명 | 스키마 목록을 반환해요. 암시적 스키마를 포함하려면 true 파라미터를 전달해요. | | 예시 | current_schemas(true) | | 결과 | ['temp', 'main', 'pg_catalog'] |

`current_setting('setting_name')`

| 설명 | 구성 설정의 현재 값을 반환해요. | | 예시 | current_setting('access_mode') | | 결과 | automatic |

`currval('sequence_name')`

| 설명 | 시퀀스의 현재 값을 반환해요. currval 호출 전에 nextval을 최소 한 번 호출해야 해요. | | 예시 | currval('my_sequence_name') | | 결과 | 1 |

`error(message)`

| 설명 | 주어진 오류 message를 던져요. | | 예시 | error('access_mode') |

`equi_width_bins(min, max, bincount, nice := false)`

| 설명 | 구간 [min, max]를 bin_count개의 동일 크기 부분 구간으로 나눈 분할의 상한 경계를 반환해요(예: histogram과 함께 사용). nice = true면 min, max, bincount를 더 보기 좋은 결과를 위해 조정할 수 있어요. | | 예시 | equi_width_bins(0.1, 2.7, 4, true) | | 결과 | [0.5, 1.0, 1.5, 2.0, 2.5, 3.0] |

`force_checkpoint(database)`

| 설명 | (선택) database의 WAL을 트랜잭션을 방해하며 파일과 동기화해요. | | 예시 | force_checkpoint(my_db) | | 결과 | 성공 Boolean |

`gen_random_uuid()`

| 설명 | eeccb8c5-9943-b2bb-bb5e-222f4e14b687 같은 무작위 UUID(UUIDv4)를 반환해요. | | 예시 | gen_random_uuid() | | 결과 | 다양함 |

`getenv(var)`

| 설명 | 환경 변수 var의 값을 반환해요. 커맨드라인 클라이언트에서만 사용 가능해요. | | 예시 | getenv('HOME') | | 결과 | /path/to/user/home |

`getvariable('variable_name')`

| 설명 | variable_name이라는 SQL 변수의 값을 반환하거나, 설정되지 않았으면 NULL을 반환해요. 자세한 내용은 SET VARIABLE 문을 참고해요. | | 예시 | getvariable('my_var') | | 결과 | 다양함 |

`hash(value)`

| 설명 | value의 해시를 담은 UBIGINT를 반환해요. 사용되는 해시 함수는 DuckDB 버전에 따라 바뀔 수 있어요. | | 예시 | hash('🦆') | | 결과 | 2595805878642663834 |

`icu_sort_key(string, collator)`

| 설명 | 특정 로케일에 따라 특수 문자를 정렬하는 데 쓰는 대리 정렬 키. Collator 파라미터는 선택적이에요. ICU 익스텐션이 설치된 경우에만 사용 가능해요. | | 예시 | icu_sort_key('ö', 'DE') | | 결과 | 460145960106 |

`if(a, b, c)`

| 설명 | 삼항 조건 연산자; a면 b를, 아니면 c를 반환해요. CASE WHEN a THEN b ELSE c END와 동일. | | 예시 | if(2 > 1, 3, 4) | | 결과 | 3 |

`ifnull(expr, other)`

| 설명 | 두 인자 버전의 coalesce. | | 예시 | ifnull(NULL, 'default_string') | | 결과 | default_string |

`is_histogram_other_bin(arg)`

| 설명 | arg가 histogram_exact 함수 목적상 데이터 타입의 "캐치올 요소"일 때 true를 반환해요. 이는 histogram 함수 목적상 데이터 타입의 "가장 오른쪽 경계"와 동일해요. | | 예시 | is_histogram_other_bin('') | | 결과 | true |

`md5(string)`

| 설명 | string의 MD5 해시를 VARCHAR로 반환해요. | | 예시 | md5('abc') | | 결과 | 900150983cd24fb0d6963f7d28e17f72 |

`md5_number(string)`

| 설명 | string의 MD5 해시를 UHUGEINT로 반환해요. | | 예시 | md5_number('abc') | | 결과 | 152195979970564155685860391459828531600 |

`md5_number_lower(string)`

| 설명 | string의 MD5 해시 하위 8바이트를 UBIGINT로 반환해요. | | 예시 | md5_number_lower('abc') | | 결과 | 8250560606382298838 |

`md5_number_upper(string)`

| 설명 | string의 MD5 해시 상위 8바이트를 UBIGINT로 반환해요. | | 예시 | md5_number_upper('abc') | | 결과 | 12704604231530709392 |

`nextval('sequence_name')`

| 설명 | 시퀀스의 다음 값을 반환해요. | | 예시 | nextval('my_sequence_name') | | 결과 | 2 |

`nullif(a, b)`

| 설명 | a = b면 NULL, 아니면 a를 반환해요. CASE WHEN a = b THEN NULL ELSE a END와 동일. | | 예시 | nullif(1+1, 2) | | 결과 | NULL |

`parse_formatted_bytes(string)`

| 설명 | 사람이 읽을 수 있는 바이트 크기 문자열(예: '16 KiB')을 UBIGINT 바이트 수로 파싱해요. 잘못된 입력이면 오류를 던져요. | | 예시 | parse_formatted_bytes('1.5 GiB') | | 결과 | 1610612736 |

`pg_typeof(expression)`

| 설명 | 표현식 결과의 데이터 타입 이름을 소문자로 반환해요. PostgreSQL 호환용. | | 예시 | pg_typeof('abc') | | 결과 | varchar |

`query(query_string)`

| 설명 | query_string에 정의된 쿼리를 파싱하고 실행하는 테이블 함수. 상수 문자열만 허용돼요. 경고: 이 함수는 임의의 쿼리를 호출할 수 있어 데이터베이스 상태를 변경할 수 있어요. | | 예시 | query('SELECT 42 AS x') | | 결과 | 42 |

`query_table(tbl_name)`

| 설명 | tbl_name에 주어진 테이블을 반환하는 테이블 함수. | | 예시 | query_table('t1') | | 결과 | (t1의 행들) |

`query_table(tbl_names, [by_name])`

| 설명 | tbl_names에 주어진 테이블들의 합집합을 반환하는 테이블 함수. 선택적 by_name 파라미터가 true면 UNION ALL BY NAME 시맨틱을 사용해요. | | 예시 | query_table(['t1', 't2']) | | 결과 | (두 테이블의 합집합) |

`read_blob(source)`

| 설명 | source(파일 이름, 파일 이름 목록, 또는 glob 패턴)의 내용을 BLOB으로 반환해요. 자세한 내용은 read_blob 가이드를 참고해요. | | 예시 | read_blob('hello.bin') | | 결과 | hello\x0A |

`read_text(source)`

| 설명 | source(파일 이름, 파일 이름 목록, 또는 glob 패턴)의 내용을 VARCHAR로 반환해요. 파일 내용은 먼저 유효한 UTF-8인지 검증돼요. read_text가 유효하지 않은 UTF-8 파일을 읽으려 하면 대신 read_blob을 사용하라는 오류가 던져져요. 자세한 내용은 read_text 가이드를 참고해요. | | 예시 | read_text('hello.txt') | | 결과 | hello\n |

`replace_type(value, source_type, target_type)`

| 설명 | value에서 타입이 source_type인 모든 필드를 target_type으로 재귀적으로 캐스팅해요. 소스·대상 타입은 NULL::VARCHAR처럼 NULL 타입 값으로 제공돼요. 깊게 중첩된 값(예: STRUCT나 LIST)의 필드 타입을 한 번에 변환할 때 유용해요. | | 예시 | replace_type([{'a': '42'}], NULL::VARCHAR, NULL::INTEGER) | | 결과 | [{'a': 42}] |

`sha1(string)`

| 설명 | string의 SHA-1 해시가 담긴 VARCHAR를 반환해요. | | 예시 | sha1('🦆') | | 결과 | 949bf843dc338be348fb9525d1eb535d31241d76 |

`sha256(string)`

| 설명 | string의 SHA-256 해시가 담긴 VARCHAR를 반환해요. | | 예시 | sha256('🦆') | | 결과 | d7a5c5e0d1d94c32218539e7e47d4ba9c3c7b77d61332fb60d633dde89e473fb |

`sleep_ms(milliseconds)`

| 설명 | 지정한 밀리초만큼 실행을 일시 중지해요. NULL을 반환해요. | | 예시 | sleep_ms(500) | | 결과 | NULL |

`stats(expression)`

| 설명 | 표현식에 대한 통계가 담긴 문자열을 반환해요. 표현식은 열, 상수, SQL 표현식일 수 있어요. | | 예시 | stats(5) | | 결과 | '[Min: 5, Max: 5][Has Null: false]' |

`txid_current()`

| 설명 | 현재 트랜잭션의 식별자인 BIGINT 값을 반환해요. 현재 트랜잭션에 값이 없으면 새로 할당해요. | | 예시 | txid_current() | | 결과 | 다양함 |

`typeof(expression)`

| 설명 | 표현식 결과의 데이터 타입 이름을 반환해요. | | 예시 | typeof('abc') | | 결과 | VARCHAR |

`uuid()`

| 설명 | eeccb8c5-9943-b2bb-bb5e-222f4e14b687 같은 무작위 UUID(UUIDv4)를 반환해요. | | 예시 | uuid() | | 결과 | 다양함 |

`uuidv4()`

| 설명 | eeccb8c5-9943-b2bb-bb5e-222f4e14b687 같은 무작위 UUID(UUIDv4)를 반환해요. | | 예시 | uuidv4() | | 결과 | 다양함 |

`uuidv7()`

| 설명 | 81964ebe-00b1-7e1d-b0f9-43c29b6fb8f5 같은 무작위 UUIDv7을 반환해요. | | 예시 | uuidv7() | | 결과 | 다양함 |

`uuid_extract_timestamp(uuidv7)`

| 설명 | UUIDv7 값에서 TIMESTAMP WITH TIME ZONE을 추출해요. | | 예시 | uuid_extract_timestamp(uuidv7()) | | 결과 | 2025-04-19 15:51:20.07+00 |

`uuid_extract_version(uuid)`

| 설명 | UUID 버전(4 또는 7)을 추출해요. | | 예시 | uuid_extract_version(uuidv7()) | | 결과 | 7 |

`version()`

| 설명 | 현재 활성 DuckDB 버전을 이 형식으로 반환해요. | | 예시 | version() | | 결과 | 다양함 |

유틸리티 테이블 함수 (Utility Table Functions)

테이블 함수는 FROM 절에서 테이블 대신 사용돼요.

이름	설명
`glob(search_path)`	search_path가 가리키는 위치에서 찾은 파일 이름을 `file`이라는 단일 열로 반환해요. search_path는 glob 패턴 매칭 문법을 포함할 수 있어요.
`repeat_row(varargs, num_rows)`	`num_rows`개의 행을 가진 테이블을 반환하며, 각 행은 `varargs`에 정의된 필드를 담아요.

`glob(search_path)`

| 설명 | search_path가 가리키는 위치에서 찾은 파일 이름을 file이라는 단일 열로 반환해요. search_path는 glob 패턴 매칭 문법을 포함할 수 있어요. | | 예시 | glob('*') | | 결과 | (파일 이름 테이블) |

`repeat_row(varargs, num_rows)`

| 설명 | num_rows개의 행을 가진 테이블을 반환하며, 각 행은 varargs에 정의된 필드를 담아요. | | 예시 | repeat_row(1, 2, 'foo', num_rows = 3) | | 결과 | 1, 2, 'foo'의 3개 행 |

유틸리티 함수