Pinecone 데이터 모델링 — Documents와 Records 이해하기

Pinecone 데이터 모델링 — Documents와 Records 이해하기

Pinecone에서 데이터를 모델링하는 방법은 두 가지고, 그 선택은 인덱스를 만들 때 결정돼요. 문서 스키마 인덱스는 문서를, 밀집·스파스 벡터 인덱스는 레코드를 담습니다.

출처: https://docs.pinecone.io/guides/index-data/data-modeling

Documents — 문서 스키마

문서(document) 는 문서 스키마를 가진 인덱스의 데이터 단위예요. 필수 _id 필드, 인덱스 스키마에 선언된 랭킹 필드, 그리고 임의의 메타데이터 필드를 가진 JSON 객체입니다.

문서 하나에 여러 필드 유형을 담을 수 있어요.

  • dense_vector — ANN 유사도 검색용
  • sparse_vector — 스파스 벡터 어휘 검색용
  • full_text_search가 켜진 string 필드 — BM25 랭킹과 Lucene 질의용

스키마에 선언되지 않은 필드는 메타데이터로 저장되어 필터링에 자동 인덱싱됩니다. 문장·숫자·불리언·문자열 배열 타입을 지원해요. 인덱스 하나당 FTS 문자열 필드는 최대 100개, 밀집 벡터 필드와 스파스 벡터 필드는 각각 최대 1개만 선언할 수 있습니다. 공개 미리보기에서는 인덱스 생성 후 스키마 마이그레이션이 지원되지 않으니 필드를 미리 잘 계획해야 해요.

Records — 벡터 API

레코드(record) 는 밀집·스파스 벡터 인덱스의 데이터 단위로, 벡터 하나(또는 혼합 하이브리드용으로 둘 다)와 선택적 메타데이터를 담아요.

  • 미리 만든 벡터를 upsert할 때: ID(고유 문자열), Vector, Metadata(선택, 평면 JSON)
  • 원시 텍스트를 upsert할 때: ID, Text(Pinecone이 벡터로 변환), Metadata(선택)

구조화된 ID와 메타데이터

레코드 ID는 데이터 유형을 반영하는 프리픽스를 붙여 구조화하면 좋아요. 예를 들어 document_id#chunk_number, tenant_id#document_id#chunk_id 같은 형태입니다. 이렇게 하면 애플리케이션이 어떤 레코드를 다뤄야 할지 빠르게 알아보고, 프리픽스로 목록 조회·갱신도 쉽습니다.

메타데이터는 질의 시 필터링에 쓰거나, 관련 청크를 잇고, 원본 데이터로 되돌아가기 위한 추적용으로 활용해요. 메타데이터 키는 문자열, 값은 문자열·숫자(64비트 부동소수점)·불리언·문자열 리스트 중 하나여야 합니다.

멀티테넌시 설계

테넌트(사용자·조직·프로젝트)별로 네임스페이스를 나누는 게 가장 효율적인 다중 테넌시 구현이에요. 질의가 해당 테넌트 데이터만 스캔하므로 성능이 좋고 비용도 낮아요. 반대로 모든 데이터를 한 네임스페이스에 두고 고카디널리티 ID 필터로 범위를 좁히는 것은 성능 저하와 $in/$nin 연산자 10,000개 값 제한 같은 문제가 있으니 피하는 게 좋습니다.

더 알아보기