DuckDB 벡터 저장소

DuckDB 스토리지 구현은 다음을 사용하여 임베디드 고성능 벡터 검색 솔루션을 제공합니다.DuckDB, 처리 중인 분석 데이터베이스입니다. HNSW 인덱싱과 함께 벡터 유사성 검색을 위해 VSS 확장을 사용하여 외부 서버가 필요 없는 가볍고 효율적인 벡터 데이터베이스를 제공합니다.

@mastra/duckdb 패키지의 일부이며, 메타데이터 필터링을 지원하는 효율적인 벡터 유사도 검색 기능을 제공합니다.

설치

npm

npm install @mastra/duckdb@latest

pnpm

pnpm add @mastra/duckdb@latest

Yarn

yarn add @mastra/duckdb@latest

Bun

bun add @mastra/duckdb@latest

용법

import { DuckDBVector } from "@mastra/duckdb";

// Create a new vector store instance
const store = new DuckDBVector({
  id: "duckdb-vector",
  path: ":memory:", // or './vectors.duckdb' for file persistence
});

// Create an index
await store.createIndex({
  indexName: "myCollection",
  dimension: 1536,
  metric: "cosine",
});

// Add vectors with metadata
const vectors = [[0.1, 0.2, ...], [0.3, 0.4, ...]];
const metadata = [
  { text: "first document", category: "A" },
  { text: "second document", category: "B" },
];
await store.upsert({
  indexName: "myCollection",
  vectors,
  metadata,
});

// Query similar vectors
const queryVector = [0.1, 0.2, ...];
const results = await store.query({
  indexName: "myCollection",
  queryVector,
  topK: 10,
  filter: { category: "A" },
});

// Clean up
await store.close();

생성자 옵션

id:

string

벡터 저장소 인스턴스의 고유 식별자

path?:

string

= ':memory:'

데이터베이스 파일 경로. 인메모리 데이터베이스에는 ':memory:'를 사용하고, 영구 저장에는 './vectors.duckdb'와 같은 파일 경로를 사용합니다.

dimensions?:

number

= 1536

벡터 임베딩의 기본 차원

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

유사도 검색의 기본 거리 측정 방식

행동 양식

createIndex()

가장 가까운 이웃을 빠르게 대략적으로 검색하기 위해 선택적 HNSW 인덱스를 사용하여 새 벡터 컬렉션을 만듭니다.

indexName:

string

생성할 인덱스의 이름

dimension:

number

벡터 차원 크기(임베딩 Model과 일치해야 함)

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

유사도 검색에 사용할 거리 측정 방식

upsert()

인덱스에 벡터와 해당 메타데이터를 추가하거나 업데이트합니다.

indexName:

string

데이터를 삽입할 인덱스의 이름

vectors:

number[][]

임베딩 벡터 배열

metadata?:

Record<string, any>[]

각 벡터의 메타데이터

ids?:

string[]

선택적 벡터 ID(제공하지 않으면 UUID 자동 생성)

query()

선택적 메타데이터 필터링을 사용하여 유사한 벡터를 검색합니다.

indexName:

string

검색할 인덱스의 이름

queryVector:

number[]

유사한 벡터를 찾는 데 사용할 쿼리 벡터

topK?:

number

= 10

반환할 결과 수

filter?:

Filter

MongoDB와 유사한 쿼리 구문을 사용하는 메타데이터 필터

includeVector?:

boolean

= false

결과에 벡터 데이터를 포함할지 여부

describeIndex()

인덱스에 대한 정보를 가져옵니다.

indexName:

string

설명할 인덱스의 이름

보고:

interface IndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
}

deleteIndex()

인덱스와 해당 데이터를 모두 삭제합니다.

indexName:

string

삭제할 인덱스의 이름

listIndexes()

데이터베이스의 모든 벡터 인덱스를 나열합니다.

보고:Promise<string[]>

updateVector()

ID 또는 메타데이터 필터를 기준으로 단일 벡터를 업데이트합니다. id 또는 filter 중 하나만 제공해야 하며, 둘 다 제공해서는 안 됩니다.

indexName:

string

벡터가 포함된 인덱스의 이름

id?:

string

업데이트할 벡터 항목의 ID(filter와 함께 사용할 수 없음)

filter?:

Record<string, any>

업데이트할 벡터를 식별하는 메타데이터 필터(id와 함께 사용할 수 없음)

update:

object

벡터 및/또는 메타데이터가 포함된 업데이트 데이터

update.vector?:

number[]

업데이트할 새 벡터 데이터

update.metadata?:

Record<string, any>

업데이트할 새 메타데이터

deleteVector()

ID별로 인덱스에서 특정 벡터 항목을 삭제합니다.

indexName:

string

벡터가 포함된 인덱스의 이름

id:

string

삭제할 벡터 항목의 ID

deleteVectors()

ID 또는 메타데이터 필터를 기준으로 여러 벡터를 삭제합니다. ids 또는 filter 중 하나만 제공해야 하며, 둘 다 제공해서는 안 됩니다.

indexName:

string

삭제할 벡터가 포함된 인덱스의 이름

ids?:

string[]

삭제할 벡터 ID 배열(filter와 함께 사용할 수 없음)

filter?:

Record<string, any>

삭제할 벡터를 식별하는 메타데이터 필터(ids와 함께 사용할 수 없음)

close()

데이터베이스 연결을 닫고 리소스를 해제합니다.

await store.close()

응답 유형

쿼리 결과는 다음 형식으로 반환됩니다.

interface QueryResult {
  id: string
  score: number
  metadata: Record<string, any>
  vector?: number[] // Only included if includeVector is true
}

필터 연산자

DuckDB 벡터 저장소는 MongoDB와 유사한 필터 연산자를 지원합니다.

카테고리	운영자
비교	$eq, $ne, $gt, $gte, $lt, $lte
Logical	$and, $or, $not, $nor
Array	$in, $nin
Element	$exists
텍스트	$contains

필터 예

// Allegato operators
const results = await store.query({
  indexName: "docs",
  queryVector: [...],
  filter: {
    $and: [
      { category: "electronics" },
      { price: { $gte: 100, $lte: 500 } },
    ],
  },
});

// Nested field access
const results = await store.query({
  indexName: "docs",
  queryVector: [...],
  filter: { "user.profile.tier": "premium" },
});

거리 측정법

측정 방식	설명	점수 해석	가장 적합한 대상
cosine	코사인 유사도	0~1(1 = 가장 유사함)	텍스트 임베딩, 정규화된 벡터
euclidean	L2 거리	0~∞(0 = 가장 유사함)	이미지 임베딩, 공간 데이터
dotproduct	내적	높을수록 더 유사함	벡터 크기가 중요한 경우

오류 처리

저장소는 다양한 실패 사례에 대해 특정 오류를 발생시킵니다.

try {
  await store.query({
    indexName: 'my-collection',
    queryVector: queryVector,
  })
} catch (error) {
  if (error.message.includes('not found')) {
    console.error('The specified index does not exist')
  } else if (error.message.includes('Invalid identifier')) {
    console.error('Index name contains invalid characters')
  } else {
    console.error('Vector store error:', error.message)
  }
}

일반적인 오류 사례는 다음과 같습니다.

• 잘못된 인덱스 이름 형식
• 인덱스/테이블을 찾을 수 없음
• 쿼리 벡터와 인덱스 간 차원 불일치
• 삭제/업데이트 작업에 빈 필터 또는 ID 배열이 있음
• 상호 배타성 위반(id와 filter를 모두 제공)

사용 사례

내장된 의미 검색

완전히 프로세스 내에서 실행되는 의미론적 검색을 통해 오프라인 지원 AI 애플리케이션을 구축하세요.

const store = new DuckDBVector({
  id: 'offline-search',
  path: './search.duckdb',
})

로컬 RAG 파이프라인

클라우드 벡터 데이터베이스로 데이터를 보내지 않고 민감한 문서를 로컬로 처리합니다.

const store = new DuckDBVector({
  id: 'private-rag',
  path: './confidential.duckdb',
  dimensions: 1536,
})

개발 및 테스트

인프라 없이 벡터 검색 기능을 신속하게 프로토타입화합니다.

const store = new DuckDBVector({
  id: 'dev-store',
  path: ':memory:', // Fast in-memory for tests
})

관련된

• 메타데이터 필터
• DuckDB 문서