> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# DuckDB 벡터 저장소

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

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

## 설치

**npm**:

```bash
npm install @mastra/duckdb@latest
```

**pnpm**:

```bash
pnpm add @mastra/duckdb@latest
```

**Yarn**:

```bash
yarn add @mastra/duckdb@latest
```

**Bun**:

```bash
bun add @mastra/duckdb@latest
```

## 용법

```typescript
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:'를 사용하고, 영구 저장에는 './vectors.duckdb'와 같은 파일 경로를 사용합니다. (Default: `':memory:'`)

**dimensions** (`number`): 벡터 임베딩의 기본 차원 (Default: `1536`)

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 유사도 검색의 기본 거리 측정 방식 (Default: `cosine`)

## 행동 양식

### `createIndex()`

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

**indexName** (`string`): 생성할 인덱스의 이름

**dimension** (`number`): 벡터 차원 크기(임베딩 Model과 일치해야 함)

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 유사도 검색에 사용할 거리 측정 방식 (Default: `cosine`)

### `upsert()`

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

**indexName** (`string`): 데이터를 삽입할 인덱스의 이름

**vectors** (`number[][]`): 임베딩 벡터 배열

**metadata** (`Record<string, any>[]`): 각 벡터의 메타데이터

**ids** (`string[]`): 선택적 벡터 ID(제공하지 않으면 UUID 자동 생성)

### `query()`

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

**indexName** (`string`): 검색할 인덱스의 이름

**queryVector** (`number[]`): 유사한 벡터를 찾는 데 사용할 쿼리 벡터

**topK** (`number`): 반환할 결과 수 (Default: `10`)

**filter** (`Filter`): MongoDB와 유사한 쿼리 구문을 사용하는 메타데이터 필터

**includeVector** (`boolean`): 결과에 벡터 데이터를 포함할지 여부 (Default: `false`)

### `describeIndex()`

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

**indexName** (`string`): 설명할 인덱스의 이름

보고:

```typescript
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()`

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

```typescript
await store.close()
```

## 응답 유형

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

```typescript
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`                                |

### 필터 예

```typescript
// 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` | 내적      | 높을수록 더 유사함       | 벡터 크기가 중요한 경우    |

## 오류 처리

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

```typescript
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 애플리케이션을 구축하세요.

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

### 로컬 RAG 파이프라인

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

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

### 개발 및 테스트

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

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

## 관련된

- [메타데이터 필터](https://mastra.zisheng.pro/ko/reference/rag/metadata-filters)
- [DuckDB 문서](https://duckdb.org/docs/)