기타 함수

참고

아래 함수에 대한 문서는 system.functions 시스템 테이블에서 자동 생성됩니다.

FQDN

도입 버전: v20.1

ClickHouse 서버의 정규화된 도메인 이름(FQDN)을 반환합니다.

구문

fqdn()

별칭: fullHostName

인수

• 없음.

반환 값

ClickHouse 서버의 정규화된 도메인 이름(FQDN)을 반환합니다. String

예시

사용 예시

SELECT fqdn()

┌─FQDN()──────────────────────────┐
│ clickhouse.us-east-2.internal │
└─────────────────────────────────┘

MACNumToString

도입된 버전: v1.1

UInt64 숫자를 빅 엔디언(big endian) 형식의 MAC 주소로 해석합니다. 해당 숫자에 대응하는 MAC 주소를 AA:BB:CC:DD:EE:FF 형식의 문자열로 반환합니다(16진수 숫자를 콜론으로 구분).

구문

MACNumToString(num)

인수

• num — UInt64 숫자. UInt64

반환 값

AA:BB:CC:DD:EE:FF 형식의 MAC 주소를 반환합니다. String

예시

사용 예시

SELECT MACNumToString(149809441867716) AS mac_address;

┌─mac_address───────┐
│ 88:00:11:22:33:44 │
└───────────────────┘

MACStringToNum

도입된 버전: v1.1

MACNumToString의 역함수입니다. MAC 주소의 형식이 올바르지 않으면 0을 반환합니다.

구문

MACStringToNum(s)

인수

• s — MAC 주소 문자열. String

반환 값

UInt64 정수를 반환합니다. UInt64

예시

사용 예시

SELECT MACStringToNum('01:02:03:04:05:06') AS mac_numeric;

1108152157446

MACStringToOUI

도입 버전: v1.1

AA:BB:CC:DD:EE:FF 형식(16진수 형태의 숫자를 콜론으로 구분한 형식)의 MAC 주소가 주어지면, 앞의 세 옥텟을 UInt64 값으로 반환합니다. MAC 주소 형식이 올바르지 않으면 0을 반환합니다.

구문

MACStringToOUI(s)

인수

• s — MAC 주소 문자열. String

반환 값

첫 세 옥텟을 UInt64 값으로 반환합니다. UInt64

예시

사용 예시

SELECT MACStringToOUI('00:50:56:12:34:56') AS oui;

20566

__applyFilter

도입 버전: v25.10

JOIN 런타임 필터링을 위한 특수한 FUNCTION입니다.

구문

__applyFilter(filter_name, key)

인수

• filter_name — 런타임 필터의 내부 이름입니다. BuildRuntimeFilterStep에 의해 생성됩니다. String
• key — 필터에 존재하는지 여부를 확인할 임의의 타입 값입니다.

반환 값

키가 필터링되어야 하는 경우 False입니다. Bool

예시

예시

This function is not supposed to be used in user queries. It might be added to query plan during optimization.

__patchPartitionID

도입 버전: v25.5

내부 함수입니다. 파트 이름과 패치 파트의 컬럼 이름 해시값을 인자로 받습니다. 패치 파트의 파티션 이름을 반환합니다. 인자는 올바른 파트 이름이어야 하며, 그렇지 않으면 동작은 정의되지 않습니다.

구문

인수

• 없음

반환 값

예제

authenticatedUser

도입 버전: v25.11

세션의 USER가 EXECUTE AS 명령으로 변경된 경우, 이 FUNCTION은 인증 및 세션 생성에 사용된 원래 사용자 이름을 반환합니다. 별칭: authUser()

구문

authenticatedUser()

별칭: authUser

인수

• 없습니다.

반환 값

인증된 사용자 이름입니다. String

예시

사용 예시

EXECUTE as u1;
            SELECT currentUser(), authenticatedUser();

┌─currentUser()─┬─authenticatedUser()─┐
│ u1            │ default             │
└───────────────┴─────────────────────┘

bar

도입 버전: v1.1

막대 차트를 생성합니다. (x - min)에 비례하는 너비를 가지며, x = max일 때는 width 개의 문자 폭과 동일한 막대를 그립니다. 막대는 문자 하나를 1/8로 나눈 수준의 정밀도로 그려집니다.

구문

bar(x, min, max[, width])

인자

• x — 표시할 크기. (U)Int* 또는 Float* 또는 Decimal
• min — 최소값. (U)Int* 또는 Float* 또는 Decimal
• max — 최대값. (U)Int* 또는 Float* 또는 Decimal
• width — 선택 사항. 막대의 너비(문자 수 기준). 기본값은 80입니다. const (U)Int* 또는 const Float* 또는 const Decimal

반환 값

유니코드 아트 형태의 막대를 나타내는 문자열을 반환합니다. String

예시

사용 예시

SELECT
toHour(EventTime) AS h,
count() AS c,
bar(c, 0, 600000, 20) AS bar
FROM test.hits
GROUP BY h
ORDER BY h ASC

┌──h─┬──────c─┬─bar────────────────┐
│  0 │ 292907 │ █████████▋         │
│  1 │ 180563 │ ██████             │
│  2 │ 114861 │ ███▋               │
│  3 │  85069 │ ██▋                │
│  4 │  68543 │ ██▎                │
│  5 │  78116 │ ██▌                │
│  6 │ 113474 │ ███▋               │
│  7 │ 170678 │ █████▋             │
│  8 │ 278380 │ █████████▎         │
│  9 │ 391053 │ █████████████      │
│ 10 │ 457681 │ ███████████████▎   │
│ 11 │ 493667 │ ████████████████▍  │
│ 12 │ 509641 │ ████████████████▊  │
│ 13 │ 522947 │ █████████████████▍ │
│ 14 │ 539954 │ █████████████████▊ │
│ 15 │ 528460 │ █████████████████▌ │
│ 16 │ 539201 │ █████████████████▊ │
│ 17 │ 523539 │ █████████████████▍ │
│ 18 │ 506467 │ ████████████████▊  │
│ 19 │ 520915 │ █████████████████▎ │
│ 20 │ 521665 │ █████████████████▍ │
│ 21 │ 542078 │ ██████████████████ │
│ 22 │ 493642 │ ████████████████▍  │
│ 23 │ 400397 │ █████████████▎     │
└────┴────────┴────────────────────┘

blockNumber

도입 버전: v1.1

행이 포함된 블록의 단조 증가하는 일련 번호를 반환합니다. 반환되는 블록 번호는 best-effort 방식으로 업데이트되므로 완전히 정확하지 않을 수 있습니다.

구문

blockNumber()

인수

• 없음.

반환 값

행이 위치한 데이터 블록의 시퀀스 번호. UInt64

예시

기본 사용법

SELECT blockNumber()
FROM
(
    SELECT *
    FROM system.numbers
    LIMIT 10
) SETTINGS max_block_size = 2

┌─blockNumber()─┐
│             7 │
│             7 │
└───────────────┘
┌─blockNumber()─┐
│             8 │
│             8 │
└───────────────┘
┌─blockNumber()─┐
│             9 │
│             9 │
└───────────────┘
┌─blockNumber()─┐
│            10 │
│            10 │
└───────────────┘
┌─blockNumber()─┐
│            11 │
│            11 │
└───────────────┘

blockSerializedSize

도입: v20.3

디스크에 저장된 값 블록의 비압축 크기를 바이트 단위로 반환합니다.

구문

blockSerializedSize(x1[, x2[, ...]])

인수

• x1[, x2, ...] — 압축되지 않은 블록 크기를 계산할 값들로, 개수에는 제한이 없습니다. Any

반환 값

압축 없이 값 블록이 디스크에 기록될 때 사용되는 바이트 수를 반환합니다. UInt64

예시

사용 예시

SELECT blockSerializedSize(maxState(1)) AS x;

┌─x─┐
│ 2 │
└───┘

blockSize

도입 버전: v1.1

ClickHouse에서는 쿼리가 블록 (청크) 단위로 처리됩니다. 이 FUNCTION이 호출되는 블록의 크기(행 수)를 반환합니다.

구문

blockSize()

인수(Arguments)

• 없음

반환값

현재 블록에 있는 행의 개수를 반환합니다. UInt64

예시(Examples)

사용 예시(Usage example)

SELECT blockSize()
FROM system.numbers LIMIT 5

┌─blockSize()─┐
│           5 │
│           5 │
│           5 │
│           5 │
│           5 │
└─────────────┘

buildId

도입된 버전: v20.5

실행 중인 ClickHouse 서버 바이너리에 대해 컴파일러가 생성한 빌드 ID를 반환합니다. 분산 테이블(distributed table) 컨텍스트에서 실행되는 경우 이 함수는 각 세그먼트에 해당하는 값을 가지는 일반 컬럼을 생성합니다. 그 외의 경우에는 상수 값을 반환합니다.

구문

buildId()

인수(Arguments)

• 없음.

반환값

빌드 ID를 반환합니다. String

예시(Examples)

사용 예(Usage example)

SELECT buildId()

┌─buildId()────────────────────────────────┐
│ AB668BEF095FAA6BD26537F197AC2AF48A927FB4 │
└──────────────────────────────────────────┘

byteSize

도입된 버전: v21.1

인수가 메모리에 저장될 때의 비압축 바이트 크기를 추정하여 반환합니다. String 인수의 경우, 문자열 길이 + 8(길이)을 반환합니다. 함수에 여러 인수가 전달되면, 각 인수의 바이트 크기를 누적하여 합산합니다.

구문

byteSize(arg1[, arg2, ...])

인수

• arg1[, arg2, ...] — 압축되지 않은 바이트 크기를 추정하려는 임의의 데이터 타입 값입니다. Any

반환 값

인수의 메모리 내 바이트 크기를 추정하여 반환합니다. UInt64

예시

사용 예시

SELECT byteSize('string')

┌─byteSize('string')─┐
│                 15 │
└────────────────────┘

여러 인수

SELECT byteSize(NULL, 1, 0.3, '')

┌─byteSize(NULL, 1, 0.3, '')─┐
│                         19 │
└────────────────────────────┘

catboostEvaluate

도입된 버전: v22.9

외부 CatBoost 모델을 평가합니다. CatBoost는 Yandex에서 머신 러닝을 위해 개발한 오픈 소스 그래디언트 부스팅 라이브러리입니다. CatBoost 모델 파일 경로와 모델 인자(피처)를 인수로 받습니다.

사전 요구 사항

1. CatBoost 평가 라이브러리 빌드

CatBoost 모델을 평가하기 전에 libcatboostmodel.<so|dylib> 라이브러리를 사용할 수 있도록 준비해야 합니다. 컴파일 방법은 CatBoost 문서를 참고하십시오.

다음으로, ClickHouse 설정에서 libcatboostmodel.<so|dylib>에 대한 경로를 지정합니다:

<clickhouse>
...
    <catboost_lib_path>/path/to/libcatboostmodel.so</catboost_lib_path>
...
</clickhouse>

보안 및 격리 측면에서 모델 평가는 서버 프로세스가 아니라 clickhouse-library-bridge 프로세스에서 실행됩니다. catboostEvaluate()를 처음 실행할 때 서버는 라이브러리 브리지 프로세스가 아직 실행 중이 아니면 이를 시작합니다. 두 프로세스는 HTTP 인터페이스를 사용하여 통신합니다. 기본 포트는 9012입니다. 포트 9012가 이미 다른 서비스에 할당되어 있다면 다음과 같이 다른 포트를 지정할 수 있습니다.

<library_bridge>
    <port>9019</port>
</library_bridge>

2. libcatboost를 사용하여 catboost 모델 학습

훈련 데이터 세트에서 catboost 모델을 학습하는 방법은 Training and applying models을 참고하십시오.

구문

catboostEvaluate(path_to_model, feature_1[, feature_2, ..., feature_n])

인수(Arguments)

• path_to_model — CatBoost 모델 파일 경로입니다. const String
• feature — 하나 이상의 모델 특성(feature)을 나타냅니다. Float*

반환 값(Returned value)

모델 평가 결과를 반환합니다. Float64

예시(Examples)

catboostEvaluate

SELECT catboostEvaluate('/root/occupy.bin', Temperature, Humidity, Light, CO2, HumidityRatio) AS prediction FROM occupancy LIMIT 1

4.695691092573497

colorOKLABToSRGB

도입된 버전: v26.2

OKLab 지각 색 공간의 색상을 sRGB 색 공간으로 변환합니다.

입력 색상은 OKLab 색 공간에서 지정됩니다. 입력 값이 일반적인 OKLab 범위를 벗어나면, 결과는 구현에 따라 달라질 수 있습니다.

OKLab은 세 가지 구성 요소를 사용합니다:

• L: 지각적 밝기(일반적으로 [0..1] 범위)
  • a: 녹색-빨강 대립 축
  • b: 파랑-노랑 대립 축

a와 b 구성 요소는 이론적으로는 제한이 없지만, 실제로는 -0.4에서 0.4 사이에 있습니다. OKLab은 계산 비용을 낮게 유지하면서 지각적으로 균일하도록 설계되었습니다.

이 변환은 colorSRGBToOKLAB의 역변환이 되도록 설계되었으며, 다음 단계들로 구성됩니다:

1. Conversion from OKLab to linear sRGB.
2. Conversion from linear sRGB to gamma-encoded sRGB.

선택적인 gamma 인수는 선형 sRGB에서 감마 인코딩된 RGB 값으로 변환할 때 사용되는 지수를 지정합니다. 지정하지 않으면 colorSRGBToOKLAB과의 일관성을 위해 기본 gamma 값이 사용됩니다.

OKLab 색 공간과 sRGB의 관계에 대한 자세한 내용은 https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/oklab 을 참고하십시오.

구문

colorOKLABToSRGB(tuple [, gamma])

인수(Arguments)

• tuple — 세 개의 숫자 값 L, a, b로 구성된 튜플입니다. 여기서 L은 [0...1] 범위입니다. Tuple(Float64, Float64, Float64)
• gamma — 선택 사항입니다. 각 채널 x에 대해 (x ^ (1 / gamma)) * 255를 적용하여 선형 sRGB를 sRGB로 다시 변환하는 데 사용되는 지수입니다. 기본값은 2.2입니다. Float64

반환 값

sRGB 색상 값을 나타내는 (R, G, B) 튜플을 반환합니다. Tuple(Float64, Float64, Float64)

예시

OKLAB을 sRGB (Float)로 변환

SELECT colorOKLABToSRGB((0.4466, 0.0991, 0.44)) AS rgb;

┌─rgb──────────────────────┐
│ (198.07056923258935,0,0) │
└──────────────────────────┘

OKLAB를 sRGB(UInt8)로 변환

WITH colorOKLABToSRGB((0.7, 0.1, 0.54)) AS t
SELECT tuple(toUInt8(t.1), toUInt8(t.2), toUInt8(t.3)) AS RGB;

┌─RGB──────────┐
│ (255,0,0)    │
└──────────────┘

colorOKLCHToSRGB

도입 버전: v25.7

OKLCH 지각 색 공간의 색상을 익숙한 sRGB 색 공간으로 변환합니다.

L이 [0...1] 범위를 벗어나거나, C가 음수이거나, H가 [0...360] 범위를 벗어나는 경우 결과는 구현에 따라 달라집니다.

참고

OKLCH는 OKLab 색 공간의 원통형 버전입니다. 세 좌표는 L(밝기, 범위 [0...1]), C(채도, >= 0), H(색상, 도 단위 [0...360])입니다. OKLab/OKLCH는 연산 비용을 낮게 유지하면서도 지각적으로 균일하도록 설계되었습니다.

변환은 colorSRGBToOKLCH의 역연산입니다:

1. OKLCH에서 OKLab으로 변환 2) OKLab에서 Linear sRGB로 변환 3) Linear sRGB에서 sRGB로 변환

두 번째 인수인 gamma는 마지막 단계에서 사용됩니다.

OKLCH 공간에서의 색상과 그것이 sRGB 색상과 어떻게 대응되는지에 대해서는 https://oklch.com/을 참조하십시오.

구문

colorOKLCHToSRGB(tuple [, gamma])

인자

• tuple — 세 개의 숫자 값 L, C, H로 구성된 튜플입니다. L은 [0...1] 범위에 있고, C >= 0, H는 [0...360] 범위에 있습니다. Tuple(Float64, Float64, Float64)
• gamma — 선택 사항입니다. 각 채널 x에 대해 (x ^ (1 / gamma)) * 255를 적용하여 linear sRGB를 sRGB로 다시 변환할 때 사용하는 지수입니다. 기본값은 2.2입니다. Float64

반환 값

sRGB 색상 값을 나타내는 튜플 (R, G, B)을 반환합니다. Tuple(Float64, Float64, Float64)

예제

OKLCH를 sRGB로 변환

SELECT colorOKLCHToSRGB((0.6, 0.12, 40)) AS rgb;

┌─rgb───────────────────────────────────────────────────────┐
│ (186.02058688365264,100.68677189684993,71.67819977081575) │
└───────────────────────────────────────────────────────────┘

OKLCH를 sRGB(UInt8)로 변환

WITH colorOKLCHToSRGB((0.6, 0.12, 40)) AS t
SELECT tuple(toUInt8(t.1), toUInt8(t.2), toUInt8(t.3)) AS RGB;

┌─RGB──────────┐
│ (186,100,71) │
└──────────────┘

colorSRGBToOKLAB

도입된 버전: v26.2

sRGB 색 공간으로 인코딩된 색을 지각적 균일성(perceptually uniform)을 갖는 OKLAB 색 공간으로 변환합니다.

입력 채널 중 하나라도 [0...255] 범위를 벗어나거나 감마(gamma) 값이 0 이하인 경우, 동작은 구현에 따라 정의됩니다.

참고

OKLAB은 지각적으로 균일한 색 공간입니다. 세 좌표는 L(범위 [0...1]의 명도), a (Green-Red axis), b (Blue-Yellow axis)입니다. OKLab은 계산 비용을 낮게 유지하면서 지각적 균일성을 갖도록 설계되었습니다.

변환은 두 단계로 이루어집니다:

1. sRGB → Linear sRGB
2. Linear sRGB → OKLab

구문

colorSRGBToOKLAB(tuple[, gamma])

인수

• tuple — [0...255] 범위의 R, G, B 세 값으로 구성된 튜플입니다. Tuple(UInt8, UInt8, UInt8)
• gamma — 선택 사항입니다. 각 채널 x에 (x / 255)^gamma를 적용하여 sRGB를 선형화하기 위해 사용하는 지수입니다. 기본값은 2.2입니다. Float64

반환 값

OKLAB 색 공간 값 (L, a, b)을 나타내는 튜플을 반환합니다. Tuple(Float64, Float64, Float64)

예시

sRGB를 OKLAB으로 변환

SELECT colorSRGBToOKLAB((128, 64, 32), 2.2) AS lab;

┌─lab──────────────────────────────────────────────────────────┐
│ (0.4436238384931984,0.07266246769242975,0.07500108778529994) │
└──────────────────────────────────────────────────────────────┘

colorSRGBToOKLCH

도입 버전: v25.7

sRGB 색 공간으로 인코딩된 색상을 지각적으로 균일한 OKLCH 색 공간으로 변환합니다.

입력 채널 중 하나라도 [0...255] 범위를 벗어나거나 감마 값이 0 이하이면 동작은 구현에 따라 달라집니다.

참고

OKLCH는 OKLab 색 공간의 원통형 버전입니다. 세 좌표는 L(밝기, 범위 [0...1]), C(채도, >= 0), H(색상, [0...360] 범위의 도 단위)입니다. OKLab/OKLCH는 계산 비용을 낮게 유지하면서도 지각적으로 균일하도록 설계되었습니다.

변환은 다음 세 단계로 구성됩니다.

1. sRGB에서 Linear sRGB로 변환 2) Linear sRGB에서 OKLab으로 변환 3) OKLab에서 OKLCH로 변환

OKLCH 공간에서의 색상 예시와 그것이 sRGB 색상과 어떻게 대응되는지에 대해서는 https://OKLCH.com/을 참조하십시오.

Syntax

colorSRGBToOKLCH(tuple[, gamma])

인수

• tuple — [0...255] 범위의 R, G, B 세 값으로 구성된 튜플입니다. Tuple(UInt8, UInt8, UInt8)
• gamma — 옵션입니다. 각 채널 x에 (x / 255)^gamma를 적용해 sRGB를 선형화할 때 사용하는 지수입니다. 기본값은 2.2입니다. Float64

반환 값

OKLCH 색 공간 값 (L, C, H)을 나타내는 튜플을 반환합니다. Tuple(Float64, Float64, Float64)

예시

sRGB를 OKLCH로 변환

SELECT colorSRGBToOKLCH((128, 64, 32), 2.2) AS lch;

┌─lch───────────────────────────────────────────────────────┐
│ (0.4436238384931984,0.1044269954567863,45.90734548193018) │
└───────────────────────────────────────────────────────────┘

connectionId

도입: v21.3

현재 쿼리를 전송한 클라이언트의 연결 ID를 반환합니다. 이 함수는 디버깅 상황에서 가장 유용합니다. MySQL의 CONNECTION_ID 함수와의 호환성을 위해 만들어졌습니다. 운영 환경의 쿼리에서는 일반적으로 사용되지 않습니다.

구문

connectionId()

인수

• 없음.

반환값

현재 클라이언트의 연결 ID를 반환합니다. UInt64

예제

사용 예제

SELECT connectionId();

┌─connectionId()─┐
│              0 │
└────────────────┘

countDigits

도입 버전: v20.8

값을 표현하는 데 필요한 10진수 자릿수의 개수를 반환합니다.

참고

이 함수는 10진수 값의 스케일을 고려합니다. 즉, (value * scale)이라는 내부 정수 타입을 기준으로 결과를 계산합니다.

예를 들면 다음과 같습니다.

• countDigits(42) = 2
• countDigits(42.000) = 5
• countDigits(0.04200) = 4

팁

Decimal64에 대해 countDigits(x) > 18 조건으로 10진수 오버플로를 확인할 수 있습니다. 다만 isDecimalOverflow보다 느립니다.

구문

countDigits(x)

인수

• x — 정수 또는 소수 값입니다. (U)Int* 또는 Decimal

반환 값

x를 표현하는 데 필요한 자릿수를 반환합니다. UInt8

예제

사용 예제

SELECT countDigits(toDecimal32(1, 9)), countDigits(toDecimal32(-1, 9)),
       countDigits(toDecimal64(1, 18)), countDigits(toDecimal64(-1, 18)),
       countDigits(toDecimal128(1, 38)), countDigits(toDecimal128(-1, 38));

┌─countDigits(toDecimal32(1, 9))─┬─countDigits(toDecimal32(-1, 9))─┬─countDigits(toDecimal64(1, 18))─┬─countDigits(toDecimal64(-1, 18))─┬─countDigits(toDecimal128(1, 38))─┬─countDigits(toDecimal128(-1, 38))─┐
│                             10 │                              10 │                              19 │                               19 │                               39 │                                39 │
└────────────────────────────────┴─────────────────────────────────┴─────────────────────────────────┴──────────────────────────────────┴──────────────────────────────────┴───────────────────────────────────┘

currentDatabase

도입 버전: v1.1

현재 데이터베이스 이름을 반환합니다. 데이터베이스를 지정해야 하는 CREATE TABLE 쿼리의 테이블 엔진 매개변수에서 유용합니다.

SET SQL 문도 참고하십시오.

구문

currentDatabase()

별칭(Aliases): current_database, SCHEMA, DATABASE

인수(Arguments)

• 없음

반환값(Returned value)

현재 데이터베이스 이름을 반환합니다. String

예시(Examples)

사용 예시(Usage example)

SELECT currentDatabase()

┌─currentDatabase()─┐
│ default           │
└───────────────────┘

currentProfiles

도입된 버전: v21.9

현재 사용자에 대한 설정 프로필 배열을 반환합니다.

구문

currentProfiles()

인수

• 없음.

반환 값

현재 사용자에 대한 설정 프로필의 배열을 반환합니다. Array(String)

예시

사용 예시

SELECT currentProfiles();

┌─currentProfiles()─────────────────────────────┐
│ ['default', 'readonly_user', 'web_analytics'] │
└───────────────────────────────────────────────┘

currentQueryID

도입 버전: v

현재 쿼리 ID를 반환합니다.

구문

currentQueryID()

별칭: current_query_id

인수

• 없음.

반환값

예시

예시

SELECT currentQueryID();

┌─currentQueryID()─────────────────────┐
│ 1280d0e8-1a08-4524-be6e-77975bb68e7d │
└──────────────────────────────────────┘

currentRoles

도입 버전: v21.9

현재 사용자에게 할당된 역할의 배열을 반환합니다.

구문

currentRoles()

인수

• 없음.

반환값

현재 사용자에게 할당된 역할의 배열을 반환합니다. Array(String)

예시

사용 예시

SELECT currentRoles();

┌─currentRoles()─────────────────────────────────┐
│ ['sql-console-role:jane.smith@clickhouse.com'] │
└────────────────────────────────────────────────┘

currentSchemas

도입된 버전: v23.7

함수 currentDatabase와 동일하지만 다음과 같은 차이가 있습니다.

• 무시되는 Boolean 인수 하나를 인수로 받습니다.
• 데이터베이스 이름을 단일 값이 들어 있는 배열로 반환합니다.

함수 currentSchemas는 PostgreSQL과의 호환성을 위해서만 존재합니다. 대신 currentDatabase를 사용하십시오.

SET SQL 문도 참고하십시오.

문법

currentSchemas(bool)

별칭(Aliases): current_schemas

인수(Arguments)

• bool — 사용되지 않는 Boolean 값입니다. Bool

반환 값(Returned value)

현재 데이터베이스 이름을 담은 단일 요소 배열을 반환합니다. Array(String)

예제(Examples)

사용 예제(Usage example)

SELECT currentSchemas(true)

┌─currentSchemas(true)─┐
│ ['default']          │
└──────────────────────┘

currentUser

도입 버전: v20.1

현재 사용자의 이름을 반환합니다. 분산 쿼리에서는, 쿼리를 시작한 사용자의 이름을 반환합니다.

구문

currentUser()

별칭(Aliases): current_user, user

인수(Arguments)

• 없음.

반환 값(Returned value)

현재 사용자 이름을 반환하며, 그렇지 않으면 쿼리를 시작한 사용자의 로그인명을 반환합니다. String

예시(Examples)

사용 예시(Usage example)

SELECT currentUser()

┌─currentUser()─┐
│ default       │
└───────────────┘

defaultProfiles

도입 버전: v21.9

현재 사용자에게 적용되는 기본 설정 프로필 이름 배열을 반환합니다.

구문

defaultProfiles()

인수

• 없음.

반환 값

현재 사용자에 대한 기본 설정 프로필 이름 배열을 반환합니다. Array(String)

예시

사용 예시

SELECT defaultProfiles();

┌─defaultProfiles()─┐
│ ['default']       │
└───────────────────┘

defaultRoles

도입된 버전: v21.9

현재 사용자에 대해 기본 역할 배열을 반환합니다.

구문

defaultRoles()

인수

• 없음.

반환 값

현재 사용자에 대한 기본 역할 배열을 반환합니다. Array(String)

예시

사용 예시

SELECT defaultRoles();

┌─defaultRoles()─────────────────────────────────┐
│ ['sql-console-role:jane.smith@clickhouse.com'] │
└────────────────────────────────────────────────┘

defaultValueOfArgumentType

도입 버전: v1.1

지정된 데이터 유형에 대한 기본값을 반환합니다. 사용자가 설정한 사용자 정의 컬럼 기본값은 포함하지 않습니다.

구문

defaultValueOfArgumentType(expression)

인수

• expression — 임의 타입의 값 또는 임의 타입의 값으로 평가되는 식입니다. Any

반환 값

숫자 타입에는 0, 문자열 타입에는 빈 문자열, 널 허용(Nullable) 타입에는 NULL을 반환합니다. UInt8 또는 String 또는 NULL

예시

사용 예시

SELECT defaultValueOfArgumentType(CAST(1 AS Int8));

┌─defaultValueOfArgumentType(CAST(1, 'Int8'))─┐
│                                           0 │
└─────────────────────────────────────────────┘

널 허용 예시

SELECT defaultValueOfArgumentType(CAST(1 AS Nullable(Int8)));

┌─defaultValueOfArgumentType(CAST(1, 'Nullable(Int8)'))─┐
│                                                  ᴺᵁᴸᴸ │
└───────────────────────────────────────────────────────┘

defaultValueOfTypeName

도입 버전: v1.1

지정된 타입 이름에 해당하는 기본값을 반환합니다.

구문

defaultValueOfTypeName(type)

인수

• type — 타입 이름을 나타내는 문자열입니다. String

반환 값

지정된 타입 이름에 대한 기본값을 반환합니다: 숫자 타입의 경우 0, 문자열 타입의 경우 빈 문자열, 또는 Nullable UInt8 또는 String 또는 NULL인 경우 NULL을 반환합니다.

예제

사용 예제

SELECT defaultValueOfTypeName('Int8');

┌─defaultValueOfTypeName('Int8')─┐
│                              0 │
└────────────────────────────────┘

널 허용 예시

SELECT defaultValueOfTypeName('Nullable(Int8)');

┌─defaultValueOfTypeName('Nullable(Int8)')─┐
│                                     ᴺᵁᴸᴸ │
└──────────────────────────────────────────┘

displayName

도입 버전: v22.11

config의 display_name 값이 설정되어 있으면 해당 값을, 설정되어 있지 않으면 서버의 FQDN(Fully Qualified Domain Name, 정규화된 도메인 이름)을 반환합니다.

구문

displayName()

인수

• 없음.

반환 값

config에 display_name이 설정되어 있으면 해당 값을, 설정되지 않은 경우 서버 FQDN을 반환합니다. String

예시

사용 예시

SELECT displayName();

┌─displayName()─┐
│ production    │
└───────────────┘

dumpColumnStructure

도입 버전: v1.1

컬럼의 내부 구조와 데이터 타입에 대한 상세한 설명을 출력합니다.

구문

dumpColumnStructure(x)

인수

• x — 설명을 가져올 값입니다. Any

반환 값

값을 표현하는 데 사용되는 컬럼 구조에 대한 설명을 반환합니다. String

예시

사용 예시

SELECT dumpColumnStructure(CAST('2018-01-01 01:02:03', 'DateTime'));

┌─dumpColumnStructure(CAST('2018-01-01 01:02:03', 'DateTime'))─┐
│ DateTime, Const(size = 1, UInt32(size = 1))                  │
└──────────────────────────────────────────────────────────────┘

enabledProfiles

도입 버전: v21.9

현재 사용자에 대해 활성화된 설정 프로필 이름을 배열로 반환합니다.

구문

enabledProfiles()

인수

• 없음.

반환 값

현재 USER에 대해 활성화된 설정 프로필 이름 배열을 반환합니다. Array(String)

예시

사용 예시

SELECT enabledProfiles();

┌─enabledProfiles()─────────────────────────────────────────────────┐
│ ['default', 'readonly_user', 'web_analytics', 'batch_processing'] │
└───────────────────────────────────────────────────────────────────┘

enabledRoles

도입 버전: v21.9

현재 사용자에게 활성화된 역할(role)들의 배열을 반환합니다.

구문

enabledRoles()

인수

• 없음.

반환값

현재 사용자에 대해 활성화된 역할 이름의 배열을 반환합니다. Array(String)

예시

사용 예시

SELECT enabledRoles();

┌─enabledRoles()─────────────────────────────────────────────────┐
│ ['general_data', 'sql-console-role:jane.smith@clickhouse.com'] │
└────────────────────────────────────────────────────────────────┘

errorCodeToName

도입된 버전: v20.12

숫자형 ClickHouse 오류 코드에 대한 텍스트 이름을 반환합니다. 숫자 오류 코드에서 오류 이름으로의 매핑은 여기에서 확인할 수 있습니다.

구문

errorCodeToName(error_code)

인수

• error_code — ClickHouse 오류 코드. (U)Int* 또는 Float* 또는 Decimal

반환 값

error_code의 텍스트 이름을 반환합니다. String

예제

사용 예제

SELECT errorCodeToName(252);

┌─errorCodeToName(252)─┐
│ TOO_MANY_PARTS       │
└──────────────────────┘

file

도입 버전: v21.3

파일을 문자열로 읽어 지정된 컬럼에 데이터를 로드합니다. 파일 내용은 해석되지 않습니다.

file 테이블 함수도 참고하십시오.

구문

file(path[, default])

인수

• path — user_files_path를 기준으로 한 파일 경로입니다. 와일드카드 *, **, ?, {abc,def}, {N..M} 패턴을 지원하며, 여기서 N, M은 숫자이고 'abc', 'def'는 문자열입니다. String
• default — 파일이 존재하지 않거나 접근할 수 없을 때 반환되는 값입니다. String 또는 NULL

반환 값

파일 내용을 문자열로 반환합니다. String

예제

테이블에 파일 삽입

INSERT INTO table SELECT file('a.txt'), file('b.txt');

filesystemAvailable

도입 버전: v20.1

데이터베이스 영속 데이터를 저장하는 파일 시스템에서 사용 가능한 여유 공간의 크기를 반환합니다. 일부 공간이 운영 체제를 위해 예약되어 있기 때문에 반환값은 항상 전체 여유 공간(filesystemUnreserved)보다 작습니다.

구문

filesystemAvailable([disk_name])

인수

• disk_name — 선택 사항입니다. 사용 가능한 공간을 조회할 디스크 이름입니다. 생략하면 기본 디스크를 사용합니다. String 또는 FixedString

반환 값

사용 가능한 남은 공간을 바이트 단위로 반환합니다. UInt64

예시

사용 예시

SELECT formatReadableSize(filesystemAvailable()) AS "Available space";

┌─Available space─┐
│ 30.75 GiB       │
└─────────────────┘

filesystemCapacity

도입된 버전: v20.1

파일 시스템의 용량을 바이트 단위로 반환합니다. 데이터 디렉터리를 가리키는 path를 설정해야 합니다.

구문

filesystemCapacity([disk_name])

인자

• disk_name — 선택적입니다. 용량을 조회할 디스크 이름입니다. 지정하지 않으면 기본 디스크를 사용합니다. String 또는 FixedString

반환값

파일 시스템의 용량을 바이트 단위로 반환합니다. UInt64

예시

사용 예시

SELECT formatReadableSize(filesystemCapacity()) AS "Capacity";

┌─Capacity──┐
│ 39.32 GiB │
└───────────┘

filesystemUnreserved

도입: v22.12

데이터베이스 영구 저장소가 위치한 파일 시스템의 총 여유 공간을 반환합니다(이전 이름: filesystemFree). filesystemAvailable도 참고하십시오.

구문

filesystemUnreserved([disk_name])

인수

• disk_name — 선택 사항입니다. 총 사용 가능한 공간을 조회할 디스크의 이름입니다. 생략하면 기본 디스크를 사용합니다. String 또는 FixedString

반환값

사용 가능한 공간의 크기를 바이트 단위로 반환합니다. UInt64

예제

사용 예제

SELECT formatReadableSize(filesystemUnreserved()) AS "Free space";

┌─Free space─┐
│ 32.39 GiB  │
└────────────┘

finalizeAggregation

도입 버전: v1.1

집계 상태가 주어지면 이 FUNCTION은 집계 결과를 반환합니다. -State 결합자를 사용하는 경우에는 정리(finalize)된 상태를 반환합니다.

구문

finalizeAggregation(state)

인수

• state — 집계 상태입니다. AggregateFunction

반환 값

집계의 최종 결과를 반환합니다. Any

예시

사용 예시

SELECT finalizeAggregation(arrayReduce('maxState', [1, 2, 3]));

┌─finalizeAggregation(arrayReduce('maxState', [1, 2, 3]))─┐
│                                                       3 │
└─────────────────────────────────────────────────────────┘

initializeAggregation과 함께 사용

WITH initializeAggregation('sumState', number) AS one_row_sum_state
SELECT
    number,
    finalizeAggregation(one_row_sum_state) AS one_row_sum,
    runningAccumulate(one_row_sum_state) AS cumulative_sum
FROM numbers(5);

┌─number─┬─one_row_sum─┬─cumulative_sum─┐
│      0 │           0 │              0 │
│      1 │           1 │              1 │
│      2 │           2 │              3 │
│      3 │           3 │              6 │
│      4 │           4 │             10 │
└────────┴─────────────┴────────────────┘

flipCoordinates

도입 버전: v25.10

기하 객체의 x, y 좌표를 뒤집습니다. 이 연산은 위도와 경도를 서로 교환하므로, 서로 다른 좌표계 간 변환이나 좌표의 순서를 교정하는 데 유용합니다.

Point의 경우 x, y 좌표를 서로 교환합니다. 복잡한 기하 객체(LineString, Polygon, MultiPolygon, Ring, MultiLineString)의 경우 각 좌표 쌍에 대해 이 변환을 재귀적으로 적용합니다.

이 FUNCTION은 개별 기하 타입(Point, Ring, Polygon, MultiPolygon, LineString, MultiLineString)과 Geometry variant 타입 모두를 지원합니다.

구문

flipCoordinates(geometry)

인수

• geometry — 변환할 기하 도형입니다. 지원되는 타입은 다음과 같습니다: Point (Tuple(Float64, Float64)), Ring (Array(Point)), Polygon (Array(Ring)), MultiPolygon (Array(Polygon)), LineString (Array(Point)), MultiLineString (Array(LineString)), 또는 Geometry (위 타입들 중 하나를 포함하는 variant 타입).

반환 값

좌표가 뒤바뀐 기하 도형입니다. 반환 타입은 입력 타입과 동일합니다. Point 또는 Ring 또는 Polygon 또는 MultiPolygon 또는 LineString 또는 MultiLineString 또는 Geometry

예제

basic_point

SELECT flipCoordinates((1.0, 2.0));

(2.0, 1.0)

ring

SELECT flipCoordinates([(1.0, 2.0), (3.0, 4.0)]);

[(2.0, 1.0), (4.0, 3.0)]

polygon

SELECT flipCoordinates([[(1.0, 2.0), (3.0, 4.0)], [(5.0, 6.0), (7.0, 8.0)]]);

[[(2.0, 1.0), (4.0, 3.0)], [(6.0, 5.0), (8.0, 7.0)]]

geometry_wkt

SELECT flipCoordinates(readWkt('POINT(10 20)'));

(20, 10)

geometry_polygon_wkt

SELECT flipCoordinates(readWkt('POLYGON((0 0, 5 0, 5 5, 0 5, 0 0))'));

[[(0, 0), (0, 5), (5, 5), (5, 0), (0, 0)]]

formatQuery

도입된 버전: v

지정된 SQL 쿼리를 형식화한 버전을 반환하며, 필요에 따라 여러 줄로 표현됩니다. 파싱 오류가 발생하는 경우 예외를 발생시킵니다. [example:multiline]

구문

formatQuery(query)

인자

• query — 형식화할 SQL 쿼리입니다. String

반환 값

형식화된 쿼리입니다. String

예시

여러 줄

SELECT formatQuery('select a,    b FRom tab WHERE a > 3 and  b < 3');

SELECT
    a,
    b
FROM tab
WHERE (a > 3) AND (b < 3)

formatQueryOrNull

도입 버전: v

지정된 SQL 쿼리를 포맷팅한 결과를 반환하며, 이 결과는 여러 줄이 될 수 있습니다. 구문 분석 오류가 발생하면 NULL을 반환합니다. [example:multiline]

구문

formatQueryOrNull(query)

인수

• query — 포맷할 SQL 쿼리입니다. String

반환 값

포맷된 쿼리 String

예시

여러 줄

SELECT formatQuery('select a,    b FRom tab WHERE a > 3 and  b < 3');

SELECT
    a,
    b
FROM tab
WHERE (a > 3) AND (b < 3)

formatQuerySingleLine

도입 버전: v

formatQuery()와 같지만, 반환되는 서식이 적용된 문자열에는 줄 바꿈이 포함되지 않습니다. 구문 분석 오류가 발생하면 예외를 던집니다. [example:multiline]

구문

formatQuerySingleLine(query)

인수

• query — 서식을 지정할 SQL 쿼리입니다. String

반환 값

서식이 지정된 쿼리 String

예시

multiline

SELECT formatQuerySingleLine('select a,    b FRom tab WHERE a > 3 and  b < 3');

SELECT a, b FROM tab WHERE (a > 3) AND (b < 3)

formatQuerySingleLineOrNull

도입 버전: v

formatQuery()와 비슷하지만, 반환되는 포맷된 문자열에는 줄바꿈이 포함되지 않습니다. 파싱 오류가 발생하면 NULL을 반환합니다. [example:multiline]

구문

formatQuerySingleLineOrNull(query)

인수

• query — 서식을 지정할 SQL 쿼리. String

반환 값

서식이 지정된 쿼리 String

예시

여러 줄

SELECT formatQuerySingleLine('select a,    b FRom tab WHERE a > 3 and  b < 3');

SELECT a, b FROM tab WHERE (a > 3) AND (b < 3)

formatReadableDecimalSize

도입 버전: v22.11

크기(바이트 수)가 주어지면, 이 FUNCTION은 사람이 읽기 쉬운 반올림된 크기에 단위 접미사(KB, MB 등)를 붙인 문자열을 반환합니다.

이 FUNCTION의 역연산은 parseReadableSize입니다.

구문

formatReadableDecimalSize(x)

인수

• x — 바이트 단위 크기. UInt64

반환 값

접미사가 포함된 읽기 쉬운 반올림된 크기를 문자열로 반환합니다. String

예시

파일 크기 형식 지정

SELECT
    arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
    formatReadableDecimalSize(filesize_bytes) AS filesize

┌─filesize_bytes─┬─filesize───┐
│              1 │ 1.00 B     │
│           1024 │ 1.02 KB    │
│        1048576 │ 1.05 MB    │
│      192851925 │ 192.85 MB  │
└────────────────┴────────────┘

formatReadableQuantity

도입 버전: v20.10

주어진 숫자에 대해, 이 함수는 해당 숫자를 반올림하고 접미사(천, 백만, 십억 등)를 붙인 문자열로 반환합니다.

이 함수는 입력으로 임의의 숫자형 타입을 허용하지만, 내부적으로는 이를 Float64로 캐스팅합니다. 값이 매우 큰 경우 결과가 최적이 아닐 수 있습니다.

구문

formatReadableQuantity(x)

인자

• x — 형식화할 숫자. UInt64

반환 값

접미사가 붙은 반올림된 숫자를 문자열로 반환합니다. String

예제

접미사가 있는 숫자 형식 지정

SELECT
    arrayJoin([1024, 1234 * 1000, (4567 * 1000) * 1000, 98765432101234]) AS number,
    formatReadableQuantity(number) AS number_for_humans

┌─────────number─┬─number_for_humans─┐
│           1024 │ 1.02 thousand     │
│        1234000 │ 1.23 million      │
│     4567000000 │ 4.57 billion      │
│ 98765432101234 │ 98.77 trillion    │
└────────────────┴───────────────────┘

formatReadableSize

도입된 버전: v1.1

바이트 단위의 크기가 주어지면, 이 함수는 접미사(KiB, MiB 등)가 포함된 사람이 읽기 쉬운 반올림된 크기를 문자열로 반환합니다.

이 함수의 반대 연산은 parseReadableSize, parseReadableSizeOrZero, parseReadableSizeOrNull입니다. 이 함수는 입력으로 모든 숫자형 데이터 타입을 허용하지만, 내부적으로는 이를 Float64로 캐스팅합니다. 매우 큰 값에 대해서는 결과가 최적이 아닐 수 있습니다.

문법

formatReadableSize(x)

별칭: FORMAT_BYTES

인수

• x — 바이트 단위의 크기. UInt64

반환 값

접미사가 포함된, 사람이 읽기 쉬운 반올림된 크기를 문자열로 반환합니다. String

예제

파일 크기 형식 지정

SELECT
    arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
    formatReadableSize(filesize_bytes) AS filesize

┌─filesize_bytes─┬─filesize───┐
│              1 │ 1.00 B     │
│           1024 │ 1.00 KiB   │
│        1048576 │ 1.00 MiB   │
│      192851925 │ 183.92 MiB │
└────────────────┴────────────┘

formatReadableTimeDelta

도입 버전: v20.12

시간 간격(델타)을 초 단위로 입력하면, 이 함수는 연/월/일/시/분/초/밀리초/마이크로초/나노초 단위가 포함된 시간 델타를 문자열로 반환합니다.

이 함수는 입력으로 임의의 숫자형 데이터 타입을 허용하지만, 내부적으로는 Float64로 캐스팅합니다. 매우 큰 값에 대해서는 결과가 최적이 아닐 수 있습니다.

구문

formatReadableTimeDelta(column[, maximum_unit, minimum_unit])

인수

• column — 시간 차이를 나타내는 숫자형 컬럼입니다. Float64
• maximum_unit — 선택 사항입니다. 표시할 최대 단위입니다. 허용되는 값: nanoseconds, microseconds, milliseconds, seconds, minutes, hours, days, months, years. 기본값: years입니다. const String
• minimum_unit — 선택 사항입니다. 표시할 최소 단위입니다. 더 작은 단위는 모두 버립니다. 허용되는 값: nanoseconds, microseconds, milliseconds, seconds, minutes, hours, days, months, years. 명시적으로 지정한 값이 maximum_unit보다 크면 예외가 발생합니다. 기본값: maximum_unit이 seconds 이상이면 seconds, 그렇지 않으면 nanoseconds입니다. const String

반환 값

시간 차이를 문자열로 반환합니다. String

예시

사용 예시

SELECT
    arrayJoin([100, 12345, 432546534]) AS elapsed,
    formatReadableTimeDelta(elapsed) AS time_delta

┌────elapsed─┬─time_delta─────────────────────────────────────────────────────┐
│        100 │ 1 minute and 40 seconds                                        │
│      12345 │ 3 hours, 25 minutes and 45 seconds                             │
│  432546534 │ 13 years, 8 months, 17 days, 7 hours, 48 minutes and 54 seconds│
└────────────┴────────────────────────────────────────────────────────────────┘

최대 단위 사용

SELECT
    arrayJoin([100, 12345, 432546534]) AS elapsed,
    formatReadableTimeDelta(elapsed, 'minutes') AS time_delta

┌────elapsed─┬─time_delta─────────────────────────────────────────────────────┐
│        100 │ 1 minute and 40 seconds                                         │
│      12345 │ 205 minutes and 45 seconds                                      │
│  432546534 │ 7209108 minutes and 54 seconds                                  │
└────────────┴─────────────────────────────────────────────────────────────────┘

generateRandomStructure

도입된 버전: v23.5

column1_name column1_type, column2_name column2_type, ... 형식의 임의 테이블 구조를 생성합니다.

구문

generateRandomStructure([number_of_columns, seed])

인수

• number_of_columns — 결과 테이블 구조에서 사용할 컬럼 수입니다. 0 또는 Null로 설정하면 컬럼 수는 1에서 128 사이에서 무작위로 결정됩니다. 기본값: Null. UInt64
• seed — 안정적인 결과를 재현하기 위한 랜덤 시드입니다. seed가 지정되지 않았거나 Null로 설정된 경우 임의로 생성됩니다. UInt64

반환값

무작위로 생성된 테이블 구조입니다. String

예시

사용 예시

SELECT generateRandomStructure()

c1 Decimal32(5), c2 Date, c3 Tuple(LowCardinality(String), Int128, UInt64, UInt16, UInt8, IPv6), c4 Array(UInt128), c5 UInt32, c6 IPv4, c7 Decimal256(64), c8 Decimal128(3), c9 UInt256, c10 UInt64, c11 DateTime

지정된 개수의 컬럼 사용

SELECT generateRandomStructure(1)

c1 Map(UInt256, UInt16)

지정된 시드로

SELECT generateRandomStructure(NULL, 33)

c1 DateTime, c2 Enum8('c2V0' = 0, 'c2V1' = 1, 'c2V2' = 2, 'c2V3' = 3), c3 LowCardinality(Nullable(FixedString(30))), c4 Int16, c5 Enum8('c5V0' = 0, 'c5V1' = 1, 'c5V2' = 2, 'c5V3' = 3), c6 Nullable(UInt8), c7 String, c8 Nested(e1 IPv4, e2 UInt8, e3 UInt16, e4 UInt16, e5 Int32, e6 Map(Date, Decimal256(70)))

generateSerialID

도입 버전: v25.1

이전 카운터 값부터 시작하는 연속된 번호를 생성하여 반환합니다. 이 함수는 문자열 인수인 「시리즈 식별자」와 선택적인 시작 값을 인수로 받습니다. 서버에는 Keeper가 구성되어 있어야 합니다. 시리즈는 서버 설정의 series_keeper_path에서 구성할 수 있는 경로 아래의 Keeper 노드에 저장됩니다.

구문

generateSerialID(series_identifier[, start_value])

인수

• series_identifier — 시리즈 식별자 const String
• start_value — 선택 옵션입니다. 카운터의 시작 값입니다. 기본값은 0입니다. 참고로, 이 값은 새 시리즈를 생성할 때만 사용되며 시리즈가 이미 존재하는 경우에는 무시됩니다. UInt*

반환 값

이전 카운터 값부터 시작하는 연속된 숫자를 반환합니다. UInt64

예제

첫 번째 호출

SELECT generateSerialID('id1')

┌─generateSerialID('id1')──┐
│                        1 │
└──────────────────────────┘

두 번째 호출

SELECT generateSerialID('id1')

┌─generateSerialID('id1')──┐
│                        2 │
└──────────────────────────┘

컬럼 호출

SELECT *, generateSerialID('id1') FROM test_table

┌─CounterID─┬─UserID─┬─ver─┬─generateSerialID('id1')──┐
│         1 │      3 │   3 │                        3 │
│         1 │      1 │   1 │                        4 │
│         1 │      2 │   2 │                        5 │
│         1 │      5 │   5 │                        6 │
│         1 │      4 │   4 │                        7 │
└───────────┴────────┴─────┴──────────────────────────┘

시작 값 사용

SELECT generateSerialID('id2', 100)

┌─generateSerialID('id2', 100)──┐
│                           100 │
└───────────────────────────────┘

시작 값을 지정한 두 번째 호출

SELECT generateSerialID('id2', 100)

┌─generateSerialID('id2', 100)──┐
│                           101 │
└───────────────────────────────┘

getClientHTTPHeader

도입 버전: v24.5

HTTP 헤더의 값을 가져옵니다. 해당 헤더가 없거나 현재 요청이 HTTP 인터페이스를 통해 수행되지 않는 경우, 함수는 빈 문자열을 반환합니다. 일부 HTTP 헤더(예: Authentication, X-ClickHouse-*)는 제한됩니다.

참고

allow_get_client_http_header 설정이 필요함

이 함수를 사용하려면 allow_get_client_http_header 설정을 활성화해야 합니다. Cookie와 같이 민감한 정보를 포함할 수 있는 헤더가 있기 때문에, 보안상의 이유로 이 설정은 기본적으로 비활성화되어 있습니다.

이 함수에서 HTTP 헤더는 대소문자를 구분합니다. 함수가 분산 쿼리(distributed query) 컨텍스트에서 사용되는 경우, 이니시에이터 노드에서만 빈 문자열이 아닌 결과를 반환합니다.

문법

getClientHTTPHeader(name)

매개변수

• name — HTTP 헤더 이름. String

반환값

헤더의 값을 반환합니다. String

예시

사용 예시

SELECT getClientHTTPHeader('Content-Type');

┌─getClientHTTPHeader('Content-Type')─┐
│ application/x-www-form-urlencoded   │
└─────────────────────────────────────┘

getMacro

도입 버전: v20.1

서버 구성 파일에 정의된 매크로의 값을 반환합니다. 매크로는 구성 파일의 <macros> 섹션에 정의되며, 호스트 이름이 복잡하더라도 서버를 구분하기 위한 편리한 이름으로 사용할 수 있습니다. 함수가 분산 테이블(distributed table) 컨텍스트에서 실행되는 경우, 각 세그먼트에 해당하는 값을 포함하는 일반 컬럼을 생성합니다.

구문

getMacro(name)

인수

• name — 조회할 매크로의 이름입니다. const String

반환 값

지정된 매크로의 값을 반환합니다. String

예제

기본 사용법

SELECT getMacro('test');

┌─getMacro('test')─┐
│ Value            │
└──────────────────┘

getMaxTableNameLengthForDatabase

도입된 버전: v

지정된 데이터베이스에서 테이블 이름의 최대 길이를 반환합니다.

구문

getMaxTableNameLengthForDatabase(database_name)

인수

• database_name — 지정된 데이터베이스의 이름. String

반환 값

최대 테이블 이름의 길이를 나타내는 정수(Integer)를 반환합니다.

예시

일반적인 예

SELECT getMaxTableNameLengthForDatabase('default');

┌─getMaxTableNameLengthForDatabase('default')─┐
            │                                         206 │
            └─────────────────────────────────────────────┘

getMergeTreeSetting

도입 버전: v25.6

MergeTree 설정의 현재 값을 반환합니다.

구문

getMergeTreeSetting(setting_name)

인수

• setting_name — 설정 이름입니다. String

반환 값

MergeTree 설정의 현재 값을 반환합니다.

예시

사용 예시

SELECT getMergeTreeSetting('index_granularity');

┌─getMergeTreeSetting('index_granularity')─┐
│                                     8192 │
└──────────────────────────────────────────┘

getOSKernelVersion

도입된 버전: v21.11

OS 커널 버전을 나타내는 문자열을 반환합니다.

구문

getOSKernelVersion()

인수

• 없음.

반환값

현재 OS 커널 버전을 반환합니다. String

예제

사용 예제

SELECT getOSKernelVersion();

┌─getOSKernelVersion()────┐
│ Linux 4.15.0-55-generic │
└─────────────────────────┘

getServerPort

도입 버전: v21.10

지정된 프로토콜에 대해 서버가 사용하는 포트 번호를 반환합니다.

구문

getServerPort(port_name)

인수

• port_name — 포트 이름. String

반환값

서버 포트 번호를 반환합니다. UInt16

예시

사용 예시

SELECT getServerPort('tcp_port');

┌─getServerPort('tcp_port')─┐
│                      9000 │
└───────────────────────────┘

getServerSetting

도입된 버전: v25.6

서버 설정 이름을 지정하면 해당 설정의 현재 값을 반환합니다.

구문

getServerSetting(setting_name')

인자

• setting_name — 서버 설정의 이름입니다. String

반환값

서버 설정의 현재 값을 반환합니다. Any

예시

사용 예시

SELECT getServerSetting('allow_use_jemalloc_memory');

┌─getServerSetting('allow_use_jemalloc_memory')─┐
│ true                                          │
└───────────────────────────────────────────────┘

getSetting

도입 버전: v20.7

현재 설정 값을 반환합니다.

구문

getSetting(setting_name)

인수

• setting_Name — 설정 이름. const String

반환 값

설정의 현재 값을 반환합니다. Any

예시

사용 예시

SELECT getSetting('enable_analyzer');
SET enable_analyzer = false;
SELECT getSetting('enable_analyzer');

┌─getSetting('⋯_analyzer')─┐
│ true                     │
└──────────────────────────┘
┌─getSetting('⋯_analyzer')─┐
│ false                    │
└──────────────────────────┘

getSettingOrDefault

도입된 버전: v24.10

설정의 현재 값을 반환하며, 현재 프로필에서 해당 설정이 지정되지 않은 경우 두 번째 인수에 지정된 기본값을 반환합니다.

구문

getSettingOrDefault(setting_name, default_value)

인수

• setting_name — 설정 이름. String
• default_value — custom_setting이 설정되지 않았을 때 반환할 값입니다. 값은 어떤 데이터 타입이든 사용할 수 있으며 Null일 수도 있습니다.

반환 값

지정된 설정의 현재 값 또는 해당 설정이 설정되지 않은 경우 default_value를 반환합니다.

예시

사용 예시

SELECT getSettingOrDefault('custom_undef1', 'my_value');
SELECT getSettingOrDefault('custom_undef2', 100);
SELECT getSettingOrDefault('custom_undef3', NULL);

my_value
100
NULL

getSizeOfEnumType

도입: v1.1

지정된 Enum에 포함된 필드 수를 반환합니다.

구문

getSizeOfEnumType(x)

인수

• x — Enum 타입 값입니다. Enum

반환 값

Enum 입력 값을 갖는 필드의 수를 반환합니다. UInt8/16

예시

사용 예시

SELECT getSizeOfEnumType(CAST('a' AS Enum8('a' = 1, 'b' = 2))) AS x;

┌─x─┐
│ 2 │
└───┘

getSubcolumn

도입 버전: v

표현식 또는 식별자와 서브컬럼 이름을 나타내는 상수 문자열을 인수로 받습니다.

표현식에서 요청된 서브컬럼을 추출하여 반환합니다.

구문

인수

• 없음.

반환값

예제

getSubcolumn

SELECT getSubcolumn(array_col, 'size0'), getSubcolumn(tuple_col, 'elem_name')

getTypeSerializationStreams

도입 버전: v22.6

데이터 유형의 스트림 경로를 열거합니다. 이 FUNCTION은 개발 목적의 사용을 위해 설계되었습니다.

구문

getTypeSerializationStreams(col)

인수 (Arguments)

• col — 데이터 타입을 감지할 컬럼 또는 데이터 타입을 문자열로 표현한 값. Any

반환 값 (Returned value)

모든 직렬화 서브스트림 경로를 포함하는 배열을 반환합니다. Array(String)

예시 (Examples)

tuple

SELECT getTypeSerializationStreams(tuple('a', 1, 'b', 2))

['{TupleElement(1), Regular}','{TupleElement(2), Regular}','{TupleElement(3), Regular}','{TupleElement(4), Regular}']

맵

SELECT getTypeSerializationStreams('Map(String, Int64)')

['{ArraySizes}','{ArrayElements, TupleElement(keys), Regular}','{ArrayElements, TupleElement(values), Regular}']

globalVariable

도입 버전: v20.5

상수 문자열 인자를 받아 해당 이름을 가진 전역 변수의 값을 반환합니다. 이 FUNCTION은 MySQL과의 호환성을 위한 것이며, 일반적인 ClickHouse 운영에서는 필요하지 않으며 유용하지도 않습니다. 일부 더미 전역 변수만 정의되어 있습니다.

구문

globalVariable(name)

인수

• name — 전역 변수의 이름. String

반환값

변수 name의 값을 반환합니다. Any

예시

globalVariable

SELECT globalVariable('max_allowed_packet')

67108864

hasColumnInTable

도입된 버전: v1.1

데이터베이스 테이블에 특정 컬럼이 존재하는지 확인합니다. 중첩된 데이터 구조의 요소에 대해서는 함수가 해당 컬럼의 존재 여부를 확인합니다. 중첩된 데이터 구조 자체에 대해서는 함수가 0을 반환합니다.

구문

hasColumnInTable([hostname[, username[, password]],]database, table, column)

인수

• database — 데이터베이스 이름. const String
• table — 테이블 이름. const String
• column — 컬럼 이름. const String
• hostname — 선택적입니다. 검사할 원격 서버 이름. const String
• username — 선택적입니다. 원격 서버 사용자 이름. const String
• password — 선택적입니다. 원격 서버 비밀번호. const String

반환 값

지정된 컬럼이 존재하면 1, 존재하지 않으면 0을 반환합니다. UInt8

예시

존재하는 컬럼 확인

SELECT hasColumnInTable('system','metrics','metric')

1

존재하지 않는 컬럼 확인

SELECT hasColumnInTable('system','metrics','non-existing_column')

0

hasThreadFuzzer

도입된 버전: v20.6

thread fuzzer(스레드 퍼저)가 활성화되어 있는지 여부를 반환합니다. 이 FUNCTION은 테스트와 디버깅에만 유용합니다.

구문

hasThreadFuzzer()

인수

• 없음.

반환 값

Thread Fuzzer가 활성화되어 있는지 여부를 반환합니다. UInt8

예제

Thread Fuzzer 상태 확인

SELECT hasThreadFuzzer()

┌─hasThreadFuzzer()─┐
│                 0 │
└───────────────────┘

hostName

도입된 버전: v20.5

이 함수가 실행된 호스트 이름을 반환합니다. 함수가 원격 서버에서 실행되는 경우(분산 처리)에는 원격 서버의 이름을 반환합니다. 함수가 분산 테이블 컨텍스트에서 실행되는 경우, 각 세그먼트에 해당하는 값을 가진 일반 컬럼을 생성합니다. 그 밖의 경우에는 상수 값을 반환합니다.

구문

hostName()

별칭: hostname

인수

• 없음.

반환 값

호스트 이름을 반환합니다. String

예시

사용 예

SELECT hostName()

┌─hostName()─┐
│ clickhouse │
└────────────┘

icebergBucket

도입 버전: v25.5

Iceberg 버킷 변환 로직을 구현합니다.

구문

icebergBucket(N, value)

인수

• N — 버킷 개수(모듈로 기준값). const (U)Int*
• value — 변환할 원본 값. (U)Int* 또는 Bool 또는 Decimal 또는 Float* 또는 String 또는 FixedString 또는 UUID 또는 Date 또는 Time 또는 DateTime

반환 값

원본 값의 32비트 해시를 반환합니다. Int32

예시

예시

SELECT icebergBucket(5, 1.0 :: Float32)

4

icebergTruncate

도입된 버전: v25.3

https://iceberg.apache.org/spec/#truncate-transform-details 에 설명된 Iceberg truncate 변환(truncate transform)의 로직을 구현합니다.

구문

icebergTruncate(N, value)

인자

• value — 변환할 값입니다. String 또는 (U)Int* 또는 Decimal

반환값

인자와 동일한 타입입니다.

예제

예제

SELECT icebergTruncate(3, 'iceberg')

ice

identity

도입 버전: v1.1

이 함수는 전달된 인수를 그대로 반환합니다. 디버깅과 테스트에 유용합니다. 인덱스 사용을 우회하여 전체 스캔 시의 성능을 확인하는 데 사용할 수 있습니다. 쿼리 분석기는 사용할 인덱스를 찾을 때 identity 함수 내부의 모든 내용을 무시하며, 상수 폴딩도 비활성화합니다.

문법

identity(x)

인수

• x — 입력값. Any

반환 값

입력값을 변경하지 않고 그대로 반환합니다. Any

예시

사용 예시

SELECT identity(42)

42

ignore

도입 버전: v1.1

임의의 인수를 받아 무조건 0을 반환합니다.

구문

ignore(x)

인수

• x — 사용되지는 않지만, 구문 오류를 피하기 위해 인수로만 전달되는 입력 값입니다. Any

반환 값

항상 0을 반환합니다. UInt8

예시

사용 예시

SELECT ignore(0, 'ClickHouse', NULL)

┌─ignore(0, 'ClickHouse', NULL)─┐
│                             0 │
└───────────────────────────────┘

indexHint

도입 버전: v1.1

이 함수는 디버깅과 내부 동작 확인을 위한 함수입니다. 인수를 무시하며 항상 1을 반환합니다. 인수는 평가되지 않습니다.

인덱스를 분석하는 동안 이 함수의 인수는 indexHint로 감싸져 있지 않은 것으로 가정됩니다. 이를 통해 해당 조건으로 인덱스 범위의 데이터를 선택하되, 이후 이 조건에 따른 추가 필터링 없이 선택할 수 있습니다. ClickHouse의 인덱스는 희소 인덱스이며, indexHint를 사용하면 같은 조건을 직접 지정하는 것보다 더 많은 데이터를 반환하게 됩니다.

설명

다음과 같이 실행한다고 가정합니다:

SELECT * FROM test WHERE key = 123;

ClickHouse는 두 가지 작업을 수행합니다:

1. 인덱스를 사용하여 어떤 그래뉼(약 8,192행으로 이루어진 블록)에 key = 123이 포함될 수 있는지 찾습니다.
2. 해당 그래뉼을 읽어서 각 행을 하나씩 필터링해 key = 123인 행만 반환합니다.

따라서 디스크에서 8,192행을 읽더라도 실제로 일치하는 행 1개만 반환합니다.

indexHint를 사용하여 다음과 같이 실행하면:

SELECT * FROM test WHERE indexHint(key = 123);

ClickHouse는 한 가지 작업만 수행합니다:

1. 인덱스를 사용하여 어떤 그래뉼에 key = 123이 포함될 수 있는지 찾고, 해당 그래뉼의 모든 행을 필터링 없이 그대로 반환합니다.

이 경우 8,192행 전체를 반환하며, 그 안에는 key = 456, key = 789 등도 포함됩니다. (같은 그래뉼에 저장되어 있던 모든 데이터가 반환됩니다.) indexHint()는 성능 향상을 위한 것이 아닙니다. ClickHouse 인덱스가 어떻게 동작하는지 디버깅하고 이해하기 위한 용도입니다:

• 해당 조건이 어떤 그래뉼을 선택하는가?
• 해당 그래뉼에는 몇 행이 포함되어 있는가?
• 사용 중인 인덱스가 효과적으로 사용되고 있는가?

주의: indexHint 함수로 쿼리를 최적화하는 것은 불가능합니다. indexHint 함수는 쿼리 분석에 추가 정보를 제공하지 않으므로 쿼리를 최적화하지 않습니다. indexHint 함수 안에 식을 넣는다고 해서, indexHint 없이 식만 사용하는 것보다 나아지는 점은 전혀 없습니다. indexHint 함수는 내부 동작 확인과 디버깅 용도로만 사용할 수 있으며 성능을 향상시키지 않습니다. ClickHouse 기여자가 아닌 사람이 indexHint를 사용하는 것을 본다면, 잘못 사용하고 있을 가능성이 크므로 제거하는 것이 좋습니다.

구문

indexHint(expression)

인자

• expression — 인덱스 범위를 선택하기 위한 임의의 식입니다. Expression

반환 값

모든 경우에 1을 반환합니다. UInt8

예시

날짜 필터링을 사용한 예시

SELECT FlightDate AS k, count() FROM ontime WHERE indexHint(k = '2025-09-15') GROUP BY k ORDER BY k ASC;

┌──────────k─┬─count()─┐
│ 2025-09-14 │    7071 │
│ 2025-09-15 │   16428 │
│ 2025-09-16 │    1077 │
│ 2025-09-30 │    8167 │
└────────────┴─────────┘

initialQueryID

도입 버전: v1.1

초기 쿼리의 ID를 반환합니다. 쿼리의 다른 매개변수는 system.query_log의 initial_query_id 필드에서 추출할 수 있습니다.

queryID 함수와 달리, initialQueryID는 서로 다른 세그먼트에서 동일한 결과를 반환합니다.

구문

initialQueryID()

별칭: initial_query_id

인수

• 없음.

반환 값

현재 초기 쿼리의 ID를 반환합니다. String

예시

사용 예시

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT initialQueryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

┌─count(DISTINCT t)─┐
│                 1 │
└───────────────────┘

initialQueryStartTime

도입 버전: v25.4

현재 쿼리의 초기 실행 시작 시간을 반환합니다. initialQueryStartTime은 서로 다른 세그먼트에서도 동일한 결과를 반환합니다.

구문

initialQueryStartTime()

별칭: initial_query_start_time

인수

• 없음.

반환 값

현재 쿼리의 최초 시작 시간을 반환합니다. DateTime

예시

사용 예

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT initialQueryStartTime() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

┌─count(DISTINCT t)─┐
│                 1 │
└───────────────────┘

initializeAggregation

도입된 버전: v20.6

단일 값을 기반으로 집계 함수의 결과를 계산합니다. 이 함수는 콤비네이터 -State가 적용된 집계 함수를 초기화하는 데 사용할 수 있습니다. 집계 함수의 상태(state)를 생성하여 AggregateFunction 타입의 컬럼에 삽입하거나, 초기화된 집계를 기본값으로 사용할 수 있습니다.

문법

initializeAggregation(aggregate_function, arg1[, arg2, ...])

인수

• aggregate_function — 초기화할 집계 함수 이름입니다. String
• arg1[, arg2, ...] — 집계 함수의 인수입니다. Any

반환값

함수에 전달된 각 행에 대한 집계 결과를 반환합니다. 반환 타입은 initializeAggregation이 첫 번째 인수로 받는 함수의 반환 타입과 동일합니다. Any

예시

uniqState를 사용한 기본 사용 예

SELECT uniqMerge(state) FROM (SELECT initializeAggregation('uniqState', number % 3) AS state FROM numbers(10000));

┌─uniqMerge(state)─┐
│                3 │
└──────────────────┘

sumState 및 finalizeAggregation과 함께 사용하기

SELECT finalizeAggregation(state), toTypeName(state) FROM (SELECT initializeAggregation('sumState', number % 3) AS state FROM numbers(5));

┌─finalizeAggregation(state)─┬─toTypeName(state)─────────────┐
│                          0 │ AggregateFunction(sum, UInt8) │
│                          1 │ AggregateFunction(sum, UInt8) │
│                          2 │ AggregateFunction(sum, UInt8) │
│                          0 │ AggregateFunction(sum, UInt8) │
│                          1 │ AggregateFunction(sum, UInt8) │
└────────────────────────────┴───────────────────────────────┘

isConstant

도입 버전: v20.3

인수가 상수 표현식인지 여부를 반환합니다. 상수 표현식이란 실행 이전, 즉 쿼리 분석 단계에서 결과를 알 수 있는 표현식을 의미합니다. 예를 들어, 리터럴을 사용하는 표현식은 상수 표현식입니다. 이 함수는 주로 개발, 디버깅 및 시연 목적으로 사용됩니다.

구문

isConstant(x)

인수

• x — 확인할 표현식입니다. Any

반환값

x가 상수이면 1, 상수가 아니면 0을 반환합니다. UInt8

예제

상수 표현식

SELECT isConstant(x + 1)
FROM (SELECT 43 AS x)

┌─isConstant(plus(x, 1))─┐
│                      1 │
└────────────────────────┘

함수에서 사용하는 상수

WITH 3.14 AS pi
SELECT isConstant(cos(pi))

┌─isConstant(cos(pi))─┐
│                   1 │
└─────────────────────┘

상수가 아닌 표현식

SELECT isConstant(number)
FROM numbers(1)

┌─isConstant(number)─┐
│                  0 │
└────────────────────┘

now() 함수의 동작

SELECT isConstant(now())

┌─isConstant(now())─┐
│                 1 │
└───────────────────┘

isDecimalOverflow

도입된 버전: v20.8

지정된 정밀도의 Decimal 데이터 타입에 수용할 수 있는 자릿수를 초과했는지 확인합니다.

구문

isDecimalOverflow(value[, precision])

인수

• value — 검사할 Decimal 값. Decimal
• precision — 선택 사항입니다. Decimal 유형의 정밀도(precision)입니다. 생략하면 첫 번째 인수의 초기 정밀도가 사용됩니다. UInt8

반환 값

Decimal 값의 자릿수가 해당 정밀도로 허용되는 자릿수보다 많으면 1을, Decimal 값이 지정된 정밀도를 충족하면 0을 반환합니다. UInt8

예시

사용 예시

SELECT isDecimalOverflow(toDecimal32(1000000000, 0), 9),
       isDecimalOverflow(toDecimal32(1000000000, 0)),
       isDecimalOverflow(toDecimal32(-1000000000, 0), 9),
       isDecimalOverflow(toDecimal32(-1000000000, 0));

┌─isDecimalOverflow(toDecimal32(1000000000, 0), 9)─┬─isDecimalOverflow(toDecimal32(1000000000, 0))─┬─isDecimalOverflow(toDecimal32(-1000000000, 0), 9)─┬─isDecimalOverflow(toDecimal32(-1000000000, 0))─┐
│                                                1 │                                             1 │                                                 1 │                                              1 │
└──────────────────────────────────────────────────┴───────────────────────────────────────────────┴───────────────────────────────────────────────────┴────────────────────────────────────────────────┘

joinGet

도입된 버전: v18.16

딕셔너리에서 데이터를 추출하는 것과 동일한 방식으로 테이블에서 데이터를 추출할 수 있습니다. 지정된 조인 키를 사용하여 Join 테이블에서 데이터를 가져옵니다.

참고

ENGINE = Join(ANY, LEFT, <join_keys>) 구문으로 생성된 테이블만 지원합니다.

구문

joinGet(join_storage_table_name, value_column, join_keys)

인수

• join_storage_table_name — 검색을 수행할 위치를 지정하는 식별자입니다. 이 식별자는 기본 데이터베이스에서 검색됩니다(설정 파일의 default_database 파라미터 참조). 기본 데이터베이스를 재정의하려면 USE database_name 쿼리를 사용하거나 database_name.table_name과 같이 점(.)을 사용하여 데이터베이스와 테이블을 함께 지정하십시오. String
• value_column — 필요한 데이터를 포함하는 테이블의 컬럼 이름입니다. const String
• join_keys — 조인에 사용할 키들의 목록입니다. Any

반환 값

키 목록에 대응하는 값들의 목록을 반환합니다. Any

예시

사용 예시

CREATE TABLE db_test.id_val(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id);
INSERT INTO db_test.id_val VALUES (1,11)(2,12)(4,13);

SELECT joinGet(db_test.id_val, 'val', toUInt32(1));

┌─joinGet(db_test.id_val, 'val', toUInt32(1))─┐
│                                          11 │
└─────────────────────────────────────────────┘

현재 데이터베이스 테이블 사용

USE db_test;
SELECT joinGet(id_val, 'val', toUInt32(2));

┌─joinGet(id_val, 'val', toUInt32(2))─┐
│                                  12 │
└─────────────────────────────────────┘

배열을 JOIN 키로 사용하기

CREATE TABLE some_table (id1 UInt32, id2 UInt32, name String) ENGINE = Join(ANY, LEFT, id1, id2);
INSERT INTO some_table VALUES (1, 11, 'a') (2, 12, 'b') (3, 13, 'c');

SELECT joinGet(some_table, 'name', 1, 11);

┌─joinGet(some_table, 'name', 1, 11)─┐
│ a                                  │
└────────────────────────────────────┘

joinGetOrNull

도입: v20.4

딕셔너리에서 데이터를 추출하는 것과 동일한 방식으로 테이블에서 데이터를 추출할 수 있습니다. 지정된 조인 키를 사용하여 Join 테이블에서 데이터를 가져옵니다. joinGet과는 달리 키가 존재하지 않을 때 NULL을 반환합니다.

참고

ENGINE = Join(ANY, LEFT, <join_keys>) 구문으로 생성된 테이블만 지원합니다.

문법

joinGetOrNull(join_storage_table_name, value_column, join_keys)

인수

• join_storage_table_name — 검색을 수행할 위치를 나타내는 식별자입니다. 이 식별자는 기본 데이터베이스에서 검색됩니다(구성 파일의 default_database 매개변수 참조). 기본 데이터베이스를 변경하려면 USE database_name 쿼리를 사용하거나 database_name.table_name과 같이 점을 사용해 데이터베이스와 테이블을 지정합니다. String
• value_column — 필요한 데이터를 포함하는 테이블의 컬럼 이름입니다. const String
• join_keys — 조인 키 목록입니다. Any

반환 값

키 목록에 해당하는 값 목록을 반환하며, 키를 찾을 수 없는 경우 NULL을 반환합니다. Any

예시

사용 예시

CREATE TABLE db_test.id_val(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id);
INSERT INTO db_test.id_val VALUES (1,11)(2,12)(4,13);

SELECT joinGetOrNull(db_test.id_val, 'val', toUInt32(1)), joinGetOrNull(db_test.id_val, 'val', toUInt32(999));

┌─joinGetOrNull(db_test.id_val, 'val', toUInt32(1))─┬─joinGetOrNull(db_test.id_val, 'val', toUInt32(999))─┐
│                                                11 │                                                ᴺᵁᴸᴸ │
└───────────────────────────────────────────────────┴─────────────────────────────────────────────────────┘

lowCardinalityIndices

도입 버전: v18.12

LowCardinality 컬럼의 딕셔너리에서 값의 위치를 반환합니다. 위치는 1부터 시작합니다. LowCardinality는 파트별 딕셔너리를 사용하므로, 이 함수는 동일한 값이라도 서로 다른 파트에서 서로 다른 위치를 반환할 수 있습니다.

구문

lowCardinalityIndices(col)

인수

• col — 낮은 카디널리티 컬럼. LowCardinality

반환 값

현재 파트의 딕셔너리에서 해당 값의 위치를 나타냅니다. UInt64

예제

사용 예제

DROP TABLE IF EXISTS test;
CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;

-- create two parts:

INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');
INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');

SELECT s, lowCardinalityIndices(s) FROM test;

┌─s──┬─lowCardinalityIndices(s)─┐
│ ab │                        1 │
│ cd │                        2 │
│ ab │                        1 │
│ ab │                        1 │
│ df │                        3 │
└────┴──────────────────────────┘
┌─s──┬─lowCardinalityIndices(s)─┐
│ ef │                        1 │
│ cd │                        2 │
│ ab │                        3 │
│ cd │                        2 │
│ ef │                        1 │
└────┴──────────────────────────┘

lowCardinalityKeys

도입 버전: v18.12

LowCardinality 컬럼의 딕셔너리 값을 반환합니다. 블록 크기가 딕셔너리 크기보다 작거나 큰 경우, 결과는 잘리거나 기본값으로 채워집니다. LowCardinality에는 파트별 딕셔너리가 있으므로, 이 함수는 서로 다른 파트에서 서로 다른 딕셔너리 값을 반환할 수 있습니다.

구문

lowCardinalityKeys(col)

인수

• col — 낮은 카디널리티 컬럼. LowCardinality

반환값

딕셔너리의 키를 반환합니다. UInt64

예제

lowCardinalityKeys

DROP TABLE IF EXISTS test;
CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;

-- create two parts:

INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');
INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');

SELECT s, lowCardinalityKeys(s) FROM test;

┌─s──┬─lowCardinalityKeys(s)─┐
│ ef │                       │
│ cd │ ef                    │
│ ab │ cd                    │
│ cd │ ab                    │
│ ef │                       │
└────┴───────────────────────┘
┌─s──┬─lowCardinalityKeys(s)─┐
│ ab │                       │
│ cd │ ab                    │
│ ab │ cd                    │
│ ab │ df                    │
│ df │                       │
└────┴───────────────────────┘

materialize

도입: v1.1

상수를 단일 값을 담고 있는 전체 컬럼으로 변환합니다. 전체 컬럼과 상수는 메모리에서 서로 다르게 표현됩니다. 함수는 일반 인수와 상수 인수에 대해 보통 서로 다른 코드를 실행하지만, 결과는 일반적으로 동일해야 합니다. 이 함수는 이러한 동작을 디버깅하는 데 사용할 수 있습니다.

구문

materialize(x)

인자

• x — 상수입니다. Any

반환 값

상수 값으로 채워진 전체 컬럼을 반환합니다. Any

예시

사용 예시

-- In the example below the `countMatches` function expects a constant second argument.
-- This behaviour can be debugged by using the `materialize` function to turn a constant into a full column,
-- verifying that the function throws an error for a non-constant argument.

SELECT countMatches('foobarfoo', 'foo');
SELECT countMatches('foobarfoo', materialize('foo'));

2
Code: 44. DB::Exception: Received from localhost:9000. DB::Exception: Illegal type of argument #2 'pattern' of function countMatches, expected constant String, got String

minSampleSizeContinuous

도입된 버전: v23.10

두 표본에서 연속형 지표의 평균을 비교하는 A/B 테스트에 필요한 최소 표본 크기를 계산합니다.

이 글에 설명된 공식을 사용합니다. 처리군(treatment)과 대조군(control)의 크기가 동일하다고 가정합니다. 하나의 그룹에 필요한 표본 크기를 반환합니다(즉, 전체 실험에 필요한 표본 크기는 반환값의 2배입니다). 또한 처리군과 대조군에서 테스트 지표의 분산이 동일하다고 가정합니다.

구문

minSampleSizeContinuous(baseline, sigma, mde, power, alpha)

별칭: minSampleSizeContinous

인수

• baseline — 메트릭의 기준값. (U)Int* 또는 Float*
• sigma — 메트릭 기준값의 표준편차. (U)Int* 또는 Float*
• mde — 기준값 대비 최소 탐지 효과(MDE, Minimum Detectable Effect)의 백분율(예: 기준값이 112.25일 때 MDE가 0.03이면 기대되는 값 변화는 112.25 ± 112.25*0.03). (U)Int* 또는 Float*
• power — 테스트에 필요한 통계적 검정력(1 - 제2종 오류 확률). (U)Int* 또는 Float*
• alpha — 테스트에 필요한 유의수준(제1종 오류 확률). (U)Int* 또는 Float*

반환 값

minimum_sample_size, detect_range_lower, detect_range_upper의 3개 요소를 가진 이름이 지정된 Tuple을 반환합니다. 각 요소는 각각 필요한 표본 크기, 반환된 필요한 표본 크기로는 탐지할 수 없는 값 범위의 하한( baseline * (1 - mde) 로 계산), 그리고 반환된 필요한 표본 크기로는 탐지할 수 없는 값 범위의 상한( baseline * (1 + mde) 로 계산)입니다(각 요소 타입: Float64). Tuple(Float64, Float64, Float64)

예시

minSampleSizeContinuous

SELECT minSampleSizeContinuous(112.25, 21.1, 0.03, 0.80, 0.05) AS sample_size

(616.2931945826209,108.8825,115.6175)

minSampleSizeConversion

도입 버전: v22.6

두 표본에서 전환율(비율)을 비교하는 A/B 테스트를 위해 필요한 최소 표본 크기를 계산합니다.

이 글에 설명된 공식을 사용합니다. 실험군과 대조군의 크기가 동일하다고 가정합니다. 한 그룹에 필요한 표본 크기를 반환합니다. 따라서 전체 실험에 필요한 표본 크기는 이 값의 2배입니다.

구문

minSampleSizeConversion(baseline, mde, power, alpha)

인수

• baseline — 기준 전환율. Float*
• mde — 최소 검출 효과(MDE)를 퍼센트 포인트 단위로 나타낸 값(예: 기준 전환율이 0.25이고 MDE가 0.03이면, 기대되는 변화는 0.25 ± 0.03을 의미합니다). Float*
• power — 필요한 통계적 검정력(1 - II종 오류 확률). Float*
• alpha — 필요한 유의수준(I종 오류 확률). Float*

반환 값

3개의 요소를 가진 이름이 지정된 Tuple을 반환합니다: minimum_sample_size, detect_range_lower, detect_range_upper. 각각은 다음을 의미합니다. 필요한 표본 크기, 반환된 필요한 표본 크기로는 검출할 수 없는 값 범위의 하한( baseline - mde 로 계산), 반환된 필요한 표본 크기로는 검출할 수 없는 값 범위의 상한( baseline + mde 로 계산). Tuple(Float64, Float64, Float64)

예시

minSampleSizeConversion

SELECT minSampleSizeConversion(0.25, 0.03, 0.80, 0.05) AS sample_size

(3396.077603219163,0.22,0.28)

neighbor

도입 버전: v20.1

현재 행에서 지정한 오프셋만큼 떨어진 위치에 있는 컬럼의 값을 반환합니다. 이 함수는 데이터 블록의 물리적 순서를 기준으로 동작하며, 이는 사용자가 기대하는 논리적 순서와 일치하지 않을 수 있으므로 사용이 중단되었고(deprecated) 오류를 유발하기 쉽습니다. 대신 적절한 윈도우 함수 사용을 고려하십시오.

allow_deprecated_error_prone_window_functions = 1 설정을 통해 이 함수를 활성화할 수 있습니다.

Syntax

neighbor(column, offset[, default_value])

인수

• column — 원본 컬럼. Any
• offset — 현재 행으로부터의 오프셋입니다. 양수는 이후 행을, 음수는 이전 행을 조회합니다. Integer
• default_value — 선택 사항입니다. 오프셋이 데이터 범위를 벗어날 때 반환할 값입니다. 지정하지 않으면 컬럼 타입의 기본값을 사용합니다. Any

반환 값

지정된 오프셋의 값을 반환하며, 범위를 벗어나면 기본값을 반환합니다. Any

예시

사용 예시

SELECT number, neighbor(number, 2) FROM system.numbers LIMIT 10;

┌─number─┬─neighbor(number, 2)─┐
│      0 │                   2 │
│      1 │                   3 │
│      2 │                   4 │
│      3 │                   5 │
│      4 │                   6 │
│      5 │                   7 │
│      6 │                   8 │
│      7 │                   9 │
│      8 │                   0 │
│      9 │                   0 │
└────────┴─────────────────────┘

기본값 사용 시

SELECT number, neighbor(number, 2, 999) FROM system.numbers LIMIT 10;

┌─number─┬─neighbor(number, 2, 999)─┐
│      0 │                        2 │
│      1 │                        3 │
│      2 │                        4 │
│      3 │                        5 │
│      4 │                        6 │
│      5 │                        7 │
│      6 │                        8 │
│      7 │                        9 │
│      8 │                      999 │
│      9 │                      999 │
└────────┴──────────────────────────┘

nested

도입된 버전: v

이 함수는 ClickHouse 엔진 내부에서 사용되며, 직접 사용하도록 설계된 함수가 아닙니다.

여러 배열로부터 튜플의 배열을 반환합니다.

첫 번째 인수는 결과 Tuple의 이름을 결정하는 상수 String 배열이어야 합니다. 나머지 인수는 모두 크기가 동일한 배열이어야 합니다.

구문

인수

• 없음

반환 값

예제

중첩

SELECT nested(['keys', 'values'], ['key_1', 'key_2'], ['value_1','value_2'])

normalizeQuery

도입 버전: v20.8

리터럴, 리터럴 시퀀스, 그리고 공백을 포함하거나 자릿수가 두 자리보다 많거나 UUID처럼 길이가 최소 36바이트인 복잡한 별칭을 플레이스홀더 ?로 대체합니다.

구문

normalizeQuery(x)

인수

• x — 문자 시퀀스입니다. String

반환 값

지정된 문자 시퀀스를 플레이스홀더와 함께 반환합니다. String

예시

사용 예시

SELECT normalizeQuery('[1, 2, 3, x]') AS query

┌─query────┐
│ [?.., x] │
└──────────┘

normalizeQueryKeepNames

도입 버전: v21.2

리터럴과 리터럴 시퀀스를 플레이스홀더 ?로 대체하지만, 공백을 포함하거나 숫자가 2개보다 많거나 UUID처럼 최소 36바이트 길이인 복잡한 별칭은 대체하지 않습니다. 이 함수는 복잡한 쿼리 로그를 더 잘 분석하는 데 도움이 됩니다.

구문

normalizeQueryKeepNames(x)

인수

• x — 문자 시퀀스. String

반환 값

지정된 문자 시퀀스를 플레이스홀더가 포함된 형태로 반환합니다. String

예시

사용 예시

SELECT normalizeQuery('SELECT 1 AS aComplexName123'), normalizeQueryKeepNames('SELECT 1 AS aComplexName123')

┌─normalizeQuery('SELECT 1 AS aComplexName123')─┬─normalizeQueryKeepNames('SELECT 1 AS aComplexName123')─┐
│ SELECT ? AS `?`                               │ SELECT ? AS aComplexName123                            │
└───────────────────────────────────────────────┴────────────────────────────────────────────────────────┘

normalizedQueryHash

도입된 버전: v20.8

유사한 쿼리에 대해 리터럴 값은 제외하고 동일한 64비트 해시 값을 반환합니다. 쿼리 로그를 분석하는 데 유용합니다.

구문

normalizedQueryHash(x)

인수

• x — 문자열. String

반환 값

64비트 해시 값을 반환합니다. UInt64

예시

사용 예시

SELECT normalizedQueryHash('SELECT 1 AS `xyz`') != normalizedQueryHash('SELECT 1 AS `abc`') AS res

┌─res─┐
│   1 │
└─────┘

normalizedQueryHashKeepNames

도입 버전: v21.2

normalizedQueryHash와 마찬가지로, 유사한 쿼리에 대해 리터럴 값 없이 동일한 64비트 해시 값을 반환하지만, 해시를 계산하기 전에 공백을 포함하거나 숫자가 두 자리보다 많거나 최소 36바이트 길이(예: UUID)인 복잡한 별칭을 플레이스홀더로 대체하지 않습니다. 쿼리 로그를 분석하는 데 유용합니다.

구문

normalizedQueryHashKeepNames(x)

인자

• x — 문자 시퀀스. String

반환값

64비트 해시값을 반환합니다. UInt64

예시

사용 예시

SELECT normalizedQueryHash('SELECT 1 AS `xyz123`') != normalizedQueryHash('SELECT 1 AS `abc123`') AS normalizedQueryHash;
SELECT normalizedQueryHashKeepNames('SELECT 1 AS `xyz123`') != normalizedQueryHashKeepNames('SELECT 1 AS `abc123`') AS normalizedQueryHashKeepNames;

┌─normalizedQueryHash─┐
│                   0 │
└─────────────────────┘
┌─normalizedQueryHashKeepNames─┐
│                            1 │
└──────────────────────────────┘

parseReadableSize

도입 버전: v24.6

바이트 크기와 단위 B, KiB, KB, MiB, MB 등(즉, ISO/IEC 80000-13 또는 십진 바이트 단위)을 포함하는 문자열이 주어지면, 이 함수는 해당하는 바이트 수를 반환합니다. 함수가 입력값을 파싱할 수 없으면 예외를 발생시킵니다.

이 함수의 역연산은 formatReadableSize 및 formatReadableDecimalSize입니다.

구문

parseReadableSize(x)

인수

• x — ISO/IEC 80000-13 또는 10진수 바이트 단위를 사용하는 사람이 읽기 쉬운 크기 표현. String

반환 값

올림하여 정수로 표현한 바이트 수를 반환합니다. UInt64

예시

사용 예시

SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB']) AS readable_sizes, parseReadableSize(readable_sizes) AS sizes;

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
└────────────────┴─────────┘

parseReadableSizeOrNull

도입 버전: v24.6

바이트 크기를 나타내는 문자열과 단위 B, KiB, KB, MiB, MB 등(즉, ISO/IEC 80000-13 또는 10진수 바이트 단위)이 주어지면, 이 함수는 해당하는 바이트 수를 반환합니다. 함수가 입력값을 파싱할 수 없으면 NULL을 반환합니다.

이 함수의 역연산은 formatReadableSize 및 formatReadableDecimalSize입니다.

구문

parseReadableSizeOrNull(x)

인수

• x — ISO/IEC 80000-13 또는 10진 바이트 단위를 사용한 사람이 읽기 쉬운 크기 표현. String

반환 값

입력을 파싱할 수 없는 경우 NULL을, 가능한 경우 가장 가까운 정수로 올림한 바이트 수를 반환합니다. Nullable(UInt64) 널 허용

예시

사용 예시

SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes, parseReadableSizeOrNull(readable_sizes) AS sizes;

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
│ invalid        │    ᴺᵁᴸᴸ │
└────────────────┴─────────┘

parseReadableSizeOrZero

도입 버전: v24.6

바이트 크기를 나타내는 문자열이 B, KiB, KB, MiB, MB 등(즉, ISO/IEC 80000-13 또는 10진수 바이트 단위)과 같은 단위를 포함하면, 이 함수는 이에 해당하는 바이트 수를 반환합니다. 입력값을 파싱할 수 없으면 0을 반환합니다.

이 함수의 역연산은 formatReadableSize와 formatReadableDecimalSize입니다.

Syntax

parseReadableSizeOrZero(x)

인수

• x — ISO/IEC 80000-13 또는 십진법 기준 바이트 단위를 사용하는 사람이 읽기 쉬운 크기 표현. String

반환 값

가장 가까운 정수로 올림한 바이트 수를 반환하며, 입력값을 파싱할 수 없는 경우 0을 반환합니다. UInt64

예시

사용 예시

SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes, parseReadableSizeOrZero(readable_sizes) AS sizes;

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
│ invalid        │       0 │
└────────────────┴─────────┘

parseTimeDelta

도입된 버전: v22.7

숫자 시퀀스와 그 뒤에 오는 시간 단위 문자열을 파싱합니다.

time delta 문자열은 다음과 같은 시간 단위 표기를 사용합니다:

• years, year, yr, y
• months, month, mo
• weeks, week, w
• days, day, d
• hours, hour, hr, h
• minutes, minute, min, m
• seconds, second, sec, s
• milliseconds, millisecond, millisec, ms
• microseconds, microsecond, microsec, μs, µs, us
• nanoseconds, nanosecond, nanosec, ns

여러 시간 단위를 구분자(공백, ;, -, +, ,, :)로 결합하여 사용할 수 있습니다.

년(year)과 월(month)의 길이는 근사값입니다. year는 365일, month는 30.5일로 간주합니다.

구문

parseTimeDelta(timestr)

인수

• timestr — 숫자 시퀀스 뒤에 시간 단위를 나타내는 토큰이 붙은 문자열입니다. String

반환 값

초 단위의 값입니다. Float64

예시

사용 예시

SELECT parseTimeDelta('11s+22min')

┌─parseTimeDelta('11s+22min')─┐
│                        1331 │
└─────────────────────────────┘

복합 시간 단위

SELECT parseTimeDelta('1yr2mo')

┌─parseTimeDelta('1yr2mo')─┐
│                 36806400 │
└──────────────────────────┘

partitionId

도입된 버전: v21.4

파티션 ID를 계산합니다.

참고

이 함수는 속도가 느리므로, 많은 수의 행에 대해 호출하는 것은 권장되지 않습니다.

구문

partitionId(column1[, column2, ...])

별칭: partitionID

인수

• column1, column2, ... — 파티션 ID를 조회할 컬럼.

반환 값

해당 행이 속한 파티션의 ID를 반환합니다. String

예시

사용 예시

DROP TABLE IF EXISTS tab;

CREATE TABLE tab
(
  i int,
  j int
)
ENGINE = MergeTree
PARTITION BY i
ORDER BY tuple();

INSERT INTO tab VALUES (1, 1), (1, 2), (1, 3), (2, 4), (2, 5), (2, 6);

SELECT i, j, partitionId(i), _partition_id FROM tab ORDER BY i, j;

┌─i─┬─j─┬─partitionId(i)─┬─_partition_id─┐
│ 1 │ 1 │ 1              │ 1             │
│ 1 │ 2 │ 1              │ 1             │
│ 1 │ 3 │ 1              │ 1             │
│ 2 │ 4 │ 2              │ 2             │
│ 2 │ 5 │ 2              │ 2             │
│ 2 │ 6 │ 2              │ 2             │
└───┴───┴────────────────┴───────────────┘

queryID

도입된 버전: v21.9

현재 쿼리의 ID를 반환합니다. 쿼리의 다른 매개변수는 system.query_log 테이블의 query_id 필드에서 추출할 수 있습니다.

initialQueryID 함수와 달리, queryID는 서로 다른 세그먼트에서 서로 다른 결과를 반환할 수 있습니다.

구문

queryID()

별칭: query_id

인수

• 없음.

반환값

현재 실행 중인 쿼리의 ID를 반환합니다. String

예시

사용 예시

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT queryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

┌─count(DISTINCT t)─┐
│                 3 │
└───────────────────┘

revision

도입 버전: v22.7

현재 ClickHouse 서버 리비전 번호를 반환합니다.

구문

revision()

인수

• 없음.

반환값

현재 ClickHouse 서버 리비전 번호를 반환합니다. UInt32

예시

사용 예시

SELECT revision()

┌─revision()─┐
│      54485 │
└────────────┘

rowNumberInAllBlocks

도입된 버전: v1.1

처리되는 각 행에 대해 고유한 행 번호를 반환합니다.

구문

rowNumberInAllBlocks()

인수

• 없음.

반환 값

데이터 블록에서 각 행에 대해 0부터 시작하는 서수 번호를 반환합니다. UInt64

예시

사용 예시

SELECT rowNumberInAllBlocks()
FROM
(
    SELECT *
    FROM system.numbers_mt
    LIMIT 10
)
SETTINGS max_block_size = 2

┌─rowNumberInAllBlocks()─┐
│                      0 │
│                      1 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      4 │
│                      5 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      2 │
│                      3 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      6 │
│                      7 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      8 │
│                      9 │
└────────────────────────┘

rowNumberInBlock

도입된 버전: v1.1

rowNumberInBlock가 처리하는 각 block에 대해 현재 행의 번호를 반환합니다.

반환되는 번호는 각 block마다 0부터 시작합니다.

구문

rowNumberInBlock()

인수

• 없음.

반환 값

데이터 블록에서 0부터 시작하는 행의 순번을 반환합니다. UInt64

예시

사용 예시

SELECT rowNumberInBlock()
FROM
(
    SELECT *
    FROM system.numbers_mt
    LIMIT 10
) SETTINGS max_block_size = 2

┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
└────────────────────┘

runningAccumulate

도입 버전: v1.1

데이터 블록의 각 행에 대해 집계 함수의 상태를 누적합니다.

사용 중단됨(Deprecated)

상태는 새로운 데이터 블록마다 초기화됩니다. 이처럼 오류를 유발하기 쉬운 동작 때문에 이 함수는 사용 중단되었으며, 대신 윈도 함수(window function)를 사용할 것을 권장합니다. 이 함수의 사용을 허용하려면 설정 allow_deprecated_error_prone_window_functions을(를) 사용하십시오.

구문

runningAccumulate(agg_state[, grouping])

인수

• agg_state — 집계 함수의 상태입니다. AggregateFunction
• grouping — 선택적입니다. 그룹화 키입니다. grouping 값이 변경되면 함수의 상태가 초기화됩니다. 등호 연산자가 정의된 지원 데이터 타입 중 어떤 것이든 사용할 수 있습니다. Any

반환 값

각 행에 대한 누적 결과를 반환합니다. Any

예시

initializeAggregation 사용 예

WITH initializeAggregation('sumState', number) AS one_row_sum_state
SELECT
    number,
    finalizeAggregation(one_row_sum_state) AS one_row_sum,
    runningAccumulate(one_row_sum_state) AS cumulative_sum
FROM numbers(5);

┌─number─┬─one_row_sum─┬─cumulative_sum─┐
│      0 │           0 │              0 │
│      1 │           1 │              1 │
│      2 │           2 │              3 │
│      3 │           3 │              6 │
│      4 │           4 │             10 │
└────────┴─────────────┴────────────────┘

runningConcurrency

도입 버전: v21.3

동시 이벤트의 개수를 계산합니다. 각 이벤트에는 시작 시각과 종료 시각이 있습니다. 시작 시각은 이벤트에 포함되지만 종료 시각은 포함되지 않습니다. 시작 시각과 종료 시각을 담는 컬럼은 동일한 데이터 타입이어야 합니다. 이 함수는 각 이벤트 시작 시각마다 활성(동시) 이벤트의 총 개수를 계산합니다.

요구 사항

이벤트는 시작 시각을 기준으로 오름차순 정렬되어 있어야 합니다. 이 요구 사항을 만족하지 않으면 함수에서 예외를 발생시킵니다. 모든 데이터 블록은 개별적으로 처리됩니다. 서로 다른 데이터 블록의 이벤트가 겹치는 경우 올바르게 처리할 수 없습니다.

사용 중단 예정

대신 window functions 사용을 권장합니다.

구문

runningConcurrency(start, end)

인수

• start — 이벤트 시작 시간을 포함하는 컬럼. Date 또는 DateTime 또는 DateTime64
• end — 이벤트 종료 시간을 포함하는 컬럼. Date 또는 DateTime 또는 DateTime64

반환 값

각 이벤트가 시작되는 시점의 동시 이벤트 개수를 반환합니다. UInt32

예시

사용 예시

SELECT start, runningConcurrency(start, end) FROM example_table;

┌──────start─┬─runningConcurrency(start, end)─┐
│ 2025-03-03 │                              1 │
│ 2025-03-06 │                              2 │
│ 2025-03-07 │                              3 │
│ 2025-03-11 │                              2 │
└────────────┴────────────────────────────────┘

runningDifference

도입 버전: v1.1

데이터 블록에서 연속된 두 행 값의 차이를 계산합니다. 첫 번째 행에는 0을 반환하고, 이후 행에는 이전 행과의 차이를 반환합니다.

Deprecated

현재 처리 중인 데이터 블록 내부에서만 차이를 반환합니다. 이와 같은 오류를 유발하기 쉬운 동작 때문에 이 함수는 더 이상 사용이 권장되지 않습니다. 대신 윈도우 함수 사용을 권장합니다.

설정 allow_deprecated_error_prone_window_functions을 사용하여 이 함수 사용을 허용할 수 있습니다.

함수 결과는 영향을 받는 데이터 블록과 블록 내 데이터의 순서에 따라 달라집니다. runningDifference()를 계산할 때의 행 순서는 사용자에게 반환되는 행 순서와 다를 수 있습니다. 이를 방지하려면 ORDER BY가 있는 서브쿼리를 작성하고, 서브쿼리 바깥에서 함수를 호출하십시오. 블록 크기가 결과에 영향을 미친다는 점에 유의하십시오. runningDifference의 내부 상태는 각 새 블록마다 초기화됩니다.

구문

runningDifference(x)

인수

• x — 누적 차이를 계산할 컬럼. Any

반환 값

연속된 값들 사이의 차이를 반환하며, 첫 번째 행에서는 0을 반환합니다.

예시

사용 예시

SELECT
    EventID,
    EventTime,
    runningDifference(EventTime) AS delta
FROM
(
    SELECT
        EventID,
        EventTime
    FROM events
    WHERE EventDate = '2025-11-24'
    ORDER BY EventTime ASC
    LIMIT 5
);

┌─EventID─┬───────────EventTime─┬─delta─┐
│    1106 │ 2025-11-24 00:00:04 │     0 │
│    1107 │ 2025-11-24 00:00:05 │     1 │
│    1108 │ 2025-11-24 00:00:05 │     0 │
│    1109 │ 2025-11-24 00:00:09 │     4 │
│    1110 │ 2025-11-24 00:00:10 │     1 │
└─────────┴─────────────────────┴───────┘

블록 크기의 영향 예시

SELECT
    number,
    runningDifference(number + 1) AS diff
FROM numbers(100000)
WHERE diff != 1;

┌─number─┬─diff─┐
│      0 │    0 │
└────────┴──────┘
┌─number─┬─diff─┐
│  65536 │    0 │
└────────┴──────┘

runningDifferenceStartingWithFirstValue

도입 버전: v1.1

데이터 블록에서 연속된 행 값들 사이의 차이를 계산하지만, runningDifference와는 달리 첫 번째 행의 경우 0 대신 실제 값을 반환합니다.

Deprecated

현재 처리 중인 데이터 블록 내부에서만 차이를 반환합니다. 이와 같은 오류를 유발하기 쉬운 동작 때문에 이 함수는 사용이 권장되지 않습니다. 대신 윈도 함수를 사용할 것을 권장합니다.

이 함수 사용을 허용하려면 allow_deprecated_error_prone_window_functions SETTING을 활성화하면 됩니다.

구문

runningDifferenceStartingWithFirstValue(x)

인수

• x — 연속 차이를 계산할 컬럼. Any

반환 값

연속하는 값 사이의 차이를 반환하며, 첫 번째 행에는 첫 번째 행의 값을 반환합니다. Any

예시

사용 예시

SELECT
    number,
    runningDifferenceStartingWithFirstValue(number) AS diff
FROM numbers(5);

┌─number─┬─diff─┐
│      0 │    0 │
│      1 │    1 │
│      2 │    1 │
│      3 │    1 │
│      4 │    1 │
└────────┴──────┘

serverUUID

도입 버전: v20.1

서버가 처음 시작될 때 생성되는 무작위이면서 고유한 UUID(v4)를 반환합니다. 이 UUID는 영구적으로 저장되므로, 두 번째, 세 번째 등 이후 서버 시작 시에도 동일한 UUID를 반환합니다.

구문

serverUUID()

인수

• 없음.

반환 값

서버의 임의의 UUID를 반환합니다. UUID

예시

사용 예제

SELECT serverUUID();

┌─serverUUID()─────────────────────────────┐
│ 7ccc9260-000d-4d5c-a843-5459abaabb5f     │
└──────────────────────────────────────────┘

shardCount

도입된 버전: v21.9

분산 쿼리에 대해 세그먼트의 총 개수를 반환합니다. 쿼리가 분산되지 않은 경우 상수 값 0이 반환됩니다.

구문

shardCount()

인수

• 없습니다.

반환 값

세그먼트의 총 개수 또는 0을 반환합니다. UInt32

예제

사용 예제

-- See shardNum() example above which also demonstrates shardCount()
CREATE TABLE shard_count_example (dummy UInt8)
ENGINE=Distributed(test_cluster_two_shards_localhost, system, one, dummy);
SELECT shardCount() FROM shard_count_example;

┌─shardCount()─┐
│            2 │
│            2 │
└──────────────┘

shardNum

도입 버전: v21.9

분산 쿼리에서 데이터 일부를 처리하는 세그먼트의 인덱스를 반환합니다. 인덱스는 1부터 시작합니다. 쿼리가 분산되지 않으면 상수 값 0을 반환합니다.

구문

shardNum()

인수

• 없음.

반환 값

세그먼트 인덱스 또는 상수값 0을 반환합니다. UInt32

예시

사용 예시

CREATE TABLE shard_num_example (dummy UInt8)
ENGINE=Distributed(test_cluster_two_shards_localhost, system, one, dummy);
SELECT dummy, shardNum(), shardCount() FROM shard_num_example;

┌─dummy─┬─shardNum()─┬─shardCount()─┐
│     0 │          1 │            2 │
│     0 │          2 │            2 │
└───────┴────────────┴──────────────┘

showCertificate

도입된 버전: v22.6

현재 서버에 Secure Sockets Layer(SSL) 인증서가 구성되어 있는 경우 해당 인증서 정보를 표시합니다. 연결을 검증하기 위해 ClickHouse에서 OpenSSL 인증서를 사용하도록 설정하는 방법은 TLS 구성하기를 참고하십시오.

구문

showCertificate()

인수

• 없음.

반환 값

구성된 SSL 인증서와 관련된 key-value 쌍으로 이루어진 맵을 반환합니다. Map(String, String)

예시

사용 예시

SELECT showCertificate() FORMAT LineAsString;

{'version':'1','serial_number':'2D9071D64530052D48308473922C7ADAFA85D6C5','signature_algo':'sha256WithRSAEncryption','issuer':'/CN=marsnet.local CA','not_before':'May  7 17:01:21 2024 GMT','not_after':'May  7 17:01:21 2025 GMT','subject':'/CN=chnode1','pkey_algo':'rsaEncryption'}

sleep

도입 버전: v1.1

지정된 초 수만큼 쿼리 실행을 일시 중지합니다. 이 함수는 주로 테스트 및 디버깅 목적으로 사용됩니다.

sleep() 함수는 쿼리 성능과 시스템 응답성을 저하시킬 수 있으므로 일반적으로 프로덕션 환경에서는 사용하지 않는 것이 좋습니다. 그러나 다음과 같은 상황에서는 유용하게 사용할 수 있습니다.

1. 테스트: ClickHouse를 테스트하거나 벤치마킹할 때, 특정 조건에서 시스템이 어떻게 동작하는지 관찰하기 위해 지연을 시뮬레이션하거나 일시 중지를 도입해야 할 수 있습니다.
2. 디버깅: 특정 시점에서 시스템 상태나 쿼리 실행 상태를 살펴봐야 하는 경우, sleep()을 사용해 일시 중지 구간을 만들어 관련 정보를 검사하거나 수집할 수 있습니다.
3. 시뮬레이션: 네트워크 지연이나 외부 시스템 의존성과 같이 실제 환경에서 발생하는 지연 또는 일시 중지 상황을 시뮬레이션해야 하는 경우가 있을 수 있습니다.

참고

sleep() 함수는 ClickHouse 시스템 전체의 성능과 응답성에 영향을 줄 수 있으므로, 꼭 필요한 경우에만 신중하게 사용해야 합니다.

보안상의 이유로 이 함수는 기본 사용자 프로필(allow_sleep이 활성화된 경우)에서만 실행할 수 있습니다.

구문

sleep(seconds)

인수

• seconds — 쿼리 실행을 일시 중지할 시간(초)로, 최대 3초까지 지정합니다. 분수 초를 지정하기 위해 부동소수점 값으로 사용할 수 있습니다. const UInt* 또는 const Float*

반환 값

0을 반환합니다. UInt8

예시

사용 예시

-- This query will pause for 2 seconds before completing.
-- During this time, no results will be returned, and the query will appear to be hanging or unresponsive.
SELECT sleep(2);

┌─sleep(2)─┐
│        0 │
└──────────┘
1 row in set. Elapsed: 2.012 sec.

sleepEachRow

도입 버전: v1.1

결과 집합의 각 행마다 지정된 시간(초) 동안 쿼리 실행을 일시 중지합니다.

sleepEachRow() 함수는 주로 테스트 및 디버깅 목적으로 사용되며, sleep() 함수와 유사합니다. 각 행을 처리할 때마다 지연을 시뮬레이션하거나 일시 중지를 추가할 수 있어, 다음과 같은 시나리오에서 유용합니다:

1. 테스트: 특정 조건에서 ClickHouse의 성능을 테스트하거나 벤치마킹할 때, sleepEachRow()를 사용하여 처리되는 각 행마다 지연을 시뮬레이션하거나 일시 중지를 추가할 수 있습니다.
2. 디버깅: 처리되는 각 행에 대해 시스템 상태나 쿼리 실행 상태를 확인해야 하는 경우, sleepEachRow()로 일시 중지를 추가하여 관련 정보를 검사하거나 수집할 수 있습니다.
3. 시뮬레이션: 외부 시스템과의 상호 작용이나 네트워크 지연 등으로 인해 각 행 처리마다 지연이나 일시 중지가 발생하는 실제 환경을 시뮬레이션해야 하는 경우에 사용할 수 있습니다.

참고

sleep() 함수와 마찬가지로, sleepEachRow()는 ClickHouse 시스템의 전체 성능과 응답성에 상당한 영향을 줄 수 있으므로, 특히 큰 결과 집합을 처리할 때는 꼭 필요할 때만 신중하게 사용해야 합니다.

문법

sleepEachRow(seconds)

인수

• seconds — 결과 집합의 각 행에 대해 쿼리 실행을 일시 중지하는 시간(초)입니다. 최대 3초까지 지정할 수 있습니다. 소수 초를 지정할 수 있도록 부동소수점 값일 수 있습니다. const UInt* 또는 const Float*

반환 값

각 행에 대해 0을 반환합니다. UInt8

예시

사용 예시

-- The output will be delayed, with a 0.5-second pause between each row.
SELECT number, sleepEachRow(0.5) FROM system.numbers LIMIT 5;

┌─number─┬─sleepEachRow(0.5)─┐
│      0 │                 0 │
│      1 │                 0 │
│      2 │                 0 │
│      3 │                 0 │
│      4 │                 0 │
└────────┴───────────────────┘

structureToCapnProtoSchema

도입된 버전: v

ClickHouse 테이블 구조를 CapnProto 형식의 스키마로 변환하는 FUNCTION입니다.

구문

인수

• 없음.

반환 값

예시

random

SELECT structureToCapnProtoSchema('s String, x UInt32', 'MessageName') format TSVRaw

struct MessageName
{
    s @0 : Data;
    x @1 : UInt32;
}

structureToProtobufSchema

도입 버전: v23.8

ClickHouse 테이블 구조를 Protobuf 형식 스키마로 변환합니다.

이 FUNCTION은 ClickHouse 테이블 구조 정의를 입력으로 받아 이를 proto3 구문의 Protocol Buffers(Protobuf) 스키마 정의로 변환합니다. 이는 데이터 교환을 위해 ClickHouse 테이블 구조와 일치하는 Protobuf 스키마를 생성하는 데 유용합니다.

구문

structureToProtobufSchema(structure, message_name)

인수

• structure — 문자열인 ClickHouse 테이블 구조 정의 (예: 'column1 Type1, column2 Type2'). String
• message_name — 생성된 스키마에서 Protobuf 메시지 타입의 이름. String

반환 값

입력 ClickHouse 테이블 구조에 대응하는 proto3 구문의 Protobuf 스키마 정의를 반환합니다. String

예시

ClickHouse 구조를 Protobuf 스키마로 변환

SELECT structureToProtobufSchema('s String, x UInt32', 'MessageName') FORMAT TSVRaw;

syntax = "proto3";

message MessageName
{
    bytes s = 1;
    uint32 x = 2;
}

tcpPort

도입 버전: v20.12

서버가 수신 대기 중인 native interface TCP 포트 번호를 반환합니다. 분산 테이블 컨텍스트에서 실행되면 이 함수는 각 세그먼트에 해당하는 값이 담긴 일반 컬럼을 생성합니다. 그렇지 않으면 상수 값을 생성합니다.

구문

tcpPort()

인수

• 없음.

반환 값

반환 값은 TCP 포트 번호입니다. UInt16

예제

사용 예제

SELECT tcpPort()

┌─tcpPort()─┐
│      9000 │
└───────────┘

throwIf

도입된 버전: v1.1

인수 x가 true인 경우 예외를 발생시킵니다. error_code 인수를 사용하려면 설정 매개변수 allow_custom_error_code_in_throw가 활성화되어 있어야 합니다.

구문

throwIf(x[, message[, error_code]])

인수

• x — 확인할 조건. Any
• message — 선택 사항. 사용자 정의 오류 메시지. const String
• error_code — 선택 사항. 사용자 정의 오류 코드. const Int8/16/32

반환 값

조건이 거짓이면 0을 반환하고, 조건이 참이면 예외를 발생시킵니다. UInt8

예시

사용 예시

SELECT throwIf(number = 3, 'Too many') FROM numbers(10);

↙ Progress: 0.00 rows, 0.00 B (0.00 rows/s., 0.00 B/s.) Received exception from server (version 19.14.1):
Code: 395. DB::Exception: Received from localhost:9000. DB::Exception: Too many.

toColumnTypeName

도입된 버전: v1.1

지정한 값의 데이터 타입에 대한 내부 이름을 반환합니다. 함수 toTypeName과 달리, 반환되는 데이터 타입에는 Const 및 LowCardinality와 같은 내부 래퍼 컬럼이 포함될 수 있습니다.

구문

toColumnTypeName(value)

인자

• value — 내부 데이터 타입을 확인할 값. Any

반환 값

값을 표현하는 데 사용되는 내부 데이터 타입을 반환합니다. String

예제

사용 예제

SELECT toColumnTypeName(CAST('2025-01-01 01:02:03' AS DateTime));

┌─toColumnTypeName(CAST('2025-01-01 01:02:03', 'DateTime'))─┐
│ Const(UInt32)                                             │
└───────────────────────────────────────────────────────────┘

toTypeName

도입 버전: v1.1

전달된 인자의 타입 이름을 반환합니다. NULL이 전달되면 함수는 ClickHouse의 내부 NULL 표현에 해당하는 타입인 Nullable(Nothing)을 반환합니다.

문법

toTypeName(x)

인수

• x — 임의의 타입 값. Any

반환 값

입력값의 데이터 타입 이름을 반환합니다. String

예시

사용 예시

SELECT toTypeName(123)

┌─toTypeName(123)─┐
│ UInt8           │
└─────────────────┘

transactionID

도입된 버전: v22.6

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

트랜잭션 ID를 반환합니다.

참고

이 함수는 실험적 기능 세트의 일부입니다. 구성에 다음 설정을 추가하여 실험적 트랜잭션 지원을 활성화하십시오.

<clickhouse>
    <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>

자세한 내용은 Transactional (ACID) support 페이지를 참조하십시오.

문법

transactionID()

인수

• 없음.

반환 값

start_csn, local_tid, host_id로 구성된 튜플을 반환합니다.

• start_csn: 이 트랜잭션이 시작될 때 관측된 가장 최근 커밋 타임스탬프의 전역 순차 번호입니다.
• local_tid: 특정 start_csn 내에서 이 호스트가 시작한 각 트랜잭션에 대해 고유한 로컬 순차 번호입니다.
• host_id: 이 트랜잭션을 시작한 호스트의 UUID입니다. Tuple(UInt64, UInt64, UUID)

예시

사용 예시

BEGIN TRANSACTION;
SELECT transactionID();
ROLLBACK;

┌─transactionID()────────────────────────────────┐
│ (32,34,'0ee8b069-f2bb-4748-9eae-069c85b5252b') │
└────────────────────────────────────────────────┘

transactionLatestSnapshot

도입 버전: v22.6

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

읽기용으로 사용할 수 있는 transaction의 최신 스냅샷(Commit Sequence Number)을 반환합니다.

참고

이 함수는 실험적 기능 집합의 일부입니다. 구성에 다음 설정을 추가하여 실험적 트랜잭션 지원을 활성화하십시오:

<clickhouse>
    <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>

자세한 내용은 Transactional (ACID) support 페이지를 참조하십시오.

구문

transactionLatestSnapshot()

인수

• 없음.

반환값

트랜잭션의 최신 스냅샷(CSN)을 반환합니다. 타입은 UInt64입니다.

예시

사용 예시

BEGIN TRANSACTION;
SELECT transactionLatestSnapshot();
ROLLBACK;

┌─transactionLatestSnapshot()─┐
│                          32 │
└─────────────────────────────┘

transactionOldestSnapshot

도입 버전: v22.6

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

실행 중인 트랜잭션 중 일부에서 볼 수 있는 가장 오래된 스냅샷(Commit Sequence Number)을 반환합니다.

참고

이 함수는 실험적 기능 세트의 일부입니다. 구성에 다음 설정을 추가하여 실험적 트랜잭션 지원을 활성화하십시오:

<clickhouse>
    <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>

자세한 내용은 트랜잭션(ACID) 지원 페이지를 참고하십시오.

구문

transactionOldestSnapshot()

인수

• 없음.

반환 값

트랜잭션에서 가장 오래된 스냅샷(CSN)을 반환합니다. UInt64

예시

사용 예시

BEGIN TRANSACTION;
SELECT transactionOldestSnapshot();
ROLLBACK;

┌─transactionOldestSnapshot()─┐
│                          32 │
└─────────────────────────────┘

transform

도입 버전: v1.1

일부 요소를 다른 요소에 명시적으로 매핑해 정의한 규칙에 따라 값을 변환합니다.

이 함수에는 두 가지 형태가 있습니다.

• transform(x, array_from, array_to, default) - 매핑 배열을 사용해 x를 변환하며, 일치하지 않는 요소에 대해서는 기본값을 사용합니다.
• transform(x, array_from, array_to) - 동일한 변환을 수행하지만, 일치 항목이 없으면 원래 x를 반환합니다.

함수는 array_from에서 x를 찾아 같은 인덱스 위치의 array_to 요소를 반환합니다. x가 array_from에서 발견되지 않으면, default 값(4-매개변수 버전) 또는 원래의 x(3-매개변수 버전)를 반환합니다. array_from에 여러 개의 일치하는 요소가 있으면, 첫 번째로 일치한 요소에 해당하는 값을 반환합니다.

요구사항:

• array_from과 array_to는 요소 개수가 동일해야 합니다.
• 4-매개변수 버전: transform(T, Array(T), Array(U), U) -> U 여기서 T와 U는 서로 다른 호환 가능한 타입일 수 있습니다.
• 3-매개변수 버전: transform(T, Array(T), Array(T)) -> T 여기서는 모든 타입이 동일해야 합니다.

Syntax

transform(x, array_from, array_to[, default])

인수

• x — 변환할 값입니다. (U)Int* 또는 Decimal 또는 Float* 또는 String 또는 Date 또는 DateTime
• array_from — 일치하는 값을 검색할 상수 배열입니다. Array((U)Int*) 또는 Array(Decimal) 또는 Array(Float*) 또는 Array(String) 또는 Array(Date) 또는 Array(DateTime)
• array_to — array_from에서 일치하는 값에 대해 반환할 값들의 상수 배열입니다. Array((U)Int*) 또는 Array(Decimal) 또는 Array(Float*) 또는 Array(String) 또는 Array(Date) 또는 Array(DateTime)
• default — 선택 사항입니다. x가 array_from에서 발견되지 않을 때 반환할 값입니다. 생략하면 x를 변경하지 않고 반환합니다. (U)Int* 또는 Decimal 또는 Float* 또는 String 또는 Date 또는 DateTime

반환 값

x가 array_from의 요소와 일치하면 array_to에서 해당하는 값을 반환하고, 그렇지 않으면 default(제공된 경우)를 반환하며, default가 제공되지 않은 경우 x를 반환합니다. Any

예시

transform(T, Array(T), Array(U), U) -> U

SELECT
transform(SearchEngineID, [2, 3], ['Yandex', 'Google'], 'Other') AS title,
count() AS c
FROM test.hits
WHERE SearchEngineID != 0
GROUP BY title
ORDER BY c DESC

┌─title─────┬──────c─┐
│ Yandex    │ 498635 │
│ Google    │ 229872 │
│ Other     │ 104472 │
└───────────┴────────┘

transform(T, Array(T), Array(T)) -> T

SELECT
transform(domain(Referer), ['yandex.ru', 'google.ru', 'vkontakte.ru'], ['www.yandex', 'example.com', 'vk.com']) AS s, count() AS c
FROM test.hits
GROUP BY domain(Referer)
ORDER BY count() DESC
LIMIT 10

┌─s──────────────┬───────c─┐
│                │ 2906259 │
│ www.yandex     │  867767 │
│ ███████.ru     │  313599 │
│ mail.yandex.ru │  107147 │
│ ██████.ru      │  100355 │
│ █████████.ru   │   65040 │
│ news.yandex.ru │   64515 │
│ ██████.net     │   59141 │
│ example.com    │   57316 │
└────────────────┴─────────┘

uniqThetaIntersect

도입 버전: v22.9

두 개의 uniqThetaSketch 객체에 대해 교집합 계산(집합 연산 ∩)을 수행하며, 결과는 새로운 uniqThetaSketch 객체입니다.

구문

uniqThetaIntersect(uniqThetaSketch,uniqThetaSketch)

인수

• uniqThetaSketch — uniqThetaSketch 객체. Tuple 또는 Array 또는 Date 또는 DateTime 또는 String 또는 (U)Int* 또는 Float* 또는 Decimal

반환 값

교집합 결과를 포함한 새로운 uniqThetaSketch 객체입니다. UInt64

예시

사용 예시

SELECT finalizeAggregation(uniqThetaIntersect(a, b)) AS a_intersect_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [1, 2]) AS a, arrayReduce('uniqThetaState', [2, 3, 4]) AS b);

┌─a_intersect_b─┬─a_cardinality─┬─b_cardinality─┐
│             1 │             2 │             3 │
└───────────────┴───────────────┴───────────────┘

uniqThetaNot

도입 버전: v22.9

두 개의 uniqThetaSketch 객체에 대해 a_not_b 계산(집합 연산 ×)을 수행하며, 그 결과는 새로운 uniqThetaSketch입니다.

구문

uniqThetaNot(uniqThetaSketch,uniqThetaSketch)

인수

• uniqThetaSketch — uniqThetaSketch 객체. Tuple 또는 Array 또는 Date 또는 DateTime 또는 String 또는 (U)Int* 또는 Float* 또는 Decimal

반환값

a_not_b 결과를 포함하는 새로운 uniqThetaSketch 객체를 반환합니다. UInt64

예시

사용 예시

SELECT finalizeAggregation(uniqThetaNot(a, b)) AS a_not_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [2, 3, 4]) AS a, arrayReduce('uniqThetaState', [1, 2]) AS b);

┌─a_not_b─┬─a_cardinality─┬─b_cardinality─┐
│       2 │             3 │             2 │
└─────────┴───────────────┴───────────────┘

uniqThetaUnion

도입 버전: v22.9

두 개의 uniqThetaSketch 객체에 대해 합집합(Set, ∪) 연산을 수행하며, 결과로 새로운 uniqThetaSketch를 생성합니다.

구문

uniqThetaUnion(uniqThetaSketch,uniqThetaSketch)

인자

• uniqThetaSketch — uniqThetaSketch 객체입니다. Tuple 또는 Array 또는 Date 또는 DateTime 또는 String 또는 (U)Int* 또는 Float* 또는 Decimal

반환 값

합집합 결과를 포함하는 새로운 uniqThetaSketch 객체를 반환합니다. UInt64

예시

사용 예시

SELECT finalizeAggregation(uniqThetaUnion(a, b)) AS a_union_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [1, 2]) AS a, arrayReduce('uniqThetaState', [2, 3, 4]) AS b);

┌─a_union_b─┬─a_cardinality─┬─b_cardinality─┐
│         4 │             2 │             3 │
└───────────┴───────────────┴───────────────┘

uptime

도입 버전: v1.1

서버의 가동 시간(초 단위)을 반환합니다. 분산 테이블 컨텍스트에서 실행되는 경우 이 함수는 각 세그먼트에 해당하는 값을 가진 일반 컬럼을 생성합니다. 그 외의 경우에는 상수 값을 생성합니다.

구문

uptime()

인수

• 없음

반환 값

서버 업타임을 초 단위로 반환합니다. UInt32

예시

사용 예시

SELECT uptime() AS Uptime

┌─Uptime─┐
│  55867 │
└────────┘

variantElement

도입된 버전: v25.2

Variant 컬럼에서 지정된 타입의 컬럼을 추출합니다.

구문

variantElement(variant, type_name[, default_value])

인수

• variant — Variant 컬럼. Variant
• type_name — 추출할 variant 타입의 이름. String
• default_value — 지정한 타입을 가진 variant가 없을 때 사용할 기본값입니다. 어떤 타입이든 사용할 수 있습니다. 선택 사항입니다. Any

반환 값

Variant 컬럼에서 지정된 variant 타입을 추출한 컬럼을 반환합니다. Any

예시

사용 예시

CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT v, variantElement(v, 'String'), variantElement(v, 'UInt64'), variantElement(v, 'Array(UInt64)') FROM test;

┌─v─────────────┬─variantElement(v, 'String')─┬─variantElement(v, 'UInt64')─┬─variantElement(v, 'Array(UInt64)')─┐
│ ᴺᵁᴸᴸ          │ ᴺᵁᴸᴸ                        │                        ᴺᵁᴸᴸ │ []                                 │
│ 42            │ ᴺᵁᴸᴸ                        │                          42 │ []                                 │
│ Hello, World! │ Hello, World!               │                        ᴺᵁᴸᴸ │ []                                 │
│ [1,2,3]       │ ᴺᵁᴸᴸ                        │                        ᴺᵁᴸᴸ │ [1,2,3]                            │
└───────────────┴─────────────────────────────┴─────────────────────────────┴────────────────────────────────────┘

variantType

도입된 버전: v24.2

Variant 컬럼의 각 행에 대해 Variant 타입의 이름을 반환합니다. 행에 NULL이 포함되어 있으면 해당 행에 대해서는 「None」을 반환합니다.

구문

variantType(variant)

인수

• variant — Variant 컬럼. Variant

반환값

각 행에 대해 Variant 타입 이름을 포함하는 Enum 컬럼을 반환합니다. Enum

예시

사용 예시

CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT variantType(v) FROM test;

┌─variantType(v)─┐
│ None           │
│ UInt64         │
│ String         │
│ Array(UInt64)  │
└────────────────┘

version

도입 버전: v1.1

현재 ClickHouse 버전을 다음 형식의 문자열로 반환합니다: major_version.minor_version.patch_version.number_of_commits_since_the_previous_stable_release. 분산 테이블 컨텍스트에서 실행되는 경우 이 함수는 각 세그먼트에 해당하는 값을 담은 일반 컬럼을 생성합니다. 그 외의 경우에는 상수 값을 생성합니다.

Syntax

version()

인자

• 없음.

반환값

현재 ClickHouse 버전을 반환합니다. String

예시

사용 예시

SELECT version()

┌─version()─┐
│ 24.2.1.1  │
└───────────┘

visibleWidth

도입 버전: v1.1

값을 텍스트 형식(탭으로 구분)으로 콘솔에 출력할 때의 대략적인 출력 너비를 계산합니다. 이 함수는 시스템에서 Pretty 형식을 구현하는 데 사용됩니다. NULL은 Pretty 형식에서 NULL에 해당하는 문자열로 표현됩니다.

구문

visibleWidth(x)

인수

• x — 임의의 데이터 타입의 값. Any

반환 값

값을 텍스트 형식으로 표시할 때의 대략적인 너비를 반환합니다. UInt64

예시

NULL의 표시 너비 계산

SELECT visibleWidth(NULL)

┌─visibleWidth(NULL)─┐
│                  4 │
└────────────────────┘

zookeeperSessionUptime

도입된 버전: v21.11

현재 ZooKeeper 세션의 업타임을 초 단위로 반환합니다.

구문

zookeeperSessionUptime()

인자

• 없음.

반환값

현재 ZooKeeper 세션의 가동 시간을 초 단위로 반환합니다. UInt32

예시

사용 예시

SELECT zookeeperSessionUptime();

┌─zookeeperSessionUptime()─┐
│                      286 │
└──────────────────────────┘