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

# 데이터베이스구성

그만큼`DatabaseConfig`type을 사용하면 벡터 쿼리 Tool을 사용할 때 데이터베이스별 구성을 지정할 수 있습니다. 이러한 구성을 통해 다양한 벡터 스토어에서 제공하는 기능과 최적화를 사용할 수 있습니다.

## 유형 정의

```typescript
export type DatabaseConfig = {
  pinecone?: PineconeConfig
  pgvector?: PgVectorConfig
  chroma?: ChromaConfig
  turbopuffer?: TurbopufferConfig
  [key: string]: any // Extensible for future databases
}
```

## 데이터베이스별 유형

### `PineconeConfig`

Pinecone 벡터 저장소와 관련된 구성 옵션입니다.

**namespace** (`string`): 동일한 인덱스 내에서 벡터를 구성하고 격리하는 Pinecone 네임스페이스입니다. 다중 테넌시 또는 환경 분리에 유용합니다.

**sparseVector** (`{ indices: number[]; values: number[]; }`): 밀집 임베딩과 희소 임베딩을 결합하는 하이브리드 검색용 희소 벡터입니다. 키워드 기반 쿼리의 검색 품질을 높입니다. indices 배열과 values 배열의 길이는 같아야 합니다.

**sparseVector.indices** (`number[]`): 희소 벡터 구성 요소의 인덱스 배열입니다.

**sparseVector.values** (`number[]`): 인덱스에 대응하는 값의 배열입니다.

**사용 사례:**

- 다중 테넌트 애플리케이션(테넌트당 별도의 네임스페이스)
- 환경 격리(dev/staging/prod 네임스페이스)
- 의미론적 일치와 키워드 일치를 결합한 하이브리드 검색

### `PgVectorConfig`

pgVector 확장자를 사용하는 PostgreSQL 관련 구성 옵션입니다.

**minScore** (`number`): 결과의 최소 유사도 점수 임곗값입니다. 유사도 점수가 이 값보다 높은 벡터만 반환됩니다.

**ef** (`number`): 검색 중 동적 후보 목록의 크기를 제어하는 HNSW 검색 매개변수입니다. 값이 클수록 속도를 희생하여 정확도가 높아집니다. 일반적으로 topK와 200 사이로 설정합니다.

**probes** (`number`): 검색 중 방문할 인덱스 셀 수를 지정하는 IVFFlat 프로브 매개변수입니다. 값이 클수록 속도를 희생하여 재현율이 높아집니다.

**성능 지침:**

- **에프**: topK 값의 2\~4배로 시작하고 정확도를 높이려면 높이세요.
- **프로브**: 1-10으로 시작하고 더 나은 기억을 위해 증가시킵니다.
- **최소점수**: 품질 요구 사항에 따라 0.5-0.9 사이의 값을 사용하십시오.

**사용 사례:**

- 고부하 시나리오를 위한 성능 최적화
- 관련 없는 결과를 제거하는 품질 필터링
- 검색 정확도와 속도 균형의 미세 조정

### `ChromaConfig`

Chroma 벡터 저장소와 관련된 구성 옵션입니다.

**where** (`Record<string, any>`): MongoDB 방식 쿼리 구문을 사용하는 메타데이터 필터링 조건입니다. 메타데이터 필드를 기준으로 결과를 필터링합니다.

**whereDocument** (`Record<string, any>`): 문서 콘텐츠 필터링 조건입니다. 실제 문서의 텍스트 콘텐츠를 기준으로 필터링할 수 있습니다.

**필터 구문 예:**

```typescript
// Simple equality
where: { "category": "technical" }

// Operators
where: { "price": { "$gt": 100 } }

// Multiple conditions
where: {
  "category": "electronics",
  "inStock": true
}

// Document content filtering
whereDocument: { "$contains": "API documentation" }
```

**사용 사례:**

- 고급 메타데이터 필터링
- 컨텐츠 기반 문서 필터링
- 복잡한 쿼리 조합

### `TurbopufferConfig`

Turbopuffer 벡터 저장소와 관련된 구성 옵션입니다.

**consistency** (`'strong' | 'eventual'`): 쿼리의 일관성 수준입니다. "strong"(기본값)은 지연 시간이 늘어나는 대신 쿼리가 시작되기 전에 기록된 모든 데이터를 쿼리에서 볼 수 있도록 보장합니다. "eventual"은 지연 시간이 짧지만 최근에 기록된 데이터가 아직 표시되지 않을 수 있습니다.

**사용 사례:**

- 약간 오래된 데이터가 허용되는 지연 시간에 민감한 쿼리(`eventual`)
- 최신 데이터를 확인해야 하는 작성한 내용 읽기 Workflow(`strong`)

## 사용 예

**Basic Usage**:

### 기본 데이터베이스 구성

```typescript
import { createVectorQueryTool } from '@mastra/rag'

const vectorTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'documents',
  model: embedModel,
  databaseConfig: {
    pinecone: {
      namespace: 'production',
    },
  },
})
```

**Runtime Override**:

### 런타임 구성 재정의

```typescript
import { RequestContext } from '@mastra/core/request-context'

// Initial configuration
const vectorTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'documents',
  model: embedModel,
  databaseConfig: {
    pinecone: {
      namespace: 'development',
    },
  },
})

// Override at runtime
const requestContext = new RequestContext()
requestContext.set('databaseConfig', {
  pinecone: {
    namespace: 'production',
  },
})

await vectorTool.execute({ queryText: 'search query' }, { mastra, requestContext })
```

**Multi-Database**:

### 다중 데이터베이스 구성

```typescript
const vectorTool = createVectorQueryTool({
  vectorStoreName: 'dynamic', // Will be determined at runtime
  indexName: 'documents',
  model: embedModel,
  databaseConfig: {
    pinecone: {
      namespace: 'default',
    },
    pgvector: {
      minScore: 0.8,
      ef: 150,
    },
    chroma: {
      where: { type: 'documentation' },
    },
  },
})
```

> **노트:** **다중 데이터베이스 지원**: 여러 데이터베이스를 구성하는 경우 실제 사용되는 벡터 저장소와 일치하는 구성만 적용됩니다.

**Performance Tuning**:

### 성능 튜닝

```typescript
// High accuracy configuration
const highAccuracyTool = createVectorQueryTool({
  vectorStoreName: 'postgres',
  indexName: 'embeddings',
  model: embedModel,
  databaseConfig: {
    pgvector: {
      ef: 400, // High accuracy
      probes: 20, // High recall
      minScore: 0.85, // High quality threshold
    },
  },
})

// High speed configuration
const highSpeedTool = createVectorQueryTool({
  vectorStoreName: 'postgres',
  indexName: 'embeddings',
  model: embedModel,
  databaseConfig: {
    pgvector: {
      ef: 50, // Lower accuracy, faster
      probes: 3, // Lower recall, faster
      minScore: 0.6, // Lower quality threshold
    },
  },
})
```

## 확장성

`DatabaseConfig` 타입은 확장할 수 있도록 설계되었습니다. 새 벡터 데이터베이스 지원을 추가하려면 다음을 수행하세요.

```typescript
// 1. Define the configuration interface
export interface NewDatabaseConfig {
  customParam1?: string
  customParam2?: number
}

// 2. Extend DatabaseConfig type
export type DatabaseConfig = {
  pinecone?: PineconeConfig
  pgvector?: PgVectorConfig
  chroma?: ChromaConfig
  newdatabase?: NewDatabaseConfig
  [key: string]: any
}

// 3. Use in vector query tool
const vectorTool = createVectorQueryTool({
  vectorStoreName: 'newdatabase',
  indexName: 'documents',
  model: embedModel,
  databaseConfig: {
    newdatabase: {
      customParam1: 'value',
      customParam2: 42,
    },
  },
})
```

## 모범 사례

1. **환경 구성**: 다양한 환경에 대해 서로 다른 네임스페이스 또는 구성을 사용합니다.
2. **성능 튜닝**: 기본값으로 시작하고 특정 요구 사항에 따라 조정합니다.
3. **품질 필터링**: minScore를 사용하여 품질이 낮은 결과를 필터링합니다.
4. **런타임 유연성**: 런타임 정의 시나리오에 대해 런타임 시 구성 재정의
5. **선적 서류 비치**: 팀 구성원을 위한 특정 구성 선택 사항을 문서화합니다.

## 마이그레이션 가이드

기존 벡터 쿼리 Tool은 변경 없이 계속 작동합니다. 데이터베이스 구성을 추가하려면 다음을 수행하십시오.

```diff
const vectorTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'documents',
  model: embedModel,
+ databaseConfig: {
+   pinecone: {
+     namespace: 'production'
+   }
+ }
});
```

## 관련된

- [createVectorQueryTool()](https://mastra.zisheng.pro/ko/reference/tools/vector-query-tool)
- [하이브리드 벡터 검색](https://mastra.zisheng.pro/ko/guides/rag/retrieval)
- [메타데이터 필터](https://mastra.zisheng.pro/ko/reference/rag/metadata-filters)