벡터 데이터 유형

벡터는 미리 계산된 임베딩을 위한 열 데이터 유형입니다. 벡터 열은 행마다 부동 소수점 숫자 배열을 담습니다. 이 배열은 이미 사용 중인 임베딩 모델의 출력이며, 이를 설명하는 텍스트, 키, 금액, 차원과 같은 행에 있는 일반 프로젝트 테이블에 저장됩니다. 벡터 열은 일반 테이블의 일반 열이므로 팩트 테이블과 조인할 수 있고, 다른 열과 동일한 가져오기 및 변환 단계를 통해 로드됩니다. 나머지 데이터와 보조를 맞추기 위해 별도의 벡터 저장소를 프로비저닝하거나 채우거나 유지 관리할 필요가 없습니다.

그런 다음 AI: 벡터 검색 단계가 하나 이상의 쿼리 벡터와 가장 가까운 행을 찾으므로, 유사도 조회도 다른 단계와 똑같은 워크플로 단계가 됩니다.

벡터 열 선언

벡터는 워크플로 단계의 출력 열 매핑과 테이블의 열 속성에서 JSON, Bitmap과 함께 데이터 유형 목록의 반구조화 그룹에 표시됩니다. 가져오기 단계의 소스 데이터 유형으로는 제공되지 않습니다. 파일의 값은 숫자 목록으로 들어와 이미 벡터 유형으로 지정된 열에 저장되기 때문입니다. 워크플로 변수의 선언 유형처럼 단일 스칼라 유형이 필요한 곳에서도 제공되지 않습니다.

이 유형 자체에는 차원이 없습니다. 너비마다 하나씩 유형 계열을 두는 대신, 벡터 유형은 하나이고 열마다 벡터의 너비를 선언합니다.

벡터 너비

테이블의 열 세부 정보 패널을 열고 벡터 열을 선택한 다음, 벡터 너비를 각 임베딩에 담긴 값의 개수(768, 1024, 1536 등 사용 중인 모델이 생성하는 값)로 설정합니다. 이 필드는 Lakehouse v2(StarRocks) 프로젝트의 벡터 열에만 표시되며, 다른 곳에는 표시되지 않습니다.

선언한 너비는 모든 로드 경로에서 적용됩니다. 벡터 길이가 다른 행은 아무것도 저장되기 전에 거부되며, 거부 메시지에는 파일, 열, 행, 확인된 길이, 선언한 너비가 명시됩니다. 따라서 어떤 값이 얼마나 다른지 정확히 알 수 있습니다. 파일 로드에서는 행 번호가 파일 기준으로 1부터 계산됩니다. 이렇게 하면 잘린 파일이나 바뀐 임베딩 모델이 읽을 수 있는 실행 실패로 드러납니다.

이 검사는 임베딩이 들어오는 모든 경로에 적용됩니다.

Parquet 가져오기
REST 커넥터 — QuickBooks, Xero, Sage, Monday.com 포함
Singer 탭
원본에 직접 실행하는 원격 데이터베이스 쿼리
테이블에 프레임을 쓰는 워크플로 단계
아카이브 가져오기 또는 아카이브 복원. 이 경우 거부 메시지에 아카이브 파일이 명시됩니다.
테이블 번들 가져오기. 번들 내보내기는 벡터 열을 실제 벡터로 기록하므로, 번들을 내보냈다가 다시 가져와도 너비가 그대로 유지됩니다.

다음 두 가지는 이 검사에서 제외됩니다.

CSV 가져오기는 검사되지 않으며, 검사할 수도 없습니다. 변환 과정에서 너비를 확인하기 전에 배열이 텍스트로 바뀌므로, CSV는 다른 너비를 열에 넣을 수 있는 유일한 경로입니다.
행 수준 쓰기(개별 행이나 레코드 저장, 키 기반 커넥터의 행 저장)는 쓰기 시점에 해당 열이 벡터임을 확인할 수 있을 때 검사됩니다. 이는 일반적인 경우일 뿐 무조건적인 보장은 아닙니다.

테이블이 더 이상 벡터로 지정하지 않는 열에 남은 너비는 적용되지 않습니다. 열 유형을 다시 지정하면 해당 선언은 그 열에 저장되는 값을 더 이상 제어하지 않습니다.

행마다 너비가 다른 열은 검색할 수 없기 때문에 이 점이 중요합니다. 그런 열에 대한 벡터 검색은 열 이름을 알려 주는 메시지 대신 기반 엔진의 원시 오류와 함께 실패합니다. 따라서 임베딩을 CSV로 로드하는 경우에는 파일이 선언한 너비를 만들어 내도록 하거나, 배열을 Parquet로 준비해 가져오십시오. 그러면 검사가 자동으로 실행됩니다.

로드하기 전에 너비를 선언하십시오. 벡터 너비는 1 이상의 정수이며 돌아갈 빈 값이 없습니다. 필드를 비우면 저장된 값으로 복원되므로, 이 선언은 열 설계의 일부로 취급하십시오.

너비는 검색이 기준으로 삼는 값이기도 합니다. 열에 선언된 너비가 없으면, 검색은 쿼리를 저장된 벡터와 비교하기 전에 행 하나를 샘플링해 저장된 벡터의 너비를 알아내야 합니다.

벡터 로드

표준 가져오기 및 변환 단계로 벡터 열을 로드합니다. 열이 32비트 부동 소수점 목록인 Parquet 파일이 가장 직접적인 경로입니다. Parquet 가져오기는 이를 벡터 열에 바로 저장합니다.

모두 표준 단계로 구성되는 일반적인 엔드 투 엔드 흐름은 다음과 같습니다.

Parquet 가져오기(또는 다른 가져오기 단계) — 임베딩과 비즈니스 키를 테이블에 저장합니다. 이 테이블의 임베딩 열은 벡터 유형이며 벡터 너비가 선언되어 있어야 합니다.
Table Inner Join 단계 — 비즈니스 키를 기준으로 해당 테이블을, 임베딩이 설명하는 팩트 테이블 또는 참조 테이블과 조인합니다.
AI: 벡터 검색 — 쿼리 벡터와 가장 가까운 행을 찾아 일치 항목을 대상 테이블에 기록합니다.
Table Lookup 단계 — 표시하려는 설명 열을 일치한 행에 다시 가져옵니다.

파일을 읽을 수 있는 위치

너비를 검사하려면 벡터 열만 따로 읽어야 하므로, 열 단위로 읽을 수 있는 문서 계정이 필요합니다. S3, Google Cloud Storage, Azure Blob Storage가 이에 해당합니다. 다른 문서 계정에서 벡터 너비가 선언된 테이블로 Parquet를 가져오면 검사 없이 로드되지 않고 거부되므로, 파일을 S3, Google Cloud Storage 또는 Azure Blob Storage에 준비한 다음 그곳에서 가져오십시오. 이러한 계정에서 아카이브를 복원하는 경우도 마찬가지입니다. 복원은 복구 작업이므로 복원 시 읽을 수 있는 계정에 아카이브를 보관하십시오. 벡터 너비를 선언하지 않은 테이블과 다른 모든 가져오기 단계는 영향을 받지 않습니다.

가장 가까운 행 검색

AI: 벡터 검색 단계는 검색할 테이블, 하나 이상의 쿼리 벡터, 쿼리당 유지할 일치 항목 수를 입력으로 받아, 가장 가까운 행을 순위를 매긴 거리와 함께 대상 테이블에 기록합니다.

두 가지 거리 지표를 사용할 수 있으며, 둘 다 거리가 작을수록 더 가까운 행입니다.

코사인 — 크기를 무시한 두 벡터 사이의 각도입니다. 텍스트 임베딩에는 이 방식이 적절한 기본 선택입니다.
유클리드(L2) — 크기를 고려하는 직선 거리입니다.

내적은 의도적으로 제공하지 않습니다. 정규화되지 않은 벡터에서 내적은 거리가 아니며, 벡터 자신과의 거리가 음수로 나옵니다. 따라서 순위가 우연히 맞더라도 내적에 설정한 임곗값이나 단계가 보여 준 점수는 의미가 없습니다. 정규화된 임베딩에서는 코사인으로 순위를 매기면 내적과 같은 순서를 얻으므로 잃는 것이 없습니다.

전체 매개변수 목록은 AI: 벡터 검색을 참조하십시오.

검색은 근사가 아닌 정확한 검색

이 단계는 필터를 통과한 모든 행을 모든 쿼리 벡터와 비교합니다. 벡터 인덱스도, 근사도 없습니다. 결과는 실제로 가장 가까운 집합이며, 작업량은 검색한 행 수에 쿼리 벡터 수를 곱한 만큼 늘어납니다.

이에 맞게 규모를 정하십시오. 전체 말뭉치를 스캔해 일부에 관한 질문에 답하는 대신, 단계의 필터를 사용해 후보 행을 중요한 범위(하나의 엔터티, 하나의 기간, 하나의 문서 집합)로 좁히십시오. 항상 필터링하는 차원을 기준으로 임베딩 테이블을 나누고 관련 테이블만 검색하는 것이 검색 시간을 줄이는 가장 효과적인 방법입니다.

측정할 수 없는 행은 제외

거리를 측정할 수 없는 행은 가장 가까운 행인 것처럼 반환되지 않고 일치 항목에서 제외됩니다. 진단 모드를 켜고 워크플로를 실행하면 로그에 쿼리마다 제외된 행 수가 보고되거나, 단계가 검색한 모든 행을 측정했다고 표시됩니다.

배열 안에 누락된 값이 있는 저장된 벡터는 건너뛰지 않고 거부됩니다. 그런 배열에 대해서는 거리를 측정할 수 없으므로, 검색은 부분적인 답을 반환하는 대신 중지하고 열 이름을 알려 줍니다.

벡터 열이 할 수 없는 일

임베딩은 키나 측정값이 아니라 좌표이므로, 벡터 열을 키나 측정값처럼 취급하는 역할에서는 거부됩니다.

조인 키가 될 수 없습니다. 벡터 옆에 있는 비즈니스 키로 조인하십시오.
그룹화 열이 될 수 없습니다. 원시 임베딩으로 행을 그룹화하면 모든 행이 각각 별도의 그룹이 됩니다.
집계 대상이 될 수 없습니다. 임베딩의 합계, 평균, 최솟값, 최댓값은 의미가 없습니다.

세 경우 모두 열과 역할을 명시한 메시지와 함께 거부되며, 단계를 저장할 때 거부되고 이전에 저장된 단계는 실행 시 다시 거부됩니다. 이 중 하나를 포함한 워크플로는 실행되지 않으므로 잘못된 숫자가 조용히 만들어지는 일이 없습니다. 벡터를 일반 출력 열로 단계에 통과시키는 것은 문제가 없으며, 행 수 세기와 고유 값 수 세기도 가능합니다.

벡터 열은 테이블 탐색기의 열 프로파일링과 값 목록에서도 제외되고, 대시보드에서 차트로 만들 수 없으며, 데이터 편집기에서 읽기 전용이고, 차원에 연결할 수 없습니다. 최솟값, 평균, 상위 값 목록은 임베딩에 대해 아무것도 알려 주지 않으며, 임베딩은 어떤 것의 멤버도 아니기 때문입니다.

벡터 값 다시 읽기

미리 보기, 내보내기, MCP를 통한 AI 어시스턴트에서 벡터 열 전체를 읽으면 숫자가 아니라 배열의 텍스트 표현이 반환됩니다. 숫자를 얻으려면 요소를 개별적으로 읽으십시오.

데이터 그리드에서는 값이 너비로 시작하는 짧은 미리 보기(예: 1536-dim [0.013,-0.046,0.079, ...])로 표시되므로, 셀마다 숫자 천 개를 표시하지 않고도 임베딩 열을 읽기 쉽게 유지할 수 있습니다.