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

# Couchbase 벡터 스토어

그만큼`CouchbaseVector`클래스는 다음을 사용하여 벡터 검색을 제공합니다.[Couchbase 벡터 검색](https://docs.couchbase.com/server/current/vector-search/vector-search.html). Couchbase 컬렉션 내에서 효율적인 유사성 검색 및 메타데이터 필터링이 가능합니다.

## 요구사항

- **카우치베이스 서버 7.6.4+**또는 호환되는 Capella 클러스터
- **검색 서비스 활성화됨**Couchbase 배포에서

## 설치

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

## 사용예

```typescript
import { CouchbaseVector } from '@mastra/couchbase'

const store = new CouchbaseVector({
  id: 'couchbase-vector',
  connectionString: process.env.COUCHBASE_CONNECTION_STRING,
  username: process.env.COUCHBASE_USERNAME,
  password: process.env.COUCHBASE_PASSWORD,
  bucketName: process.env.COUCHBASE_BUCKET,
  scopeName: process.env.COUCHBASE_SCOPE,
  collectionName: process.env.COUCHBASE_COLLECTION,
})
```

## 생성자 옵션

**id** (`string`): 이 벡터 저장소 인스턴스의 고유 식별자

**connectionString** (`string`): Couchbase 연결 문자열

**username** (`string`): Couchbase 사용자 이름

**password** (`string`): Couchbase 비밀번호

**bucketName** (`string`): 사용할 Couchbase 버킷의 이름

**scopeName** (`string`): 사용할 Couchbase 범위의 이름

**collectionName** (`string`): 사용할 Couchbase 컬렉션의 이름

**options** (`CouchbaseClientOptions`): 선택적 Couchbase 클라이언트 옵션

## 행동 양식

### `createIndex()`

Couchbase에서 새로운 벡터 인덱스를 생성합니다.

> **노트:** 인덱스 생성은 비동기 방식입니다. `createIndex`를 호출한 후 쿼리하기 전에 시간을 두세요(일반적으로 소규모 데이터 세트는 1\~5초, 대규모 데이터 세트는 더 오래 걸림). 프로덕션 환경에서는 고정 지연 시간을 사용하는 대신 폴링을 구현하여 인덱스 상태를 확인하세요.

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

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

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

### `upsert()`

컬렉션에 벡터와 해당 메타데이터를 추가하거나 업데이트합니다.

> **노트:** 인덱스를 생성하기 전이나 후에 데이터를 업서트할 수 있습니다. `upsert` 메서드는 인덱스가 없어도 사용할 수 있습니다. Couchbase에서는 동일한 컬렉션에 여러 Search 인덱스를 만들 수 있습니다.

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

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

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

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

### `query()`

유사한 벡터를 검색합니다.

> **경고:** 현재 `filter` 및 `includeVector` 매개변수는 지원되지 않습니다. 결과를 가져온 후 클라이언트 측에서 필터링하거나 Couchbase SDK의 Search 기능을 직접 사용해야 합니다. 벡터 임베딩을 가져오려면 Couchbase SDK를 사용하여 ID로 전체 문서를 가져오세요.

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

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

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

**filter** (`Record<string, any>`): 메타데이터 필터

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

**minScore** (`number`): 최소 유사도 점수 임계값 (Default: `0`)

### `describeIndex()`

인덱스에 대한 정보를 반환합니다.

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

보고:

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

### `deleteIndex()`

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

**indexName** (`string`): 삭제할 인덱스의 이름

### `listIndexes()`

Couchbase 버킷의 모든 벡터 인덱스를 나열합니다.

보고:`Promise<string[]>`

### `updateVector()`

새로운 벡터 데이터 및/또는 메타데이터를 사용하여 ID별로 특정 벡터 항목을 업데이트합니다. Couchbase에는 필터 기반 업데이트가 아직 구현되지 않았습니다.

**indexName** (`string`): 벡터가 포함된 인덱스의 이름

**id** (`string`): 업데이트할 벡터 항목의 ID

**update** (`{ vector?: number[]; metadata?: Record<string, any>; }`): 업데이트할 벡터 및/또는 메타데이터가 포함된 객체

### `deleteVector()`

인덱스에서 ID로 단일 벡터를 삭제합니다.

**indexName** (`string`): 벡터가 포함된 인덱스의 이름

**id** (`string`): 삭제할 벡터의 ID

### `deleteVectors()`

ID별로 여러 벡터를 삭제합니다. Couchbase에는 필터 기반 삭제가 아직 구현되지 않았습니다.

**indexName** (`string`): 삭제할 벡터가 포함된 인덱스의 이름

**ids** (`string[]`): 삭제할 벡터 ID 배열

### `disconnect()`

Couchbase 클라이언트 연결을 닫습니다. 매장 이용이 끝나면 전화해야 합니다.

## 응답 유형

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

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

## 오류 처리

상점에서는 포착할 수 있는 입력된 오류를 발생시킵니다.

```typescript
try {
  await store.query({
    indexName: 'my_index',
    queryVector: queryVector,
  })
} catch (error) {
  // Handle specific error cases
  if (error.message.includes('Invalid index name')) {
    console.error(
      'Index name must start with a letter or underscore and contain only valid characters.',
    )
  } else if (error.message.includes('Index not found')) {
    console.error('The specified index does not exist')
  } else {
    console.error('Vector store error:', error.message)
  }
}
```

## 메모

- **인덱스 삭제 시 주의 사항:**&#xAC80;색 인덱스를 삭제해도 연결된 Couchbase 컬렉션의 벡터/문서는 삭제되지 않습니다. 명시적으로 제거하지 않는 한 데이터는 그대로 유지됩니다.
- **필수 권한:**&#x43;ouchbase 사용자는 대상 컬렉션에 문서를 읽고 쓸 수 있어야 하며(`kv` role), Search 인덱스를 관리할 수 있어야 합니다(관련 버킷/범위의 `search_admin` role).
- **인덱스 정의 세부 정보 및 문서 구조:**&#xADF8; `createIndex` 메서드는 지정된 `scopeName.collectionName` 내의 문서를 대상으로 `embedding` 필드(`vector` 유형)와 `content` 필드(`text` 유형)를 인덱싱하는 Search 인덱스 정의를 생성합니다. 각 문서는 벡터를 `embedding` 필드에, 메타데이터를 `metadata` 필드에 저장합니다. `metadata`에 `text` 속성이 있으면 해당 값도 최상위 `content` 필드에 복사되며, 이 필드는 텍스트 검색용으로 인덱싱됩니다.
- **복제 및 내구성:**&#xB370;이터 내구성을 확보하려면 Couchbase에 내장된 복제 및 지속성 기능을 사용하세요. 효율적인 검색을 위해 인덱스 통계를 정기적으로 모니터링하세요.

## 제한사항

- 인덱스 생성 지연은 생성 후 즉각적인 쿼리에 영향을 미칠 수 있습니다.
- 수집 시 벡터 차원을 강제로 적용하지 않습니다(차원 불일치로 인해 쿼리 시 오류가 발생함).
- 벡터 삽입과 인덱스 업데이트는 최종적으로 일관됩니다. 쓰기 직후에는 강력한 일관성이 보장되지 않습니다.

## 관련된

- [메타데이터 필터](https://mastra.zisheng.pro/ko/reference/rag/metadata-filters)