벡터 함수

원문 보기 위키 갱신 2026.10.11

벡터 함수 (Vector Functions)

Turso는 벡터 임베딩을 저장하고 조회하는 내장 함수를 제공해요. 벡터는 압축된 이진 형식의 BLOB으로 저장되고, 거리 함수로 비교해서 유사도 검색을 할 수 있어요.

출처: 문서

본문

**Turso 확장 기능**: 벡터 함수는 SQL에서 벡터 임베딩을 직접 다루는 Turso 전용 기능이에요. SQLite 표준에는 없는 함수들이에요.

Turso는 벡터 임베딩을 저장하고 조회하기 위한 내장 함수를 제공해요. 벡터는 압축된 이진 형식의 BLOB으로 저장되고, 유사도 검색을 위해 거리 함수로 비교할 수 있어요.

벡터 만들기

vector32

숫자 JSON 배열로 32비트 부동소수점 벡터를 만들어요.

vector32(json_array)

매개변수	타입	설명
`json_array`	TEXT	숫자 JSON 배열. 예: `'[1.0, 2.0, 3.0]'`

반환: BLOB -- 32비트 float 이진 형식의 벡터.

가장 흔히 쓰이는 벡터 형식으로, 정밀도와 저장 효율의 균형이 좋아요. 각 차원이 4바이트를 사용해요.

SELECT vector32('[1.0, 2.0, 3.0]');
-- (BLOB: 12 bytes)

-- Store embeddings in a table
CREATE TABLE documents (
    id INTEGER PRIMARY KEY,
    content TEXT,
    embedding BLOB
);

INSERT INTO documents VALUES (1, 'Introduction to databases', vector32('[0.1, 0.3, 0.5, 0.7]'));

vector64

숫자 JSON 배열로 64비트 부동소수점 벡터를 만들어요.

vector64(json_array)

매개변수	타입	설명
`json_array`	TEXT	숫자 JSON 배열. 예: `'[1.0, 2.0, 3.0]'`

반환: BLOB -- 64비트 float 이진 형식의 벡터.

더 높은 정밀도가 필요할 때 이 형식을 쓰세요. 각 차원이 8바이트를 사용해요.

SELECT vector64('[1.0, 2.0, 3.0]');
-- (BLOB: 24 bytes)

vector

기본 형식(32비트 float)으로 벡터를 만들어요.

vector(json_array)

매개변수	타입	설명
`json_array`	TEXT	숫자 JSON 배열

반환: BLOB -- 기본(32비트 float) 이진 형식의 벡터.

SELECT vector('[1.0, 2.0, 3.0]');

vector8

숫자 JSON 배열로 8비트 양자화(quantized) 벡터를 만들어요.

vector8(json_array)

매개변수	타입	설명
`json_array`	TEXT	정수 값(0-255)의 JSON 배열

반환: BLOB -- 8비트 정수 이진 형식의 벡터.

저장 효율이 좋은 근사 표현이 필요할 때 이 형식을 쓰세요. 각 차원이 1바이트를 사용해요.

SELECT vector8('[128, 64, 255, 0]');

vector1bit

JSON 배열로 1비트 이진 벡터를 만들어요.

vector1bit(json_array)

매개변수	타입	설명
`json_array`	TEXT	0과 1의 JSON 배열

반환: BLOB -- 1비트 이진 형식의 벡터.

극도로 압축된 표현이 필요할 때 이 형식을 쓰세요. 여덟 개 차원이 한 바이트에 들어가요.

SELECT vector1bit('[1, 0, 1, 1, 0, 0, 1, 0]');

vector32_sparse

숫자 JSON 배열로 32비트 부동소수점 희소(sparse) 벡터를 만들어요. 0이 아닌 성분만 저장되기 때문에, 대부분이 0인 고차원 벡터에 효율적이에요.

vector32_sparse(json_array)

매개변수	타입	설명
`json_array`	TEXT	숫자 JSON 배열. 보통 0이 많아요

반환: BLOB -- 32비트 float 희소 이진 형식의 벡터.

SELECT vector32_sparse('[0.0, 0.0, 1.5, 0.0, 0.0, 2.5]');

희소 벡터는 실험적인 희소 벡터 인덱스 방식으로 인덱싱할 수 있어요 (`--experimental-index-method` 활성화 필요). [CREATE INDEX](/sql-reference/statements/create-index)를 참고하세요.

거리 함수

거리 함수는 두 벡터 사이의 거리를 계산해요. 값이 작을수록 더 비슷한 벡터예요.

vector_distance_cos

두 벡터의 코사인 거리를 계산해요. 1 - cosine_similarity로 정의돼요. 결과가 0이면 방향이 동일하고, 1이면 서로 수직(orthogonal)이라는 뜻이에요.

vector_distance_cos(v1, v2)

매개변수	타입	설명
`v1`	BLOB	첫 번째 벡터
`v2`	BLOB	두 번째 벡터 (`v1`과 차원 수가 같아야 해요)

반환: REAL -- 두 벡터의 코사인 거리.

SELECT vector_distance_cos(
    vector32('[1.0, 0.0, 0.0]'),
    vector32('[0.0, 1.0, 0.0]')
);
-- 1.0 (orthogonal vectors)

SELECT vector_distance_cos(
    vector32('[1.0, 0.0]'),
    vector32('[1.0, 0.0]')
);
-- 0.0 (identical vectors)

vector_distance_l2

두 벡터의 유클리드(L2) 거리를 계산해요. 결과가 0이면 벡터가 동일하다는 뜻이에요.

vector_distance_l2(v1, v2)

매개변수	타입	설명
`v1`	BLOB	첫 번째 벡터
`v2`	BLOB	두 번째 벡터 (`v1`과 차원 수가 같아야 해요)

반환: REAL -- 두 벡터의 유클리드 거리.

SELECT vector_distance_l2(
    vector32('[1.0, 0.0, 0.0]'),
    vector32('[0.0, 1.0, 0.0]')
);
-- 1.4142135623730951

SELECT vector_distance_l2(
    vector32('[3.0, 4.0]'),
    vector32('[0.0, 0.0]')
);
-- 5.0

vector_distance_dot

두 벡터의 음의 내적 거리를 계산해요. 결과는 내적의 음수라서, 값이 작을수록(더 음수일수록) 유사도가 높아요.

vector_distance_dot(v1, v2)

매개변수	타입	설명
`v1`	BLOB	첫 번째 벡터
`v2`	BLOB	두 번째 벡터 (`v1`과 차원 수가 같아야 해요)

반환: REAL -- 두 벡터의 음의 내적.

SELECT vector_distance_dot(
    vector32('[1.0, 2.0, 3.0]'),
    vector32('[4.0, 5.0, 6.0]')
);
-- -32.0 (dot product is 32)

vector_distance_jaccard

두 이진 벡터의 자카드(Jaccard) 거리를 계산해요. vector1bit 벡터와 함께 쓰기에 가장 적합해요.

vector_distance_jaccard(v1, v2)

매개변수	타입	설명
`v1`	BLOB	첫 번째 벡터
`v2`	BLOB	두 번째 벡터 (`v1`과 차원 수가 같아야 해요)

반환: REAL -- 두 벡터의 자카드 거리.

유틸리티 함수

vector_extract

벡터 BLOB을 다시 JSON 텍스트 표현으로 변환해요.

vector_extract(vector_blob)

매개변수	타입	설명
`vector_blob`	BLOB	`vector32`, `vector64` 등 다른 벡터 함수로 만든 벡터

반환: TEXT -- 벡터 성분들의 JSON 배열 문자열.

SELECT vector_extract(vector32('[1.5, 2.5, 3.5]'));
-- [1.500000,2.500000,3.500000]

vector_concat

둘 이상의 벡터를 하나의 벡터로 이어 붙여요.

vector_concat(v1, v2, ...)

매개변수	타입	설명
`v1, v2, ...`	BLOB	이어 붙일 둘 이상의 벡터. 모든 벡터는 같은 타입이어야 해요.

반환: BLOB -- 모든 입력 벡터의 차원을 순서대로 담은 새 벡터.

SELECT vector_extract(
    vector_concat(
        vector32('[1.0, 2.0]'),
        vector32('[3.0, 4.0]')
    )
);
-- [1.000000,2.000000,3.000000,4.000000]

vector_slice

벡터의 연속된 구간을 뽑아내요.

vector_slice(vector_blob, start, end)

매개변수	타입	설명
`vector_blob`	BLOB	원본 벡터
`start`	INTEGER	시작 인덱스 (0부터 시작, 포함)
`end`	INTEGER	끝 인덱스 (제외)

반환: BLOB -- start부터 end - 1까지의 차원을 담은 새 벡터.

SELECT vector_extract(
    vector_slice(vector32('[10.0, 20.0, 30.0, 40.0, 50.0]'), 1, 4)
);
-- [20.000000,30.000000,40.000000]

예제

벡터 임베딩 테이블 만들기

CREATE TABLE articles (
    id INTEGER PRIMARY KEY,
    title TEXT NOT NULL,
    content TEXT,
    embedding BLOB
);

INSERT INTO articles VALUES (
    1,
    'Introduction to Machine Learning',
    'Machine learning is a subset of artificial intelligence...',
    vector32('[0.12, -0.34, 0.56, 0.78, -0.11, 0.45, -0.23, 0.67]')
);

INSERT INTO articles VALUES (
    2,
    'Database Design Patterns',
    'Relational databases organize data into tables...',
    vector32('[0.82, 0.15, -0.44, 0.23, 0.61, -0.33, 0.09, 0.77]')
);

INSERT INTO articles VALUES (
    3,
    'Neural Networks Explained',
    'Neural networks are computing systems inspired by biological neural networks...',
    vector32('[0.14, -0.28, 0.62, 0.71, -0.09, 0.51, -0.18, 0.59]')
);

ORDER BY 거리로 유사도 검색하기

-- Find articles most similar to a query embedding using cosine distance
SELECT
    id,
    title,
    vector_distance_cos(embedding, vector32('[0.1, -0.3, 0.5, 0.8, -0.1, 0.4, -0.2, 0.6]')) AS distance
FROM articles
ORDER BY distance ASC
LIMIT 5;

코사인 거리 vs. L2 거리

코사인 거리는 크기(magnitude)를 무시하고 두 벡터 사이의 각도를 측정해요. L2 거리는 공간상의 절대 거리를 측정해요.

-- Cosine distance: direction matters, not magnitude
SELECT vector_distance_cos(
    vector32('[1.0, 0.0]'),
    vector32('[100.0, 0.0]')
);
-- 0.0 (same direction, cosine distance is 0)

-- L2 distance: magnitude matters
SELECT vector_distance_l2(
    vector32('[1.0, 0.0]'),
    vector32('[100.0, 0.0]')
);
-- 99.0 (very far apart in absolute terms)

벡터의 방향이 중요할 때는 코사인 거리를 쓰세요 (예: 텍스트 임베딩의 의미적 유사도). 절대 위치가 중요할 때는 L2 거리를 쓰세요 (예: 지리 좌표나 이미지 특징 벡터).

벡터 데이터 다루기

-- Inspect the contents of a stored vector
SELECT vector_extract(embedding) FROM articles WHERE id = 1;

-- Concatenate vectors from two different models
SELECT vector_extract(
    vector_concat(
        (SELECT embedding FROM articles WHERE id = 1),
        (SELECT embedding FROM articles WHERE id = 2)
    )
);

-- Extract the first 4 dimensions of an embedding
SELECT vector_extract(
    vector_slice(embedding, 0, 4)
) FROM articles WHERE id = 1;
-- [0.120000,-0.340000,0.560000,0.780000]

기본적으로 유사도 검색은 테이블 전체를 선형으로 훑어요(linear scan). 실험적인 희소 벡터 인덱스 방식이 `--experimental-index-method` 플래그 뒤에 준비되어 있어요. 이 플래그 없이는, 데이터가 크다면 WHERE 절로 검색 범위를 일부 행으로 좁히는 걸 고려해 보세요.

더 알아보기 (Learn more)

CREATE INDEX - FTS를 포함한 인덱스 타입
데이터 타입 - Turso가 BLOB을 처리하는 방식