튜플 함수

튜플 함수 (Tuple functions)

튜플을 생성하고, 요소에 접근하며, 산술·거리 연산을 수행하는 함수들이에요. 아래 문서는 system.functions 시스템 테이블에서 생성된 내용입니다.

출처: 문서

본문

다음 내용은 system.functions 시스템 테이블에서 생성된 것입니다.

dotProduct

도입 버전: v21.11.0

두 벡터(같은 크기의 튜플 또는 배열)의 내적(dot product)(스칼라 곱)을 계산합니다. 대응하는 요소들의 곱의 합을 반환합니다.

구문

dotProduct(vector1, vector2)

별칭: scalarProduct

인자

  • vector1 — 첫 번째 벡터. Array(T) 또는 Tuple(T)
  • vector2 — 두 번째 벡터. 첫 번째 벡터와 같은 크기여야 합니다. Array(T) 또는 Tuple(T)

반환 값

두 벡터의 내적을 반환합니다. 두 BFloat16 배열은 누적되어 Float32로 반환됩니다. (U)Int* 또는 Float* 또는 Decimal

예제 — 기본 사용

Query

SELECT dotProduct((1, 2), (3, 4))

Response

11

flattenTuple

도입 버전: v22.6.0

이름 있는 중첩 튜플을 평탄화합니다. 반환된 튜플의 요소는 입력 튜플의 경로(path)입니다.

구문

flattenTuple(input)

인자

반환 값

요소가 원래 입력의 경로인 출력 튜플을 반환합니다. Tuple(T)

예제 — 사용 예시

Query

CREATE TABLE tab(t Tuple(a UInt32, b Tuple(c String, d UInt32))) ENGINE = MergeTree ORDER BY tuple();
INSERT INTO tab VALUES ((3, ('c', 4)));

SELECT flattenTuple(t) FROM tab;

Response

┌─flattenTuple(t)─┐
│ (3,'c',4)       │
└─────────────────┘

tuple

도입 버전: v1.1.0

입력 인자를 묶어 튜플을 반환합니다. 타입이 T1, T2, …인 컬럼 C1, C2, …에 대해, 이름이 고유하고 따옴표 없는 식별자로 취급될 수 있으면 이 컬럼들을 담은 이름 있는 Tuple(C1 T1, C2 T2, …) 타입 튜플을, 그렇지 않으면 Tuple(T1, T2, …)을 반환합니다. 함수 실행 비용은 없습니다.

튜플은 보통 IN 연산자의 인자 중간 값으로, 또는 람다 함수의 형식 파라미터 목록을 만드는 데 사용됩니다. 튜플은 테이블에 쓸 수 없습니다.

이 함수는 연산자 (x, y, ...)를 구현합니다.

구문

tuple([t1[, t2[ ...]]])

인자

  • 없음.

반환 값

예제 — 일반적인 사용

Query

SELECT tuple(1, 2)

Response

(1,2)

tupleConcat

도입 버전: v23.8.0

인자로 전달된 튜플들을 결합합니다.

구문

tupleConcat(tuple1[, tuple2, [...]]])

인자

  • tupleN — Tuple 타입의 임의 개수 인자. Tuple(T)

반환 값

입력 튜플들의 모든 요소를 담은 튜플을 반환합니다. Tuple(T)

예제 — 사용 예시

Query

SELECT tupleConcat((1, 2), ('a',), (true, false))

Response

(1,2,'a',true,false)

tupleDivide

도입 버전: v21.11.0

같은 크기의 둘 이상의 튜플을 왼쪽에서 오른쪽으로 요소별 나눗셈을 계산합니다.

0으로 나누면 inf를 반환합니다.

구문

tupleDivide(t1, t2[, tN, ...])

인자

반환 값

요소별 몫을 담은 튜플을 반환합니다. Tuple((U)Int*) 또는 Tuple(Float*) 또는 Tuple(Decimal)

예제 — 두 튜플

Query

SELECT tupleDivide((1, 2), (2, 3))

Response

(0.5,0.6666666666666666)

예제 — 세 튜플

Query

SELECT tupleDivide((100.0, 60.0), (5.0, 3.0), (2.0, 4.0))

Response

(10,5)

tupleDivideByNumber

도입 버전: v21.11.0

모든 요소를 숫자로 나눈 튜플을 반환합니다.

0으로 나누면 inf가 반환됩니다.

구문

tupleDivideByNumber(tuple, number)

인자

반환 값

나뉜 요소들을 담은 튜플을 반환합니다. Tuple((U)Int*) 또는 Tuple(Float*) 또는 Tuple(Decimal)

예제 — 기본 사용

Query

SELECT tupleDivideByNumber((1, 2), 0.5)

Response

(2,4)

tupleElement

도입 버전: v1.1.0

인덱스 또는 이름으로 튜플에서 요소를 추출합니다. 인덱스 접근은 1부터 시작하는 숫자 인덱스를 기대합니다. 이름 접근은 요소 이름을 문자열로 제공할 수 있습니다(이름 있는 튜플에만 동작). 음수 인덱스가 지원됩니다. 이 경우 끝에서부터 번호를 매긴 해당 요소가 선택됩니다. 예를 들어 tuple.-1은 튜플의 마지막 요소입니다. 선택적 세 번째 인자는 접근한 요소가 존재하지 않을 때 예외를 던지는 대신 반환할 기본 값을 지정합니다. 모든 인자는 상수여야 합니다.

이 함수는 런타임 비용이 0이며 x.index와 x.name 연산자를 구현합니다.

구문

tupleElement(tuple, index|name[, default_value])

인자

  • tuple — 튜플 또는 튜플 배열. Tuple(T) 또는 Array(Tuple(T))
  • index — 1부터 시작하는 컬럼 인덱스. const UInt8/16/32/64
  • name — 요소 이름. const String
  • default_value — 인덱스가 범위를 벗어나거나 요소가 존재하지 않을 때 반환되는 기본 값. Any

반환 값

지정된 인덱스 또는 이름의 요소를 반환합니다. Any

예제 — 인덱스 접근

Query

SELECT tupleElement((1, 'hello'), 2)

Response

hello

예제 — 음수 인덱싱

Query

SELECT tupleElement((1, 'hello'), -1)

Response

hello

예제 — 테이블과 함께 사용하는 이름 있는 튜플

Query

CREATE TABLE example (values Tuple(name String, age UInt32)) ENGINE = Memory;
INSERT INTO example VALUES (('Alice', 30));
SELECT tupleElement(values, 'name') FROM example;

Response

Alice

예제 — 기본 값 사용

Query

SELECT tupleElement((1, 2), 5, 'not_found')

Response

not_found

예제 — 연산자 구문

Query

SELECT (1, 'hello').2

Response

hello

tupleHammingDistance

도입 버전: v21.1.0

같은 크기의 두 튜플 사이의 해밍 거리를 반환합니다.

결과 타입은 입력 튜플의 요소 수에 따라 산술 함수와 같은 방식으로 결정됩니다.

SELECT
    toTypeName(tupleHammingDistance(tuple(0), tuple(0))) AS t1,
    toTypeName(tupleHammingDistance((0, 0), (0, 0))) AS t2,
    toTypeName(tupleHammingDistance((0, 0, 0), (0, 0, 0))) AS t3,
    toTypeName(tupleHammingDistance((0, 0, 0, 0), (0, 0, 0, 0))) AS t4,
    toTypeName(tupleHammingDistance((0, 0, 0, 0, 0), (0, 0, 0, 0, 0))) AS t5

┌─t1────┬─t2─────┬─t3─────┬─t4─────┬─t5─────┐
│ UInt8 │ UInt16 │ UInt32 │ UInt64 │ UInt64 │
└───────┴────────┴────────┴────────┴────────┘

구문

tupleHammingDistance(t1, t2)

인자

반환 값

해밍 거리를 반환합니다. UInt8/16/32/64

예제 — 사용 예시

Query

SELECT tupleHammingDistance((1, 2, 3), (3, 2, 1))

Response

2

예제 — MinHash로 준중복 문자열 감지

Query

SELECT tupleHammingDistance(wordShingleMinHash(string), wordShingleMinHashCaseInsensitive(string)) FROM (SELECT 'ClickHouse is a column-oriented database management system for online analytical processing of queries.' AS string)

Response

2

tupleIntDiv

도입 버전: v23.8.0

같은 크기의 둘 이상의 튜플을 왼쪽에서 오른쪽으로 요소별 정수 나눗셈을 수행하고 몫의 튜플을 반환합니다. 어떤 튜플에 정수가 아닌 요소가 있으면 각 정수가 아닌 분자·제수에 대해 가장 가까운 정수로 반올림해 계산합니다. 0으로 나누면 예외가 발생합니다.

구문

tupleIntDiv(t1, t2[, tN, ...])

인자

반환 값

정수 몫의 튜플을 반환합니다. Tuple((U)Int*) 또는 Tuple(Float*) 또는 Tuple(Decimal)

예제 — 두 튜플

Query

SELECT tupleIntDiv((15, 10, 5), (5, 5, 5))

Response

(3,2,1)

예제 — 소수 포함

Query

SELECT tupleIntDiv((15, 10, 5), (5.5, 5.5, 5.5))

Response

(2,1,0)

예제 — 세 튜플

Query

SELECT tupleIntDiv((120, 60), (4, 3), (2, 4))

Response

(15,5)

tupleIntDivByNumber

도입 버전: v23.8.0

분자들의 튜플을 주어진 분모로 정수 나눗셈하고 몫의 튜플을 반환합니다. 입력 파라미터 중 하나에 정수가 아닌 요소가 있으면 각 정수가 아닌 분자·제수에 대해 가장 가까운 정수로 반올림해 계산합니다. 0으로 나누면 오류가 발생합니다.

구문

tupleIntDivByNumber(tuple_num, div)

인자

반환 값

몫의 튜플을 반환합니다. Tuple((U)Int*) 또는 Tuple(Float*) 또는 Tuple(Decimal)

예제 — 기본 사용

Query

SELECT tupleIntDivByNumber((15, 10, 5), 5)

Response

(3,2,1)

예제 — 소수 포함

Query

SELECT tupleIntDivByNumber((15.2, 10.7, 5.5), 5.8)

Response

(2,1,0)

tupleIntDivOrZero

도입 버전: v23.8.0

tupleIntDiv처럼 같은 크기의 둘 이상의 튜플을 왼쪽에서 오른쪽으로 요소별 정수 나눗셈을 수행합니다. 0으로 나눌 때 예외를 던지는 대신 해당 요소에 0을 반환합니다. 어떤 튜플에 정수가 아닌 요소가 있으면 각 정수가 아닌 분자·제수에 대해 가장 가까운 정수로 반올림해 계산합니다.

구문

tupleIntDivOrZero(t1, t2[, tN, ...])

인자

반환 값

정수 몫의 튜플을 반환하며, 제수가 0인 요소는 0을 반환합니다. Tuple((U)Int*) 또는 Tuple(Float*) 또는 Tuple(Decimal)

예제 — 0 제수 포함

Query

SELECT tupleIntDivOrZero((5, 10, 15), (0, 0, 0))

Response

(0,0,0)

예제 — 세 튜플

Query

SELECT tupleIntDivOrZero((120, 60), (4, 3), (2, 4))

Response

(15,5)

tupleIntDivOrZeroByNumber

도입 버전: v23.8.0

tupleIntDivByNumber처럼 분자들의 튜플을 주어진 분모로 정수 나눗셈하고 몫의 튜플을 반환합니다. 0 제수에 대해 오류를 던지지 않고 몫을 0으로 반환합니다. 튜플이나 div에 정수가 아닌 요소가 있으면 각 정수가 아닌 분자·제수에 대해 가장 가까운 정수로 반올림해 계산합니다.

구문

tupleIntDivOrZeroByNumber(tuple_num, div)

인자

반환 값

제수가 0인 몫은 0으로 하는 몫의 튜플을 반환합니다. Tuple((U)Int*) 또는 Tuple(Float*) 또는 Tuple(Decimal)

예제 — 기본 사용

Query

SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 5)

Response

(3,2,1)

예제 — 0 제수 포함

Query

SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 0)

Response

(0,0,0)

tupleMinus

도입 버전: v21.11.0

같은 크기의 둘 이상의 튜플을 왼쪽에서 오른쪽으로 요소별 차를 계산합니다.

구문

tupleMinus(t1, t2[, tN, ...])

별칭: vectorDifference

인자

반환 값

요소별 차를 담은 튜플을 반환합니다. Tuple((U)Int*) 또는 Tuple(Float*) 또는 Tuple(Decimal)

예제 — 두 튜플

Query

SELECT tupleMinus((1, 2), (2, 3))

Response

(-1,-1)

예제 — 세 튜플

Query

SELECT tupleMinus((10, 10), (3, 4), (2, 1))

Response

(5,5)

tupleModulo

도입 버전: v23.8.0

같은 크기의 둘 이상의 튜플을 왼쪽에서 오른쪽으로 나눈 나머지의 튜플을 반환합니다.

구문

tupleModulo(t1, t2[, tN, ...])

인자

반환 값

요소별 나머지의 튜플을 반환합니다. 0으로 나누면 예외가 발생합니다. Tuple((U)Int*) 또는 Tuple(Float*) 또는 Tuple(Decimal)

예제 — 두 튜플

Query

SELECT tupleModulo((15, 10, 5), (5, 3, 2))

Response

(0,1,1)

예제 — 세 튜플

Query

SELECT tupleModulo((10, 20), (7, 9), (3, 5))

Response

(0,2)

tupleModuloByNumber

도입 버전: v23.8.0

튜플과 주어진 제수의 나눗셈 연산의 나머지(모듈로) 튜플을 반환합니다.

구문

tupleModuloByNumber(tuple_num, div)

인자

반환 값

나눗셈의 나머지 튜플을 반환합니다. 0으로 나누면 오류가 발생합니다. Tuple((U)Int*) 또는 Tuple(Float*) 또는 Tuple(Decimal)

예제 — 기본 사용

Query

SELECT tupleModuloByNumber((15, 10, 5), 2)

Response

(1,0,1)

tupleMultiply

도입 버전: v21.11.0

같은 크기의 둘 이상의 튜플의 요소별 곱을 계산합니다.

구문

tupleMultiply(t1, t2[, tN, ...])

인자

반환 값

요소별 곱을 담은 튜플을 반환합니다. Tuple((U)Int*) 또는 Tuple(Float*) 또는 Tuple(Decimal)

예제 — 두 튜플

Query

SELECT tupleMultiply((1, 2), (2, 3))

Response

(2,6)

tupleMultiplyByNumber

도입 버전: v21.11.0

모든 요소를 숫자로 곱한 튜플을 반환합니다.

구문

tupleMultiplyByNumber(tuple, number)

인자

반환 값

곱해진 요소들을 담은 튜플을 반환합니다. Tuple((U)Int*) 또는 Tuple(Float*) 또는 Tuple(Decimal)

예제 — 기본 사용

Query

SELECT tupleMultiplyByNumber((1, 2), 2)

Response

(2,4)

tupleNames

매개변수에 전달된 튜플의 이름을 반환합니다.

구문

tupleNames(tuple)

인자

  • tuple — 이름을 얻을 튜플. Tuple(T)

반환 값

문자열 배열 형태의 이름 목록을 반환합니다. Array(String)

예제 — 사용 예시

Query

SELECT tupleNames((1, 'Hello'))

Response

[]

Query

SELECT tupleNames((1 AS x, 'Hello' AS y))

Response

['x','y']

tupleNegate

도입 버전: v21.11.0

모든 요소의 부호를 뒤집은 튜플을 반환합니다.

구문

tupleNegate(tuple)

인자

반환 값

요소들의 부호를 뒤집은 튜플을 반환합니다. Tuple((U)Int*) 또는 Tuple(Float*) 또는 Tuple(Decimal)

예제 — 기본 사용

Query

SELECT tupleNegate((1, 2))

Response

(-1,-2)

tuplePlus

도입 버전: v21.11.0

같은 크기의 둘 이상의 튜플 요소별 합을 계산합니다.

구문

tuplePlus(t1, t2[, tN, ...])

별칭: vectorSum

인자

반환 값

요소별 합을 담은 튜플을 반환합니다. Tuple((U)Int*) 또는 Tuple(Float*) 또는 Tuple(Decimal)

예제 — 두 튜플

Query

SELECT tuplePlus((1, 2), (2, 3))

Response

(3,5)

예제 — 세 튜플

Query

SELECT tuplePlus((1, 2, 3), (4, 5, 6), (7, 8, 9))

Response

(12,15,18)

tuplePositiveModuloByNumber

도입 버전: v23.8.0

튜플의 각 요소와 주어진 제수 사이의 양의 모듈로를 계산합니다. 즉, 나머지가 항상 0 이상인 나눗셈입니다.

구문

tuplePositiveModuloByNumber(tuple_num, div)

인자

반환 값

각 요소의 양의 나머지 튜플을 반환합니다. Tuple((U)Int*) 또는 Tuple(Float*) 또는 Tuple(Decimal)

예제 — 기본 사용

Query

SELECT tuplePositiveModuloByNumber((-1, -2, 3), 5)

Response

(4,3,3)

tupleToNameValuePairs

도입 버전: v21.11.0

이름 있는 튜플을 (name, value) 쌍의 배열로 변환합니다. 익명 튜플의 경우 익명 요소들의 이름을 나타냅니다. 결과 배열의 요소 수는 원본 튜플과 같습니다. 결과의 name 요소는 유효한 ClickHouse 식별자에 대해서만 계산됩니다.

구문

tupleToNameValuePairs(tuple)

인자

반환 값

(name, value) 쌍의 배열을 반환합니다. Array(Tuple(String, T1), Tuple(String, T2), ...)

예제 — 사용 예시

Query

SELECT tupleToNameValuePairs((1 AS x, 'Hello' AS y))

Response

[('x',1),('y','Hello')]

untuple

도입 버전: v1.1.0

튜플의 요소를 추가 컬럼으로 변환합니다. 아쿠아리움 함수와 함께 사용할 수 있습니다.

구문

untuple(tuple)
SELECT untuple(tuple) FROM table

인자

반환 값

아무것도 없습니다. 이 함수는 SELECT의 지정된 열 집합에 튜플 요소를 확장합니다. 즉, 결과 열은 tuple의 요소들입니다. Tuple(T)

예제 — 사용 예시

Query

CREATE TABLE tab (t1 Tuple(Int32, String), t2 Tuple(Int32, String)) ENGINE = Log;
INSERT INTO tab VALUES ((1, 'Hello'), (2, 'World'));

SELECT untuple(t1) FROM tab;

Response

┌─_tuple_1─┬─_tuple_2─┐
│        1 │ Hello    │
│        2 │ World    │
└──────────┴──────────┘

거리 함수 (Distance functions)

L1Distance

도입 버전: v21.1.0

두 벡터(같은 요소 수의 튜플 또는 배열) 사이의 거리를 계산합니다. 결과 타입은 입력의 요소 수에 따라 산술 함수와 같은 방식으로 결정됩니다.

구문

L1Distance(tuple1, tuple2)

별칭: L1Norm, normL1

인자

반환 값

L1 거리를 반환합니다. Float64

예제 — 사용 예시

Query

SELECT L1Distance((1, 2), (3, 4))

Response

4

L2Distance

도입 버전: v21.1.0

두 개의 벡터(같은 요소 수의 튜플 또는 배열) 사이의 유클리드 거리를 계산합니다.

구문

L2Distance(tuple1, tuple2)

별칭: vectorDifference, distance

인자

반환 값

유클리드 거리를 반환합니다. Float64

예제 — 사용 예시

Query

SELECT L2Distance((1, 2), (3, 4))

Response

2.8284271247461903

L2SquaredDistance

도입 버전: v21.1.0

두 개의 벡터(같은 요소 수의 튜플 또는 배열) 사이의 유클리드 거리의 제곱을 계산합니다.

구문

L2SquaredDistance(tuple1, tuple2)

인자

반환 값

유클리드 거리의 제곱을 반환합니다. Float64

예제 — 사용 예시

Query

SELECT L2SquaredDistance((1, 2), (3, 4))

Response

8

LpDistance

도입 버전: v21.1.0

두 개의 벡터(같은 요소 수의 튜플 또는 배열) 사이의 Lp 거리(민코프스키 거리)를 계산합니다.

구문

LpDistance(tuple1, tuple2, p)

인자

반환 값

Lp 거리를 반환합니다. Float64

예제 — 사용 예시

Query

SELECT LpDistance((1, 2), (3, 4), 3)

Response

2.080083823051904

L1Norm

두 벡터 요소들의 절대값 합으로 정의되는 L1 규범(맨해튼 거리)을 계산합니다.

구문

L1Norm(tuple)

인자

반환 값

L1 규범 값을 반환합니다. Float64

예제 — 사용 예시

Query

SELECT L1Norm((1, 2, 3))

Response

6

L2Norm

두 벡터 요소들의 제곱 합의 제곱근으로 정의되는 L2 규범(유클리드 규범)을 계산합니다.

구문

L2Norm(tuple)

인자

반환 값

L2 규범 값을 반환합니다. Float64

예제 — 사용 예시

Query

SELECT L2Norm((1, 2, 3))

Response

3.7416573867739413

LpNorm

민코프스키 규범으로 정의되는 Lp 규범을 계산합니다.

구문

LpNorm(tuple, p)

인자

반환 값

Lp 규범 값을 반환합니다. Float64

예제 — 사용 예시

Query

SELECT LpNorm((1, 2, 3), 3)

Response

3.3019272488946263

LinfNorm

L-무한대(Linf) 규범을 계산합니다.

구문

LinfNorm(tuple)

인자

반환 값

Linf 규범 값을 반환합니다. Float64

예제 — 사용 예시

Query

SELECT LinfNorm((1, 2, 3))

Response

3

더 알아보기 (Learn more)