기타 함수

“기타” 함수 카테고리에 대한 문서

아래 함수 문서는 system.functions 시스템 테이블을 기반으로 생성됩니다.

​

FQDN

도입 버전: v20.1.0

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

구문

FQDN()

별칭: fullHostName

인수

• 없음.

반환 값

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

예시

사용 예시

Query

SELECT fqdn()

Response

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

​

MACNumToString

도입 버전: v1.1.0

UInt64 숫자를 빅 엔디언 포맷의 MAC 주소로 해석합니다. 해당 MAC 주소를 문자열로 반환하며, 포맷은 AA:BB:CC:DD:EE:FF입니다(16진수 숫자를 콜론으로 구분).

구문

MACNumToString(num)

인수

• num — UInt64 형식의 숫자입니다. UInt64

반환 값

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

예시

사용 예시

Query

SELECT MACNumToString(149809441867716) AS mac_address;

Response

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

​

MACStringToNum

도입 버전: v1.1.0

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

구문

MACStringToNum(s)

인수

• s — MAC 주소 문자열입니다. String

반환 값

UInt64 값을 반환합니다. UInt64

예시

사용 예시

Query

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

Response

1108152157446

​

MACStringToOUI

도입 버전: v1.1.0

AA:BB:CC:DD:EE:FF 포맷의 MAC 주소(콜론으로 구분된 16진수 값)가 주어지면, 처음 3개의 옥텟을 UInt64 값으로 반환합니다. MAC 주소 포맷이 올바르지 않으면 0을 반환합니다.

구문

MACStringToOUI(s)

인수

• s — MAC 주소 문자열입니다. String

반환 값

처음 3개의 옥텟을 UInt64 값으로 반환합니다. UInt64

예시

사용 예시

Query

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

Response

20566

​

authenticatedUser

도입 버전: v25.11.0

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

구문

authenticatedUser()

별칭: authUser

인수

• 없음.

반환 값

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

예시

사용 예시

Query

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

Response

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

​

bar

도입 버전: v1.1.0

막대 차트를 생성합니다. x = max일 때 너비가 width문자인 띠를 그리며, 띠의 너비는 (x - min)에 비례합니다. 띠는 기호 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

예시

사용 예시

Query

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

Response

┌──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.0

행을 포함하는 블록의 단조 증가하는 순번을 반환합니다. 반환되는 블록 번호는 가능한 범위에서 갱신되므로 완전히 정확하지 않을 수 있습니다.

구문

blockNumber()

인수

• None.

반환 값

해당 행이 포함된 데이터 블록의 시퀀스 번호입니다. UInt64

예시

기본 사용법

Query

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

Response

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

​

blockSerializedSize

도입 버전: v20.3.0

디스크에 있는 값 블록의 압축되지 않은 크기를 바이트 단위로 반환합니다.

구문

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

인수

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

반환 값

압축되지 않은 값 블록이 디스크에 기록될 때의 바이트 수를 반환합니다. UInt64

예시

사용 예시

Query

SELECT blockSerializedSize(maxState(1)) AS x;

Response

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

​

blockSize

지원 시작 버전: v1.1.0

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

구문

blockSize()

인수

• 없음

반환 값

현재 블록의 행 수를 반환합니다. UInt64

예시

사용 예시

Query

SELECT blockSize()
FROM system.numbers LIMIT 5

Response

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

​

buildId

도입 버전: v20.5.0

실행 중인 ClickHouse 서버 바이너리에 대해 컴파일러가 생성한 build ID를 반환합니다. 분산 테이블의 Context에서 실행하면, 이 함수는 각 세그먼트에 해당하는 값을 갖는 일반 컬럼을 생성합니다. 그렇지 않으면 상수 값을 반환합니다.

구문

buildId()

인수

• None.

반환 값

빌드 ID를 반환합니다. String

예시

사용 예시

Query

SELECT buildId()

Response

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

​

byteSize

도입 버전: v21.1.0

메모리에서 인수의 압축되지 않은 바이트 크기를 추정해 반환합니다. String 인수의 경우 문자열 길이 + 8(길이)을 반환합니다. 인수가 여러 개이면 각 인수의 바이트 크기를 합산합니다.

구문

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

인수

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

반환 값

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

예시

사용 예시

Query

SELECT byteSize('string')

Response

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

여러 개의 인수

Query

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

Response

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

​

catboostEvaluate

도입 버전: v22.9.0

외부 catboost 모델을 평가합니다. CatBoost는 Yandex가 기계 학습용으로 개발한 오픈소스 그래디언트 부스팅 라이브러리입니다. catboost 모델의 경로와 모델 인수(피처)를 받습니다.

사전 요구 사항

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

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

다음으로, ClickHouse 구성에서 libcatboostmodel.<so|dylib>의 경로를 지정합니다:

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

보안 및 격리를 위해 모델 평가는 server process가 아니라 clickhouse-library-bridge process에서 실행됩니다. catboostEvaluate()를 처음 실행할 때 server가 아직 실행 중이 아니라면 library bridge process를 시작합니다. 두 프로세스는 HTTP 인터페이스를 사용해 통신합니다. 기본적으로 포트 9012를 사용합니다. 다음과 같이 다른 포트를 지정할 수 있으며, 포트 9012가 이미 다른 서비스에 할당되어 있는 경우 유용합니다.

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

2. libcatboost를 사용하여 catboost 모델을 학습합니다

학습 데이터 세트로 catboost 모델을 학습하는 방법은 모델 학습 및 적용을 참조하십시오.

구문

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

인수

• path_to_model — catboost 모델 경로입니다. const String
• feature — 하나 이상의 모델 피처 또는 인수입니다. Float*

반환 값

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

예시

catboostEvaluate

Query

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

Response

4.695691092573497

​

colorOKLABToSRGB

도입 버전: v26.2.0

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

입력 색상은 OKLab 색 공간으로 지정합니다. 입력 값이 일반적인 OKLab 범위를 벗어나면 결과는 구현에 따라 달라집니다.

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

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

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

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

1. OKLab에서 선형 sRGB로 변환합니다. 2) 선형 sRGB에서 감마 인코딩된 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])

인수

• tuple — 숫자 값 L, a, b 3개로 이루어진 튜플입니다. 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)로 변환

Query

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

Response

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

OKLAB을 sRGB (UInt8)로 변환

Query

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

Response

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

​

colorOKLCHToSRGB

도입 버전: v25.7.0

색상을 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를 적용해 선형 sRGB를 다시 sRGB로 변환할 때 사용하는 지수입니다. 기본값은 2.2입니다. Float64

반환 값

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

예시

OKLCH를 sRGB로 변환

Query

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

Response

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

OKLCH를 sRGB로 변환 (UInt8)

Query

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

Response

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

​

colorSRGBToOKLAB

도입 버전: v26.2.0

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

입력 채널 중 하나라도 [0...255] 범위를 벗어나거나 감마 값이 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로 변환

Query

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

Response

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

​

colorSRGBToOKLCH

도입 버전: v25.7.0

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/을 참조하십시오.

구문

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로 변환

Query

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

Response

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

​

connectionId

v21.3.0에서 도입됨

현재 쿼리를 제출한 클라이언트의 connection ID를 반환합니다. 이 함수는 디버깅 시 가장 유용합니다. MySQL의 CONNECTION_ID 함수와의 호환성을 위해 만들어졌습니다. 일반적으로 프로덕션 쿼리에서는 사용되지 않습니다.

구문

connectionId()

인수

• 없음.

반환 값

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

예시

사용 예시

Query

SELECT connectionId();

Response

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

​

countDigits

도입 버전: v20.8.0

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

이 함수는 Decimal 값의 소수 자릿수(scale)도 고려합니다. 즉, 내부 정수형인 (value * scale)를 기준으로 결과를 계산합니다.

예시는 다음과 같습니다.

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

Decimal64의 Decimal 오버플로우는 countDigits(x) > 18로 확인할 수 있지만, isDecimalOverflow보다 느립니다.

구문

countDigits(x)

인수

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

반환 값

x를 나타내는 데 필요한 자릿수를 반환합니다. UInt8

예시

사용 예시

Query

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));

Response

┌─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.0

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

SET 문도 참조하십시오.

구문

currentDatabase()

별칭: current_database, SCHEMA, DATABASE

인수

• 없음.

반환 값

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

예시

사용 예시

Query

SELECT currentDatabase()

Response

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

괄호 없는 SQL 표준 구문

Query

SELECT CURRENT_DATABASE

Response

┌─CURRENT_DATABASE─┐
│ default          │
└──────────────────┘

​

currentProfiles

도입 버전: v21.9.0

현재 사용자의 설정 프로필로 이루어진 배열을 반환합니다.

구문

currentProfiles()

인수

• None.

반환 값

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

예시

사용 예시

Query

SELECT currentProfiles();

Response

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

​

currentQueryID

도입 버전: v25.2.0

현재 Query id를 반환합니다.

구문

currentQueryID()

별칭: current_query_id

인수

• None.

반환 값

예시

예시

Query

SELECT currentQueryID();

Response

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

​

currentRoles

도입 버전: v21.9.0

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

구문

currentRoles()

인수

• None.

반환 값

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

예시

사용 예시

Query

SELECT currentRoles();

Response

┌─currentRoles()─────────────────────────────────┐
│ ['sql-console-role:[e-mail]'] │
└────────────────────────────────────────────────┘

​

currentSchemas

도입 버전: v23.7.0

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

• 무시되는 boolean 인수를 받습니다.
• 데이터베이스 이름을 단일 값만 포함된 배열로 반환합니다.

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

SET 문도 참조하십시오.

구문

currentSchemas(bool)

별칭: current_schemas

인수

• bool — 무시되는 불리언 값입니다. Bool

반환 값

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

예시

사용 예시

Query

SELECT currentSchemas(true)

Response

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

​

currentUser

도입 버전: v20.1.0

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

구문

currentUser()

별칭: session_user, user, current_user

인수

• 없음.

반환 값

현재 사용자의 이름을 반환합니다. 현재 사용자를 확인할 수 없으면 쿼리를 시작한 사용자의 로그인명을 반환합니다. String

예시

사용 예시

Query

SELECT currentUser()

Response

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

괄호 없는 SQL 표준 구문

Query

SELECT CURRENT_USER

Response

┌─CURRENT_USER─┐
│ default      │
└──────────────┘

​

defaultProfiles

도입 버전: v21.9.0

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

구문

defaultProfiles()

인수

• 없음.

반환 값

현재 사용자의 기본 설정 프로필 이름으로 이루어진 배열을 반환합니다. Array(String)

예시

사용 예시

Query

SELECT defaultProfiles();

Response

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

​

defaultRoles

도입 버전: v21.9.0

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

구문

defaultRoles()

인수

• 없음.

반환 값

현재 사용자의 기본 역할로 이루어진 배열을 반환합니다. Array(String)

예시

사용 예시

Query

SELECT defaultRoles();

Response

┌─defaultRoles()─────────────────────────────────┐
│ ['sql-console-role:[e-mail]'] │
└────────────────────────────────────────────────┘

​

defaultValueOfArgumentType

도입 버전: v1.1.0

주어진 데이터 타입의 기본값을 반환합니다. 사용자가 설정한 사용자 지정 컬럼의 기본값은 포함하지 않습니다.

구문

defaultValueOfArgumentType(expression)

인수

• expression — 임의의 타입 값을 나타내는 값 또는 임의의 타입 값을 반환하는 표현식입니다. Any

반환 값

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

예시

사용 예시

Query

SELECT defaultValueOfArgumentType(CAST(1 AS Int8));

Response

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

널 허용 예시

Query

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

Response

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

​

defaultValueOfTypeName

도입 버전: v1.1.0

주어진 type name의 기본값을 반환합니다.

구문

defaultValueOfTypeName(type)

인수

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

반환 값

주어진 타입 이름의 기본값을 반환합니다. 숫자 타입은 0, 문자열 타입은 빈 문자열, 널 허용 UInt8, String, 또는 NULL은 NULL을 반환합니다.

예시

사용 예시

Query

SELECT defaultValueOfTypeName('Int8');

Response

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

널 허용 예시

Query

SELECT defaultValueOfTypeName('Nullable(Int8)');

Response

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

​

displayName

도입 버전: v22.11.0

구성에서 display_name 값이 설정되어 있으면 그 값을 반환하고, 설정되어 있지 않으면 server의 정규화된 도메인 이름(FQDN)을 반환합니다.

구문

displayName()

인수

• 없음.

반환 값

config의 display_name 값이 설정된 경우 해당 값을 반환하며, 설정되지 않은 경우 server FQDN을 반환합니다. String

예시

사용 예시

Query

SELECT displayName();

Response

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

​

dumpColumnStructure

도입 버전: v1.1.0

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

구문

dumpColumnStructure(x)

인수

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

반환 값

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

예시

사용 예시

Query

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

Response

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

​

enabledProfiles

도입 버전: v21.9.0

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

구문

enabledProfiles()

인수

• 없음.

반환 값

현재 사용자에게 활성화된 설정 프로필 이름의 배열을 반환합니다. Array(String)

예시

사용 예시

Query

SELECT enabledProfiles();

Response

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

​

enabledRoles

도입 버전: v21.9.0

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

구문

enabledRoles()

인수

• 없음.

반환 값

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

예시

사용 예시

Query

SELECT enabledRoles();

Response

┌─enabledRoles()─────────────────────────────────────────────────┐
│ ['general_data', 'sql-console-role:[e-mail]'] │
└────────────────────────────────────────────────────────────────┘

​

errorCodeToName

도입 버전: v20.12.0

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

구문

errorCodeToName(error_code)

인수

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

반환 값

error_code에 해당하는 이름 문자열을 반환합니다. String

예시

사용 예시

Query

SELECT errorCodeToName(252);

Response

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

​

file

도입 버전: v21.3.0

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

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

구문

file(path[, default])

인수

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

반환 값

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

예시

파일을 테이블에 삽입

Query

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

Response

​

filesystemAvailable

도입 버전: v20.1.0

데이터베이스 영구 저장소가 위치한 파일 시스템의 사용 가능한 여유 공간을 반환합니다. 일부 공간은 운영 체제용으로 예약되므로 반환 값은 항상 전체 여유 공간(filesystemUnreserved)보다 작습니다.

구문

filesystemAvailable([disk_name])

인수

• disk_name — 선택 사항입니다. 남은 여유 공간의 크기를 확인할 디스크 이름입니다. 생략하면 기본 디스크를 사용합니다. String 또는 FixedString

반환 값

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

예시

사용 예시

Query

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

Response

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

​

filesystemCapacity

도입 버전: v20.1.0

파일 시스템의 용량을 바이트 단위로 반환합니다. 데이터 디렉터리의 경로가 설정되어 있어야 합니다.

구문

filesystemCapacity([disk_name])

인수

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

반환 값

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

예시

사용 예시

Query

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

Response

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

​

filesystemUnreserved

도입 버전: v22.12.0

데이터베이스 영구 저장소가 위치한 파일 시스템의 전체 여유 공간을 반환합니다(이전 이름: filesystemFree). 관련 항목: filesystemAvailable.

구문

filesystemUnreserved([disk_name])

인수

• disk_name — 선택 사항입니다. 전체 여유 공간을 확인할 디스크 이름입니다. 생략하면 기본 디스크를 사용합니다. String 또는 FixedString

반환 값

바이트 단위의 여유 공간을 반환합니다. UInt64

예시

사용 예시

Query

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

Response

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

​

finalizeAggregation

도입 버전: v1.1.0

집계 상태가 주어지면, 이 함수는 집계 결과를 반환합니다(또는 -State combinator를 사용하는 경우 최종화된 상태를 반환합니다).

구문

finalizeAggregation(state)

인수

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

반환 값

집계가 완료된 최종 결과를 반환합니다. Any

예시

사용 예시

Query

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

Response

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

initializeAggregation과 함께 사용

Query

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);

Response

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

​

flipCoordinates

도입 버전: v25.11.0

기하 객체의 x 및 y 좌표를 서로 바꿉니다. 이 작업은 위도와 경도를 맞바꾸는 것으로, 서로 다른 좌표계 간 변환하거나 좌표 순서를 바로잡는 데 유용합니다.

Point에서는 x 및 y 좌표를 서로 바꿉니다. 복합 기하 객체(LineString, Polygon, MultiPolygon, Ring, MultiLineString)에서는 각 좌표 쌍에 이 변환을 재귀적으로 적용합니다.

이 함수는 개별 Geometry 타입(Point, Ring, Polygon, MultiPolygon, LineString, MultiLineString)과 Geometry variant type을 모두 지원합니다.

구문

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

Query

SELECT flipCoordinates((1.0, 2.0));

Response

(2.0, 1.0)

ring

Query

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

Response

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

다각형

Query

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

Response

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

geometry_wkt

Query

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

Response

(20, 10)

geometry_polygon_wkt

Query

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

Response

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

​

formatQuery

도입 버전: v23.10.0

주어진 SQL 쿼리를 포맷된 형태로 반환하며, 여러 줄 형식일 수도 있습니다. 파싱 오류가 발생하면 예외를 발생시킵니다. [example:multiline]

구문

formatQuery(query)

인수

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

반환 값

포맷된 쿼리 String

예시

여러 줄

Query

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

Response

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

​

formatQueryOrNull

도입 버전: v23.11.0

지정된 SQL 쿼리를 서식이 적용된 버전으로 반환하며, 여러 줄 형식일 수 있습니다. 파싱 오류가 발생하면 NULL을 반환합니다. [example:multiline]

구문

formatQueryOrNull(query)

인수

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

반환 값

포맷된 쿼리 String

예시

여러 줄

Query

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

Response

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

​

formatQuerySingleLine

도입 버전: v23.10.0

formatQuery()와 비슷하지만 반환되는 포맷된 문자열에는 줄바꿈이 없습니다. 파싱 오류가 발생한 경우 예외를 발생시킵니다. [example:multiline]

구문

formatQuerySingleLine(query)

인수

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

반환 값

포맷된 쿼리입니다. String

예시

여러 줄

Query

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

Response

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

​

formatQuerySingleLineOrNull

도입 버전: v23.11.0

formatQuery()와 유사하지만 반환되는 문자열에는 줄바꿈이 없습니다. 파싱 오류가 발생하면 NULL을 반환합니다. [example:multiline]

구문

formatQuerySingleLineOrNull(query)

인수

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

반환 값

포맷된 쿼리 String

예시

여러 줄

Query

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

Response

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

​

formatReadableDecimalSize

도입 버전: v22.11.0

크기(바이트 수)가 주어지면, 이 함수는 접미사(KB, MB 등)가 붙은 읽기 쉬운 반올림 크기를 문자열로 반환합니다.

이 함수의 반대 연산은 parseReadableSize입니다.

구문

formatReadableDecimalSize(value[, precision])

인수

• value — 바이트 단위의 크기입니다. Int8 or Int16 or Int32 or Int64 or UInt8 or UInt16 or UInt32 or UInt64 or Float32 or Float64 or Decimal
• precision — 선택 사항입니다. 소수점 이하 자릿수입니다. 기본값은 2입니다. const UInt8

반환 값

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

예시

파일 크기 형식 지정

Query

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

Response

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

정밀도를 명시적으로 지정

Query

SELECT
    formatReadableDecimalSize(192851925, 0) AS no_decimals,
    formatReadableDecimalSize(192851925, 4) AS four_decimals

Response

┌─no_decimals─┬─four_decimals─┐
│ 193 MB      │ 192.8519 MB   │
└─────────────┴───────────────┘

​

formatReadableQuantity

도입 버전: v20.10.0

주어진 숫자에 대해, 이 함수는 접미사(천, 백만, 십억 등)가 붙은 반올림된 값을 문자열로 반환합니다.

이 함수는 모든 숫자형을 입력으로 받을 수 있지만, 내부적으로는 이를 Float64로 형변환합니다. 큰 값에서는 결과가 다소 부정확할 수 있습니다.

구문

formatReadableQuantity(value[, precision])

인수

• value — 포맷할 숫자입니다. Int8 또는 Int16 또는 Int32 또는 Int64 또는 UInt8 또는 UInt16 또는 UInt32 또는 UInt64 또는 Float32 또는 Float64 또는 Decimal
• precision — 선택 사항입니다. 소수점 이하 자릿수입니다. 기본값은 2입니다. const UInt8

반환 값

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

예시

접미사를 사용해 숫자 포맷하기

Query

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

Response

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

정밀도를 명시적으로 지정해 사용하기

Query

SELECT
    formatReadableQuantity(98765432101234, 0) AS no_decimals,
    formatReadableQuantity(98765432101234, 4) AS four_decimals

Response

┌─no_decimals──┬─four_decimals─────┐
│ 99 trillion  │ 98.7654 trillion  │
└──────────────┴───────────────────┘

​

formatReadableSize

도입 버전: v1.1.0

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

이 함수의 반대 연산은 parseReadableSize, parseReadableSizeOrZero, parseReadableSizeOrNull입니다. 이 함수는 모든 숫자 유형을 입력으로 받을 수 있지만, 내부적으로는 이를 Float64로 변환합니다. 값이 큰 경우 결과가 최적이지 않을 수 있습니다.

구문

formatReadableSize(value[, precision])

별칭: FORMAT_BYTES

인수

• value — 바이트 단위의 크기입니다. Int8 or Int16 or Int32 or Int64 or UInt8 or UInt16 or UInt32 or UInt64 or Float32 or Float64 or Decimal
• precision — 선택 사항입니다. 소수점 이하 자릿수입니다. 기본값은 2입니다. const UInt8

반환 값

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

예시

파일 크기 포맷 지정

Query

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

Response

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

정밀도를 명시적으로 지정하는 경우

Query

SELECT
    formatReadableSize(192851925, 0) AS no_decimals,
    formatReadableSize(192851925, 4) AS four_decimals

Response

┌─no_decimals─┬─four_decimals──┐
│ 184 MiB     │ 183.9179 MiB   │
└─────────────┴────────────────┘

​

formatReadableTimeDelta

도입 버전: v20.12.0

초 단위의 시간 인터벌(delta) 또는 INTERVAL 표현식이 주어지면, 이 함수는 year/month/day/hour/minute/second/millisecond/microsecond/nanosecond 단위로 이루어진 시간 차이를 문자열로 반환합니다.

이 함수는 입력으로 모든 숫자 유형을 받을 수 있지만, 내부적으로는 이를 Float64로 CAST합니다. 값이 큰 경우 결과가 다소 부정확할 수 있습니다.

INTERVAL 표현식이 전달되면 해당 값은 초로 변환됩니다. MONTH 이상의 인터벌 단위(MONTH, QUARTER, YEAR)는 초 단위의 고정된 크기 인터벌을 나타내지 않으므로 지원되지 않습니다.

구문

formatReadableTimeDelta(column[, maximum_unit, minimum_unit])

인수

• column — 숫자형 시간 차이를 나타내는 컬럼 또는 INTERVAL 표현식입니다. MONTH 이상의 인터벌 단위는 지원되지 않습니다. Float64 or Interval
• 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

예시

사용 예시

Query

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

Response

┌────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│
└────────────┴────────────────────────────────────────────────────────────────┘

최대 단위 사용

Query

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

Response

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

INTERVAL 표현식 사용

Query

SELECT formatReadableTimeDelta(INTERVAL 12345 SECOND) AS time_delta

Response

┌─time_delta─────────────────────────┐
│ 3 hours, 25 minutes and 45 seconds │
└────────────────────────────────────┘

​

fuzzQuery

도입 버전: v26.2.0

주어진 쿼리 문자열을 파싱하고 여기에 무작위 AST 뮤테이션(fuzzing)을 적용합니다. 퍼징된 쿼리를 문자열로 반환합니다. 결정적이지 않으므로 호출할 때마다 다른 결과가 생성될 수 있습니다. allow_fuzz_query_functions = 1이 필요합니다.

구문

fuzzQuery(query)

인수

• query — 퍼징 대상 SQL 쿼리입니다. String

반환 값

퍼징된 쿼리 문자열 String

예시

기본

Query

SET allow_fuzz_query_functions = 1; SELECT fuzzQuery('SELECT 1');

Response

​

generateRandomStructure

도입 버전: v23.5.0

column1_name column1_type, column2_name column2_type, ... 포맷의 무작위 테이블 구조를 생성합니다.

구문

generateRandomStructure([number_of_columns, seed])

인수

• number_of_columns — 결과 테이블 구조의 원하는 컬럼 수입니다. 0 또는 Null로 설정하면 컬럼 수는 1~128 사이에서 무작위로 정해집니다. 기본값은 Null입니다. UInt64
• seed — 일관된 결과를 생성하기 위한 랜덤 시드입니다. 시드를 지정하지 않거나 Null로 설정하면 무작위로 생성됩니다. UInt64

반환 값

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

예시

사용 예시

Query

SELECT generateRandomStructure()

Response

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

지정한 개수의 컬럼으로

Query

SELECT generateRandomStructure(1)

Response

c1 Map(UInt256, UInt16)

지정된 시드로

Query

SELECT generateRandomStructure(NULL, 33)

Response

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.0

이전 카운터 값부터 순차적인 숫자를 생성해 반환합니다. 이 함수는 문자열 인수인 시리즈 식별자와 선택적 시작 값을 받습니다. 서버는 Keeper를 사용하도록 구성되어 있어야 합니다. 시리즈는 Keeper 노드의 경로 아래에 저장되며, 이 경로는 서버 구성의 series_keeper_path에서 설정할 수 있습니다.

구문

generateSerialID(series_identifier[, start_value])

인수

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

반환 값

이전 카운터 값을 기준으로 순차적인 숫자를 반환합니다. UInt64

예시

첫 번째 호출

Query

SELECT generateSerialID('id1')

Response

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

두 번째 호출

Query

SELECT generateSerialID('id1')

Response

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

컬럼 호출

Query

SELECT *, generateSerialID('id1') FROM test_table

Response

┌─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 │
└───────────┴────────┴─────┴──────────────────────────┘

시작 값 포함

Query

SELECT generateSerialID('id2', 100)

Response

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

시작 값으로 두 번째 호출

Query

SELECT generateSerialID('id2', 100)

Response

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

​

getClientHTTPHeader

도입 버전: v24.5.0

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

설정 allow_get_client_http_header이 필요합니다

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

이 함수에서는 HTTP 헤더의 대소문자를 구분합니다. 이 함수가 분산 쿼리에서 사용되면, initiator 노드에서만 비어 있지 않은 결과를 반환합니다.

구문

getClientHTTPHeader(name)

인수

• name — HTTP 헤더의 이름입니다. String

반환 값

헤더 값을 반환합니다. String

예시

사용 예시

Query

SELECT getClientHTTPHeader('Content-Type');

Response

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

​

getMacro

도입 버전: v20.1.0

서버 설정 파일에서 매크로의 값을 반환합니다. 매크로는 설정 파일의 <macros> 섹션에 정의되며, 호스트명이 복잡하더라도 서버를 알기 쉬운 이름으로 구분하는 데 사용할 수 있습니다. 이 함수가 분산 테이블에서 실행되면 각 세그먼트에 해당하는 값을 가진 일반 컬럼을 생성합니다.

구문

getMacro(name)

인수

• name — 가져올 매크로의 이름입니다. const String

반환 값

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

예시

기본 사용법

Query

SELECT getMacro('test');

Response

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

​

getMaxTableNameLengthForDatabase

도입 버전: v25.1.0

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

구문

getMaxTableNameLengthForDatabase(database_name)

인수

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

반환 값

최대 테이블 이름의 길이를 반환합니다. 반환 타입은 Integer입니다.

예시

일반적인 예

Query

SELECT getMaxTableNameLengthForDatabase('default');

Response

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

​

getMergeTreeSetting

도입 버전: v25.6.0

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

구문

getMergeTreeSetting(setting_name)

인수

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

반환 값

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

예시

사용 예시

Query

SELECT getMergeTreeSetting('index_granularity');

Response

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

​

getOSKernelVersion

v21.11.0에 도입됨

OS 커널 버전 문자열을 반환합니다.

구문

getOSKernelVersion()

인수

• 없음.

반환 값

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

예시

사용 예시

Query

SELECT getOSKernelVersion();

Response

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

​

getServerPort

도입 버전: v21.10.0

지정한 프로토콜에 사용되는 server의 포트 번호를 반환합니다.

구문

getServerPort(port_name)

인수

• port_name — 포트 이름입니다. String

반환 값

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

예시

사용 예시

Query

SELECT getServerPort('tcp_port');

Response

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

​

getServerSetting

도입 버전: v25.6.0

서버 설정 이름이 주어지면 현재 설정된 값을 반환합니다.

구문

getServerSetting(setting_name')

인수

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

반환 값

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

예시

사용 예시

Query

SELECT getServerSetting('allow_use_jemalloc_memory');

Response

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

​

getSetting

도입 버전: v20.7.0

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

구문

getSetting(setting_name)

인수

• setting_Name — 설정 이름입니다. const String

반환 값

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

예시

사용 예시

Query

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

Response

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

​

getSettingOrDefault

도입 버전: v24.10.0

현재 profile에 해당 설정이 지정되어 있으면 그 현재 값을 반환하고, 지정되어 있지 않으면 두 번째 인수에 지정된 기본값을 반환합니다.

구문

getSettingOrDefault(setting_name, default_value)

인수

• setting_name — 설정 이름입니다. String
• default_value — custom_setting이 설정되지 않은 경우 반환할 값입니다. 값은 모든 데이터 타입이거나 Null일 수 있습니다.

반환 값

지정한 설정의 현재 값을 반환합니다. 설정이 지정되지 않은 경우 default_value를 반환합니다.

예시

사용 예시

Query

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

Response

my_value
100
NULL

​

getSizeOfEnumType

도입 버전: v1.1.0

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

구문

getSizeOfEnumType(x)

인수

• x — Enum 타입의 값. Enum

반환 값

입력 값이 Enum인 필드 수를 반환합니다. UInt8/16

예시

사용 예시

Query

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

Response

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

​

getSubcolumn

도입 버전: v23.3.0

표현식 또는 식별자와 subcolumn 이름이 포함된 상수 문자열을 받습니다.

표현식에서 추출한 요청된 subcolumn을 반환합니다.

구문

getSubcolumn(nested_value, subcolumn_name)

인수

• 없음.

반환 값

예시

getSubcolumn

Query

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

Response

​

getTypeSerializationStreams

도입 버전: v22.6.0

데이터 타입의 스트림 경로를 나열합니다. 이 함수는 개발용으로 사용됩니다.

구문

getTypeSerializationStreams(col)

인수

• col — 데이터 타입을 판별할 컬럼 또는 데이터 타입의 문자열 표현입니다. Any

반환 값

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

예시

tuple

Query

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

Response

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

맵

Query

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

Response

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

​

globalVariable

도입 버전: v20.5.0

상수 문자열 인수를 받아 해당 이름의 전역 변수 값을 반환합니다. 이 함수는 MySQL 호환성을 위해 제공되며, ClickHouse를 일반적으로 운영할 때는 필요하지도 유용하지도 않습니다. 정의된 더미 전역 변수는 몇 개뿐입니다.

구문

globalVariable(name)

인수

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

반환 값

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

예시

globalVariable

Query

SELECT globalVariable('max_allowed_packet')

Response

67108864

​

hasColumnInTable

도입 버전: v1.1.0

데이터베이스 테이블에 특정 컬럼이 존재하는지 확인합니다. 중첩된 데이터 구조의 요소에 대해서는 컬럼의 존재 여부를 확인합니다. 중첩된 데이터 구조 자체에 대해서는 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

예시

기존 컬럼 확인

Query

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

Response

1

존재하지 않는 컬럼 확인

Query

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

Response

0

​

hasThreadFuzzer

도입 버전: v20.6.0

thread fuzzer가 활성화되어 있는지 여부를 반환합니다. 이 함수는 테스트와 디버깅에만 유용합니다.

구문

hasThreadFuzzer()

인수

• 없음.

반환 값

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

예시

Thread Fuzzer 상태 확인

Query

SELECT hasThreadFuzzer()

Response

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

​

highlightQuery

도입 버전: v26.5.0

ClickHouse SQL 쿼리 문자열을 파싱하여 구문 강조에 사용할 강조 범위의 배열을 반환합니다. 각 범위는 시작 위치(바이트 단위), 끝 위치, 강조 유형으로 구성된 named tuple입니다. 강조 유형은 해당 조각의 구문상 역할(키워드, 식별자, 함수 등)을 나타내며 UI에서 색상을 지정하는 데 사용할 수 있습니다. LIKE 및 REGEXP 문자열 패턴 내부에서는 메타문자와 이스케이프 문자가 별도로 강조 표시됩니다.

구문

highlightQuery(query)

인수

• query — ClickHouse SQL 쿼리 문자열입니다. String.

반환 값

강조 표시된 범위를 나타내는 이름이 지정된 Tuple (begin UInt64, end UInt64, type Enum8(...))의 배열입니다. Array(Tuple(begin UInt64, end UInt64, type Enum8(...)))

예시

기본

Query

SELECT highlightQuery('SELECT 1')

Response

[(0,6,'keyword'),(7,8,'number')]

​

hostName

도입 버전: v20.5.0

이 함수가 실행된 호스트명을 반환합니다. 함수가 원격 server(분산 처리)에서 실행되면 원격 server의 이름을 반환합니다. 함수가 분산 테이블에서 실행되면 각 세그먼트와 관련된 값을 갖는 일반 컬럼을 생성합니다. 그렇지 않으면 상수 값을 생성합니다.

구문

hostName()

별칭: hostname

인수

• 없음.

반환 값

호스트명을 반환합니다. String

예시

사용 예시

Query

SELECT hostName()

Response

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

​

icebergBucket

도입 버전: v25.5.0

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

구문

icebergBucket(N, value)

인수

• N — 버킷 수를 나타내는 모듈로 값입니다. const (U)Int*
• value — 변환할 원본 값입니다. (U)Int* or Bool or Decimal or Float* or String or FixedString or UUID or Date or Time or DateTime

반환 값

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

예시

예시

Query

SELECT icebergBucket(5, 1.0 :: Float32)

Response

4

​

icebergTruncate

도입 버전: v25.3.0

Iceberg truncate transform 로직을 구현합니다: https://iceberg.apache.org/spec/#truncate-transform-details.

구문

icebergTruncate(N, value)

인수

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

반환 값

인수와 같은 타입

예시

예시

Query

SELECT icebergTruncate(3, 'iceberg')

Response

ice

​

identity

도입 버전: v1.1.0

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

구문

identity(x)

인수

• x — 입력 값입니다. Any

반환 값

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

예시

사용 예시

Query

SELECT identity(42)

Response

42

​

ignore

도입 버전: v1.1.0

임의의 인수를 받아 항상 0을 반환합니다.

구문

ignore(x)

인수

• x — 구문 오류를 방지하기 위해서만 전달되며 실제로는 사용되지 않는 입력 값입니다. Any

반환 값

항상 0을 반환합니다. UInt8

예시

사용 예시

Query

SELECT ignore(0, 'ClickHouse', NULL)

Response

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

​

indexHint

도입 버전: v1.1.0

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

인덱스 분석 중에는 이 함수의 인수가 indexHint로 감싸져 있지 않은 것으로 간주됩니다. 따라서 해당 조건에 따라 인덱스 범위의 데이터를 선택하면서도, 그 조건으로 추가 필터링은 하지 않을 수 있습니다. ClickHouse의 인덱스는 희소하므로, indexHint를 사용하면 동일한 조건을 직접 지정할 때보다 더 많은 데이터가 반환됩니다.

설명

다음을 실행하면:

SELECT * FROM test WHERE key = 123;

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

1. 인덱스를 사용해 key = 123을 포함할 수 있는 그래뉼(약 8192개 행의 블록)을 찾습니다
2. 해당 그래뉼을 읽은 다음 각 행을 필터링하여 key = 123인 행만 반환합니다

따라서 디스크에서 8,192개 행을 읽더라도, 실제로 반환되는 것은 조건에 일치하는 1개 행뿐입니다.

indexHint를 사용해 다음을 실행하면:

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

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

1. 인덱스를 사용해 key = 123을 포함할 수 있는 그래뉼을 찾고, 필터링 없이 해당 그래뉼의 모든 행을 반환합니다.

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

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

참고: indexHint 함수를 사용해 쿼리를 최적화할 수는 없습니다. indexHint 함수는 쿼리 분석에 추가 정보를 제공하지 않으므로 쿼리를 최적화하지 않습니다. indexHint 함수 안에 표현식을 넣는 것이 indexHint 함수 없이 사용하는 것보다 어떤 면에서도 더 낫지 않습니다. indexHint 함수는 내부 검사와 디버깅 목적으로만 사용할 수 있으며 성능을 개선하지 않습니다. ClickHouse 기여자가 아닌 사람이 indexHint를 사용하는 경우, 실수일 가능성이 높으므로 제거해야 합니다.

구문

indexHint(expression)

인수

• expression — 인덱스 범위 선택에 사용할 임의의 표현식입니다. Expression

반환 값

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

예시

날짜 필터링 사용 예시

Query

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

Response

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

​

initialQueryID

도입 버전: v1.1.0

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

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

구문

initialQueryID()

별칭: initial_query_id

인수

• 없습니다.

반환 값

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

예시

사용 예시

Query

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());

Response

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

​

initialQueryStartTime

도입 버전: v25.4.0

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

구문

initialQueryStartTime()

별칭: initial_query_start_time

인수

• None.

반환 값

현재 쿼리를 발생시킨 초기 쿼리의 시작 시간을 반환합니다. DateTime

예시

사용 예시

Query

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());

Response

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

​

initializeAggregation

도입 버전: v20.6.0

단일 값을 기반으로 집계 함수의 결과를 계산합니다. 이 함수는 combinator -State를 사용해 집계 함수를 초기화할 때 사용할 수 있습니다. 집계 함수의 상태를 생성해 AggregateFunction 타입의 컬럼에 삽입하거나, 초기화된 집계를 기본값으로 사용할 수 있습니다.

구문

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

인수

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

반환 값

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

예시

uniqState를 사용한 기본 사용법

Query

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

Response

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

sumState와 finalizeAggregation 사용

Query

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

Response

┌─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.0

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

구문

isConstant(x)

인수

• x — 검사할 표현식입니다. Any

반환 값

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

예시

상수 표현식

Query

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

Response

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

함수가 포함된 상수

Query

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

Response

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

상수가 아닌 표현식

Query

SELECT isConstant(number)
FROM numbers(1)

Response

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

now() 함수의 동작

Query

SELECT isConstant(now())

Response

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

​

isDecimalOverflow

도입 버전: v20.8.0

주어진 정밀도의 Decimal 데이터 타입에 정확히 저장할 수 없을 만큼 자릿수가 많은 10진수인지 확인합니다.

구문

isDecimalOverflow(value[, precision])

인수

• value — 확인할 Decimal 값입니다. Decimal
• precision — 선택 사항입니다. Decimal 타입의 정밀도입니다. 생략하면 첫 번째 인수의 원래 정밀도가 사용됩니다. UInt8

반환 값

Decimal 값의 자릿수가 정밀도에서 허용되는 자릿수를 초과하면 1을, 지정된 정밀도를 만족하면 0을 반환합니다. UInt8

예시

사용 예시

Query

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

Response

┌─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.0

딕셔너리와 같은 방식으로 테이블에서 데이터를 추출할 수 있습니다. 지정한 조인 키를 사용해 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

예시

사용 예시

Query

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));

Response

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

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

Query

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

Response

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

배열을 조인 키로 사용하기

Query

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);

Response

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

​

joinGetOrNull

도입 버전: v20.4.0

딕셔너리와 동일한 방식으로 테이블에서 데이터를 추출할 수 있습니다. 지정한 조인 키를 사용해 Join 테이블에서 데이터를 가져옵니다. joinGet과 달리 키가 없으면 NULL을 반환합니다.

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

구문

joinGetOrNull(join_storage_table_name, value_column, join_keys)

인수

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

반환 값

키 목록에 대응하는 값 목록을 반환합니다. 키를 찾지 못하면 NULL을 반환합니다. Any

예시

사용 예시

Query

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));

Response

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

​

lowCardinalityIndices

도입 버전: v18.12.0

LowCardinality 컬럼의 딕셔너리에서 값의 위치를 반환합니다. 위치는 1부터 시작합니다. LowCardinality는 파트마다 딕셔너리를 가지므로, 이 함수는 서로 다른 파트에서 동일한 값에 대해 다른 위치를 반환할 수 있습니다.

구문

lowCardinalityIndices(col)

인수

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

반환 값

현재 파트의 딕셔너리에서 값의 위치입니다. UInt64

예시

사용 예시

Query

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

-- 두 개의 파트 생성:

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

SELECT s, lowCardinalityIndices(s) FROM test;

Response

┌─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.0

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

구문

lowCardinalityKeys(col)

인수

• col — 낮은 카디널리티를 사용하는 컬럼입니다. LowCardinality

반환 값

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

예시

lowCardinalityKeys

Query

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

-- 두 개의 파트 생성:

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

SELECT s, lowCardinalityKeys(s) FROM test;

Response

┌─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.0

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

구문

materialize(x)

인수

• x — 상수입니다. Any

반환 값

상수 값이 들어 있는 전체 컬럼을 반환합니다. Any

예시

사용 예시

Query

-- 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'));

Response

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.0

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

이 문서에 설명된 공식을 사용합니다. 처치군과 대조군의 크기가 같다고 가정합니다. 한 그룹에 필요한 표본 크기를 반환합니다(즉, 전체 실험에 필요한 표본 크기는 반환 값의 2배입니다). 또한 처치군과 대조군에서 테스트 메트릭의 분산이 같다고 가정합니다.

구문

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

별칭: minSampleSizeContinous

인수

• baseline — 메트릭의 기준값입니다. (U)Int* 또는 Float*
• sigma — 메트릭 기준값의 표준편차입니다. (U)Int* 또는 Float*
• mde — 기준값 대비 백분율로 나타낸 최소 검출 가능 효과(MDE)입니다(예: 기준값이 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*

반환 값

3개의 요소 minimum_sample_size, detect_range_lower, detect_range_upper로 구성된 named Tuple을 반환합니다. 각각은 필요한 표본 크기, 반환된 표본 크기로는 검출할 수 없는 값 범위의 하한(baseline * (1 - mde)로 계산), 그리고 반환된 표본 크기로는 검출할 수 없는 값 범위의 상한(baseline * (1 + mde)로 계산)을 의미합니다(Float64). Tuple(Float64, Float64, Float64)

예시

minSampleSizeContinuous

Query

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

Response

(616.2931945826209,108.8825,115.6175)

​

minSampleSizeConversion

도입 버전: v22.6.0

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

이 문서에 설명된 공식을 사용합니다. 처치군과 대조군의 크기가 같다고 가정합니다. 한 그룹에 필요한 표본 크기를 반환합니다(즉, 전체 실험에 필요한 표본 크기는 반환 값의 2배입니다).

구문

minSampleSizeConversion(baseline, mde, power, alpha)

인수

• baseline — 기준 전환율입니다. Float*
• mde — 퍼센트 포인트 단위의 최소 검출 가능 효과(MDE)입니다(예: 기준 전환율이 0.25일 때 MDE가 0.03이면 0.25 ± 0.03의 변화가 예상됨을 의미합니다). Float*
• power — 검정에 필요한 통계적 검정력입니다(1 - 제2종 오류 확률). Float*
• alpha — 검정에 필요한 유의수준입니다(제1종 오류 확률). Float*

반환 값

3개의 요소 minimum_sample_size, detect_range_lower, detect_range_upper를 포함하는 named Tuple을 반환합니다. 각각은 순서대로 필요한 표본 크기, 반환된 필요 표본 크기에서 검출되지 않는 값 범위의 하한으로 baseline - mde로 계산한 값, 반환된 필요 표본 크기에서 검출되지 않는 값 범위의 상한으로 baseline + mde로 계산한 값입니다. Tuple(Float64, Float64, Float64)

예시

minSampleSizeConversion

Query

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

Response

(3396.077603219163,0.22,0.28)

​

neighbor

도입 버전: v20.1.0

현재 행을 기준으로 지정된 오프셋에 있는 컬럼의 값을 반환합니다. 이 함수는 사용 중단되었으며 오류를 일으키기 쉽습니다. 사용자가 기대하는 논리적 순서와 데이터 블록의 물리적 순서가 일치하지 않을 수 있는데, 이 함수는 물리적 순서를 기준으로 동작하기 때문입니다. 대신 적절한 윈도우 함수를 사용하는 것이 좋습니다.

이 함수는 allow_deprecated_error_prone_window_functions = 1을 설정하면 활성화할 수 있습니다.

구문

neighbor(column, offset[, default_value])

인수

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

반환 값

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

예시

사용 예시

Query

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

Response

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

기본값이 있는 경우

Query

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

Response

┌─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 │
└────────┴──────────────────────────┘

​

normalizeQuery

도입 버전: v20.8.0

리터럴, 연속된 리터럴, 그리고 복잡한 별칭(공백을 포함하거나, 3자리 이상 숫자를 포함하거나, UUID처럼 길이가 36바이트 이상인 경우)을 플레이스홀더 ?로 대체합니다.

구문

normalizeQuery(x)

인수

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

반환 값

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

예시

사용 예시

Query

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

Response

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

​

normalizeQueryKeepNames

도입 버전: v21.2.0

리터럴과 리터럴의 연속을 플레이스홀더 ?로 대체하지만, 복잡한 별칭(alias)(공백을 포함하거나, 3자리 이상의 숫자를 포함하거나, UUID처럼 길이가 36바이트 이상인 경우)은 대체하지 않습니다. 이렇게 하면 복잡한 쿼리 로그를 더 효과적으로 분석할 수 있습니다.

구문

normalizeQueryKeepNames(x)

인수

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

반환 값

지정된 문자 시퀀스에 플레이스홀더를 적용해 반환합니다. String

예시

사용 예시

Query

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

Response

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

​

normalizedQueryHash

도입 버전: v20.8.0

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

구문

normalizedQueryHash(x)

인수

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

반환 값

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

예시

사용 예시

Query

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

Response

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

​

normalizedQueryHashKeepNames

도입 버전: v21.2.0

normalizedQueryHash와 마찬가지로, 유사한 쿼리에 대해 리터럴 값은 제외한 동일한 64비트 해시 값을 반환합니다. 다만 해싱 전에 복잡한 별칭(공백을 포함하거나, 2자리를 초과하는 숫자를 포함하거나, UUID처럼 길이가 36바이트 이상인 경우)을 플레이스홀더로 대체하지는 않습니다. 쿼리 로그를 분석할 때 유용할 수 있습니다.

구문

normalizedQueryHashKeepNames(x)

인수

• x — 문자열입니다. String

반환 값

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

예시

사용 예시

Query

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;

Response

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

​

obfuscateQuery

도입 버전: v26.4.0

식별자를 무작위 단어로, 리터럴을 무작위 값으로 대체하면서 SQL 쿼리 구조는 유지한 채 난독화합니다.

이 함수는 로깅하거나 디버깅을 위해 쿼리를 공유하기 전에 쿼리를 익명화할 때 유용합니다. 같은 입력 쿼리라도 서로 다른 행에서는 서로 다른 난독화 결과가 생성되므로, 여러 쿼리를 다룰 때 프라이버시를 유지하는 데 도움이 됩니다.

선택적 tag 매개변수는 동일한 함수 호출이 쿼리에서 여러 번 사용될 때 공통 하위 표현식 제거가 일어나지 않도록 합니다. 이렇게 하면 각 호출마다 서로 다른 난독화 결과가 생성됩니다.

기능:

• table 이름, 컬럼 이름, 별칭을 무작위 단어로 대체합니다
• 숫자 및 문자열 리터럴을 무작위 값으로 대체합니다
• 전체 쿼리 구조와 SQL 구문을 유지합니다
• 서로 다른 행에 대해 서로 다른 결과를 생성합니다

구문

obfuscateQuery(query[, tag])

인수

• query — 난독화할 SQL 쿼리입니다. String
• tag — 선택 사항입니다. 동일한 함수 호출을 여러 번 사용할 때 공통 하위 표현식 제거를 방지하기 위한 값입니다.

반환 값

원래 쿼리 구조를 유지하면서 식별자와 리터럴을 대체한 난독화된 쿼리입니다. String

예시

기본 사용법

Query

SELECT obfuscateQuery('SELECT name, age FROM users WHERE age > 30')

Response

SELECT fruit, number FROM table WHERE number > 12

공통 부분 표현식 제거를 방지하기 위해 tag 사용

Query

SELECT obfuscateQuery('SELECT * FROM t', 1), obfuscateQuery('SELECT * FROM t', 2)

Response

SELECT a FROM b, SELECT c FROM d

행에 따라 결과가 달라집니다

Query

SELECT obfuscateQuery('SELECT 1') AS a, obfuscateQuery('SELECT 1') AS b

Response

A B

​

obfuscateQueryWithSeed

도입 버전: v26.4.0

지정된 seed를 사용해 결정론적 결과가 나오도록 SQL 쿼리를 난독화합니다.

obfuscateQuery()와 달리, 이 함수는 동일한 seed가 주어지면 항상 동일한 결과를 생성합니다. 여러 번 실행하더라도 일관된 난독화가 필요하거나, 테스트 또는 디버깅 목적으로 동일하게 난독화된 쿼리를 재현하려는 경우에 유용합니다.

기능:

• 제공된 seed를 기반으로 한 결정론적 난독화
• 동일한 seed는 항상 동일한 난독화 결과를 생성
• 서로 다른 seed는 서로 다른 결과를 생성
• obfuscateQuery()처럼 쿼리 구조를 유지

사용 사례:

• 재현 가능한 테스트 케이스
• 여러 번 실행해도 일관된 익명화
• 일관되게 난독화된 쿼리를 사용한 디버깅

구문

obfuscateQueryWithSeed(query, seed)

인수

• query — 난독화할 SQL 쿼리입니다. String
• seed — 난독화에 사용할 시드입니다. 동일한 시드를 사용하면 항상 같은 결과가 생성됩니다. Integer 또는 String

반환 값

제공된 시드를 기준으로 동일하게 생성되는 난독화된 쿼리입니다. String

예시

정수 시드를 사용한 결정적 난독화

Query

SELECT obfuscateQueryWithSeed('SELECT name FROM users', 42)

Response

SELECT fruit FROM table

문자열 시드를 사용한 결정론적 난독화

Query

SELECT obfuscateQueryWithSeed('SELECT id, value FROM data', 'myseed')

Response

SELECT a, b FROM c

같은 시드를 사용하면 같은 결과가 나옵니다

Query

SELECT obfuscateQueryWithSeed('SELECT 1', 100) = obfuscateQueryWithSeed('SELECT 1', 100)

Response

true

​

parseReadableSize

도입 버전: v24.6.0

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

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

구문

parseReadableSize(x)

인수

• x — ISO/IEC 80000-13 또는 십진 바이트 단위를 사용하는 사람이 읽기 쉬운 형식의 크기입니다. String

반환 값

가장 가까운 정수로 올림한 바이트 수를 반환합니다. UInt64

예시

사용 예시

Query

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

Response

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

​

parseReadableSizeOrNull

도입 버전: v24.6.0

바이트 크기를 나타내는 문자열과 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)

예시

사용 예시

Query

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

Response

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

​

parseReadableSizeOrZero

도입 버전: v24.6.0

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

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

구문

parseReadableSizeOrZero(x)

인수

• x — ISO/IEC 80000-13 또는 10진 바이트 단위를 사용하는 사람이 읽기 쉬운 형식의 크기입니다. String

반환 값

바이트 수를 반환합니다. 값은 가장 가까운 정수로 올림되며, 입력을 파싱할 수 없으면 0을 반환합니다. UInt64

예시

사용 예시

Query

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

Response

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

​

parseTimeDelta

도입 버전: v22.7.0

숫자 뒤에 시간 단위와 유사한 표현이 오는 시퀀스를 parse합니다.

시간 델타 문자열에서는 다음과 같은 시간 단위 표기를 사용합니다:

• 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

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

연과 월의 길이는 근사값입니다. 1년은 365일이고 1개월은 30.5일입니다.

구문

parseTimeDelta(timestr)

인수

• timestr — 숫자 뒤에 시간 단위와 유사한 표현이 오는 문자열입니다. String

반환 값

초 단위의 숫자입니다. Float64

예시

사용 예시

Query

SELECT parseTimeDelta('11s+22min')

Response

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

복합 시간 단위

Query

SELECT parseTimeDelta('1yr2mo')

Response

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

​

partitionId

도입 버전: v21.4.0

partition ID를 계산합니다.

이 함수는 느리므로 많은 수의 행에 대해서는 호출하지 않는 것이 좋습니다.

구문

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

별칭: partitionID

인수

• column1, column2, ... — 파티션 ID를 반환할 컬럼입니다.

반환 값

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

예시

사용 예시

Query

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;

Response

┌─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.0

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

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

구문

queryID()

별칭: query_id

인수

• 없음.

반환 값

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

예시

사용 예시

Query

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());

Response

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

​

revision

도입된 버전: v22.7.0

현재 ClickHouse 서버의 리비전을 반환합니다.

구문

revision()

인수

• 없음.

반환 값

현재 ClickHouse 서버의 리비전을 반환합니다. UInt32

예시

사용 예시

Query

SELECT revision()

Response

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

​

rowNumberInAllBlocks

도입된 버전: v1.1.0

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

구문

rowNumberInAllBlocks()

인수

• None.

반환 값

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

예시

사용 예시

Query

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

Response

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

​

rowNumberInBlock

도입 버전: v1.1.0

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

반환되는 번호는 각 블록에서 0부터 시작합니다.

구문

rowNumberInBlock()

인수

• 없음.

반환 값

0부터 시작하는 데이터 블록 내 행 번호를 반환합니다. UInt64

예시

사용 예시

Query

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

Response

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

​

runningAccumulate

도입 버전: v1.1.0

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

사용 중단 예정

상태는 새 데이터 블록이 시작될 때마다 재설정됩니다. 이러한 오류를 유발하기 쉬운 동작 때문에 이 함수는 사용 중단 예정이며, 대신 윈도우 함수를 사용하는 것이 좋습니다. 이 함수의 사용을 허용하려면 SETTING allow_deprecated_error_prone_window_functions를 사용할 수 있습니다.

구문

runningAccumulate(agg_state[, grouping])

인수

• agg_state — 집계 함수의 상태입니다. AggregateFunction
• grouping — 선택 사항입니다. 그룹화 키입니다. grouping 값이 바뀌면 함수 상태가 재설정됩니다. 같음 연산자가 정의된 지원 데이터 타입이라면 무엇이든 사용할 수 있습니다. Any

반환 값

각 행의 누적 결과를 반환합니다. Any

예시

initializeAggregation을 사용하는 사용 예시

Query

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);

Response

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

​

runningConcurrency

도입 버전: v21.3.0

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

요구 사항

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

사용 중단 예정

대신 윈도우 함수를 사용하는 것이 좋습니다.

구문

runningConcurrency(start, end)

인수

• start — 이벤트 시작 시간을 나타내는 컬럼입니다. Date 또는 DateTime 또는 DateTime64
• end — 이벤트 종료 시간을 나타내는 컬럼입니다. Date 또는 DateTime 또는 DateTime64

반환 값

각 이벤트 시작 시점에 동시에 진행 중인 이벤트 수를 반환합니다. UInt32

예시

사용 예시

Query

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

Response

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

​

runningDifference

도입 버전: v1.1.0

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

사용 중단 예정

현재 처리 중인 데이터 블록 내부의 차이만 반환합니다. 이러한 동작은 오류를 유발하기 쉬우므로 이 함수는 사용 중단 예정입니다. 대신 윈도우 함수를 사용하는 것이 좋습니다.

이 함수의 사용을 허용하려면 SETTING allow_deprecated_error_prone_window_functions을 사용할 수 있습니다.

함수의 결과는 처리되는 데이터 블록과 블록 내 데이터 순서에 따라 달라집니다. runningDifference() 계산 시의 행 순서는 사용자에게 반환되는 행 순서와 다를 수 있습니다. 이를 방지하려면 ORDER BY가 포함된 서브쿼리를 만들고, 해당 서브쿼리 바깥에서 함수를 호출할 수 있습니다. 블록 크기가 결과에 영향을 준다는 점에 유의하십시오. runningDifference의 내부 상태는 새 블록마다 재설정됩니다.

구문

runningDifference(x)

인수

• x — 연속된 값의 차이를 계산할 컬럼입니다. Any

반환 값

첫 번째 행은 0이며, 연속된 값 사이의 차이를 반환합니다.

예시

사용 예시

Query

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

Response

┌─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 │
└─────────┴─────────────────────┴───────┘

블록 크기에 따른 영향 예시

Query

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

Response

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

​

runningDifferenceStartingWithFirstValue

도입 버전: v1.1.0

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

사용 중단 예정

현재 처리 중인 데이터 블록 내에서의 차이만 반환합니다. 이러한 오류 발생 가능성이 높은 동작 때문에 이 함수는 사용 중단 예정입니다. 대신 윈도우 함수를 사용하는 것이 좋습니다.

이 함수 사용을 허용하려면 SETTING allow_deprecated_error_prone_window_functions를 사용할 수 있습니다.

구문

runningDifferenceStartingWithFirstValue(x)

인수

• x — running difference를 계산할 컬럼입니다. Any

반환 값

연속된 값 사이의 차이를 반환합니다. 첫 번째 행에는 해당 행의 값 자체가 반환됩니다. Any

예시

사용 예시

Query

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

Response

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

​

serverUUID

도입 버전: v20.1.0

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

구문

serverUUID()

인수

• 없음.

반환 값

서버의 무작위 UUID를 반환합니다. UUID

예시

사용 예시

Query

SELECT serverUUID();

Response

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

​

shardCount

도입 버전: v21.9.0

분산 쿼리의 전체 세그먼트 수를 반환합니다. 쿼리가 분산 쿼리가 아니면 상수 값 0을 반환합니다.

구문

shardCount()

인수

• 없음.

반환 값

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

예시

사용 예시

Query

-- 위의 shardNum() 예시를 참조하세요. shardCount()도 함께 설명합니다.
CREATE TABLE shard_count_example (dummy UInt8)
ENGINE=Distributed(test_cluster_two_shards_localhost, system, one, dummy);
SELECT shardCount() FROM shard_count_example;

Response

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

​

shardNum

도입 버전: v21.9.0

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

구문

shardNum()

인수

• 없음.

반환 값

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

예시

사용 예시

Query

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;

Response

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

​

showCertificate

도입 버전: v22.6.0

현재 서버에 Secure Sockets Layer(SSL) 인증서가 구성된 경우 해당 정보를 표시합니다. ClickHouse가 OpenSSL 인증서를 사용해 연결을 검증하도록 구성하는 방법에 대한 자세한 내용은 TLS 구성을 참조하십시오.

구문

showCertificate()

인수

• 없음.

반환 값

설정된 SSL 인증서와 관련된 key-value 쌍의 맵을 반환합니다. Map(String, String)

예시

사용 예시

Query

SELECT showCertificate() FORMAT LineAsString;

Response

{'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.0

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

sleep() 함수는 쿼리 성능과 시스템 응답성에 부정적인 영향을 줄 수 있으므로, 일반적으로 프로덕션 환경에서는 사용하지 않는 것이 좋습니다. 하지만 다음과 같은 시나리오에서는 유용할 수 있습니다:

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

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

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

구문

sleep(seconds)

인수

• seconds — 쿼리 실행을 최대 3초 동안 일시 중지할 초 단위 시간입니다. 소수 단위 초를 지정하려면 부동소수점 값을 사용할 수 있습니다. const UInt* 또는 const Float*

반환 값

0을 반환합니다. UInt8

예시

사용 예시

Query

-- 이 쿼리는 완료되기 전에 2초 동안 일시 중지됩니다.
-- 이 시간 동안 결과가 반환되지 않으며, 쿼리가 중단되거나 응답이 없는 것처럼 보입니다.
SELECT sleep(2);

Response

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

​

sleepEachRow

도입 버전: v1.1.0

결과 집합(result set)의 각 행마다 지정한 초 수만큼 쿼리 실행을 일시 중지합니다.

sleepEachRow() 함수는 sleep() 함수와 마찬가지로 주로 테스트 및 디버깅 용도로 사용됩니다. 이 함수를 사용하면 각 행을 처리할 때 지연을 시뮬레이션하거나 일시 중지를 넣을 수 있으므로, 다음과 같은 상황에서 유용합니다:

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

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

구문

sleepEachRow(seconds)

인수

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

반환 값

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

예시

사용 예시

Query

-- 각 행마다 0.5초씩 일시 정지되어 출력이 지연됩니다.
SELECT number, sleepEachRow(0.5) FROM system.numbers LIMIT 5;

Response

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

​

structureToCapnProtoSchema

도입 버전: v23.8.0

ClickHouse 테이블 구조를 CapnProto 포맷의 스키마로 변환하는 함수

구문

structureToCapnProtoSchema(table_structure, message)

인수

• 없음.

반환 값

예시

random

Query

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

Response

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

​

structureToProtobufSchema

도입 버전: v23.8.0

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

이 함수는 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 스키마로 변환하기

Query

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

Response

syntax = "proto3";

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

​

tcpPort

도입 버전: v20.12.0

서버가 수신 대기 중인 네이티브 인터페이스 TCP 포트 번호를 반환합니다. 분산 테이블에서 실행하면, 이 함수는 각 세그먼트에 해당하는 값을 가진 일반 컬럼을 반환합니다. 그렇지 않으면 상수 값을 반환합니다.

구문

tcpPort()

인수

• 없음.

반환 값

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

예시

사용 예시

Query

SELECT tcpPort()

Response

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

​

throwIf

도입 버전: v1.1.0

인수 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

반환 값

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

예시

사용 예시

Query

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

Response

↙ 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.0

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

구문

toColumnTypeName(value)

인수

• value — 내부 데이터 타입을 반환할 값입니다. Any

반환 값

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

예시

사용 예시

Query

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

Response

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

​

toTypeName

도입 버전: v1.1.0

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

구문

toTypeName(x)

인수

• x — 임의 유형의 값입니다. Any

반환 값

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

예시

사용 예시

Query

SELECT toTypeName(123)

Response

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

​

tokenizeQuery

도입 버전: v26.5.0

ClickHouse SQL 쿼리 문자열을 토큰화하여 토큰 배열을 반환합니다. 각 토큰은 시작 위치(바이트 단위), 끝 위치, 토큰 유형을 포함하는 named tuple입니다.

구문

tokenizeQuery(query)

인수

• query — ClickHouse SQL 쿼리 문자열입니다. String.

반환 값

쿼리의 토큰을 나타내는 named tuple (begin UInt64, end UInt64, type Enum8(...))의 배열입니다. Array(Tuple(begin UInt64, end UInt64, type Enum8(...)))

예시

간단한 예시

Query

SELECT tokenizeQuery('SELECT 1')

Response

[(0,6,'BareWord'),(6,7,'Whitespace'),(7,8,'Number')]

​

transactionID

도입 버전: v22.6.0

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

이 함수는 실험적 기능 세트에 포함됩니다. 실험적 트랜잭션 지원을 활성화하려면 구성에 다음 설정을 추가하세요:

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

자세한 내용은 트랜잭션(ACID) 지원 페이지를 참조하세요.

구문

transactionID()

인수

• None.

반환 값

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

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

예시

사용 예시

Query

BEGIN TRANSACTION;
SELECT transactionID();
ROLLBACK;

Response

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

​

transactionLatestSnapshot

도입된 버전: v22.6.0

읽기 가능한 트랜잭션의 가장 최신 스냅샷(Commit Sequence Number)을 반환합니다.

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

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

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

구문

transactionLatestSnapshot()

인수

• 없음.

반환 값

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

예시

사용 예시

Query

BEGIN TRANSACTION;
SELECT transactionLatestSnapshot();
ROLLBACK;

Response

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

​

transactionOldestSnapshot

도입 버전: v22.6.0

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

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

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

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

구문

transactionOldestSnapshot()

인수

• 없음.

반환 값

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

예시

사용 예시

Query

BEGIN TRANSACTION;
SELECT transactionOldestSnapshot();
ROLLBACK;

Response

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

​

transform

도입 버전: v1.1.0

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

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

• transform(x, array_from, array_to, default) - 일치하는 요소가 없을 때 기본값을 사용하여 매핑 배열로 x를 변환합니다
• transform(x, array_from, array_to) - 동일하게 변환하지만 일치하는 값을 찾지 못하면 원래 x를 반환합니다

이 함수는 array_from에서 x를 찾고, 동일한 인덱스에 있는 array_to의 해당 요소를 반환합니다. array_from에서 x를 찾지 못하면 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 여기서 모든 타입은 동일해야 합니다

구문

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(제공된 경우) 또는 x(default가 제공되지 않은 경우)를 반환합니다. Any

예시

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

Query

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

Response

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

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

Query

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

Response

┌─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

Introduced in: v22.9.0

두 uniqThetaSketch 객체의 교집합(집합 연산 ∩)을 계산합니다. 결과는 새로운 uniqThetaSketch 객체입니다.

구문

uniqThetaIntersect(uniqThetaSketch,uniqThetaSketch)

인수

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

반환 값

교집합 결과를 포함하는 새로운 uniqThetaSketch입니다. UInt64

예시

사용 예시

Query

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);

Response

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

​

uniqThetaNot

도입 버전: v22.9.0

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

구문

uniqThetaNot(uniqThetaSketch,uniqThetaSketch)

인수

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

반환 값

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

예시

사용 예시

Query

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);

Response

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

​

uniqThetaUnion

도입 버전: v22.9.0

두 개의 uniqThetaSketch 객체에 대해 union 계산(집합 연산 ∪)을 수행하며, 결과로 새로운 uniqThetaSketch가 반환됩니다.

구문

uniqThetaUnion(uniqThetaSketch,uniqThetaSketch)

인수

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

반환 값

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

예시

사용 예시

Query

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);

Response

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

​

uptime

도입 버전: v1.1.0

서버의 업타임을 초 단위로 반환합니다. 분산 테이블의 컨텍스트에서 실행하면, 이 함수는 각 세그먼트에 해당하는 값이 들어 있는 일반 컬럼을 생성합니다. 그렇지 않으면 상수 값을 반환합니다.

구문

uptime()

인수

• 없음.

반환 값

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

예시

사용 예시

Query

SELECT uptime() AS Uptime

Response

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

​

variantElement

도입 버전: v25.2.0

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

구문

variantElement(variant, type_name[, default_value])

인수

• variant — Variant 컬럼입니다. Variant
• type_name — 추출할 variant 유형의 이름입니다. String
• default_value — variant에 지정된 유형의 variant가 없을 경우 사용할 기본값입니다. 어떤 유형이든 가능합니다. 선택 사항입니다. Any

반환 값

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

예시

사용 예시

Query

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;

Response

┌─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.0

Variant 컬럼의 각 행에 대해 variant type의 이름을 반환합니다. 행에 NULL이 포함된 경우 해당 행에 대해 ‘None’을 반환합니다.

구문

variantType(variant)

인수

• variant — Variant 컬럼. Variant

반환 값

각 행의 variant 타입 이름을 나타내는 Enum 컬럼을 반환합니다. Enum

예시

사용 예시

Query

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;

Response

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

​

version

도입 버전: v1.1.0

ClickHouse의 현재 버전을 major_version.minor_version.patch_version.number_of_commits_since_the_previous_stable_release 형식의 문자열로 반환합니다. 분산 테이블에서 실행되면 이 함수는 각 세그먼트에 해당하는 값을 갖는 일반 컬럼을 생성합니다. 그렇지 않으면 상수 값을 반환합니다.

구문

version()

인수

• None.

반환 값

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

예시

사용 예시

Query

SELECT version()

Response

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

​

visibleWidth

도입 버전: v1.1.0

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

구문

visibleWidth(x)

인수

• x — 모든 데이터 타입의 값입니다. Any

반환 값

텍스트 포맷으로 표시될 때 값의 대략적인 너비를 반환합니다. UInt64

예시

NULL의 표시 너비 계산

Query

SELECT visibleWidth(NULL)

Response

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

​

zookeeperSessionUptime

도입 버전: v21.11.0

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

구문

zookeeperSessionUptime()

인수

• 없음.

반환 값

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

예시

사용 예시

Query

SELECT zookeeperSessionUptime();

Response

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