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

# Amazon S3 벡터 스토어

그만큼`S3Vectors`클래스는 다음을 사용하여 벡터 검색을 제공합니다.[Amazon S3 벡터(미리 보기)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors.html). 벡터를 저장합니다.**벡터 양동이**유사성 검색을 수행합니다.**벡터 인덱스**, JSON 기반 메타데이터 필터 포함.

> **경고:** Amazon S3 벡터는 미리 보기 서비스입니다. 미리 보기 기능은 예고 없이 변경되거나 제거될 수 있으며 AWS SLA가 적용되지 않습니다. 동작, 한도, 지역별 가용성은 언제든지 변경될 수 있습니다. 이 라이브러리는 AWS와 보조를 맞추기 위해 주요 변경 사항을 도입할 수 있습니다.

## 설치

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

## 사용예

```typescript
import { S3Vectors } from '@mastra/s3vectors'

const store = new S3Vectors({
  vectorBucketName: process.env.S3_VECTORS_BUCKET_NAME!, // e.g. "my-vector-bucket"
  clientConfig: {
    region: process.env.AWS_REGION!, // credentials use the default AWS provider chain
  },
  // Optional: mark large/long-text fields as non-filterable at index creation time
  nonFilterableMetadataKeys: ['content'],
})

// Create an index (names are normalized: "_" → "-" and lowercased)
await store.createIndex({
  indexName: 'my_index',
  dimension: 1536,
  metric: 'cosine', // "euclidean" also supported; "dotproduct" is NOT supported
})

// Upsert vectors (ids auto-generated if omitted). Date values in metadata are serialized to epoch ms.
const ids = await store.upsert({
  indexName: 'my_index',
  vectors: [
    [0.1, 0.2 /* … */],
    [0.3, 0.4 /* … */],
  ],
  metadata: [
    {
      text: 'doc1',
      genre: 'documentary',
      year: 2023,
      createdAt: new Date('2024-01-01'),
    },
    { text: 'doc2', genre: 'comedy', year: 2021 },
  ],
})

// Query with metadata filters (implicit AND is canonicalized)
const results = await store.query({
  indexName: 'my-index',
  queryVector: [0.1, 0.2 /* … */],
  topK: 10, // Service-side limits may apply (commonly 30)
  filter: { genre: { $in: ['documentary', 'comedy'] }, year: { $gte: 2020 } },
  includeVector: false, // set true to include raw vectors (may trigger a secondary fetch)
})

// Clean up resources (closes the underlying HTTP handler)
await store.disconnect()
```

## 생성자 옵션

**vectorBucketName** (`string`): 대상 S3 Vectors 벡터 버킷 이름입니다.

**clientConfig** (`S3VectorsClientConfig`): AWS SDK v3 클라이언트 옵션(예: region, credentials)입니다.

**nonFilterableMetadataKeys** (`string[]`): 필터링할 수 없도록 설정할 메타데이터 키입니다(인덱스 생성 시 적용). content 같은 대용량 텍스트 필드에 사용하세요.

## 행동 양식

### `createIndex()`

구성된 벡터 버킷에 새 벡터 인덱스를 생성합니다. 인덱스가 이미 존재하는 경우 호출은 스키마의 유효성을 검사하고 작동하지 않습니다(기존 지표 및 차원은 유지됨).

**indexName** (`string`): 논리적 인덱스 이름입니다. 내부적으로 밑줄을 하이픈으로 바꾸고 이름을 소문자로 변환하여 정규화합니다.

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

**metric** (`'cosine' | 'euclidean'`): 유사도 검색에 사용할 거리 측정 방식입니다. S3 Vectors는 dotproduct를 지원하지 않습니다. (Default: `cosine`)

### `upsert()`

벡터를 추가하거나 대체합니다(전체 레코드 삽입). `ids`를 제공하지 않으면 UUID가 생성됩니다.

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

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

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

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

### `query()`

선택적 메타데이터 필터링을 사용하여 최근접 이웃을 검색합니다.

**indexName** (`string`): 쿼리할 인덱스의 이름

**queryVector** (`number[]`): 유사한 벡터를 찾기 위한 쿼리 벡터

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

**filter** (`S3VectorsFilter`): $and, $or, $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists를 지원하는 JSON 기반 메타데이터 필터입니다.

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

> **노트:** 결과에는 기반 거리 순위를 유지하면서 값이 클수록 더 좋도록 `score = 1/(1 + distance)`가 포함됩니다.

### `describeIndex()`

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

**indexName** (`string`): 설명을 조회할 인덱스 이름입니다.

보고:

```typescript
interface IndexStats {
  dimension: number
  count: number // computed via ListVectors pagination (O(n))
  metric: 'cosine' | 'euclidean'
}
```

### `deleteIndex()`

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

**indexName** (`string`): 삭제할 인덱스입니다.

### `listIndexes()`

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

보고:`Promise<string[]>`

### `updateVector()`

인덱스 내의 특정 ID에 대한 벡터 또는 메타데이터를 업데이트합니다.

**indexName** (`string`): 벡터가 포함된 인덱스입니다.

**id** (`string`): 업데이트할 ID입니다.

**update** (`object`): 벡터 및/또는 메타데이터가 포함된 업데이트 데이터

**update.vector** (`number[]`): 업데이트할 새 벡터 데이터

**update.metadata** (`Record<string, any>`): 업데이트할 새 메타데이터

### `deleteVector()`

ID별로 특정 벡터를 삭제합니다.

**indexName** (`string`): 벡터가 포함된 인덱스입니다.

**id** (`string`): 삭제할 ID입니다.

### `disconnect()`

기본 AWS SDK HTTP 핸들러를 닫아 소켓을 확보합니다.

## 응답 유형

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

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

## 필터 구문

S3 벡터는 연산자 및 값 유형의 엄격한 하위 집합을 지원합니다. Mastra 필터 번역기:

- **암시적 AND를 정규화합니다.**: `{a:1,b:2}` → `{ $and: [{a:1},{b:2}] }`.
- **날짜 값을 정규화합니다.** 숫자 비교와 배열 요소에 사용할 수 있도록 epoch ms로 변환합니다.
- **동등 비교 위치에서는 날짜를 허용하지 않습니다.** (`field: value` 또는 `$eq/$ne`). 동등 비교 값은 **string | number | boolean**이어야 합니다.
- 동등 비교에서는 null/undefined를 **거부**합니다. **배열 동등 비교**는 지원하지 않습니다(`$in`/`$nin` 사용).
- 최상위 논리 연산자로는 \*\*`$and` / `$or`\*\*만 허용됩니다.
- 논리 연산자에는 직접 연산자가 아닌 **필드 조건**이 포함되어야 합니다. **지원되는 연산자:**
- **논리:** `$and`, `$or` (비어 있지 않은 배열)
- **기본:** `$eq`, `$ne` (string | number | boolean)
- **숫자:** `$gt`, `$gte`, `$lt`, `$lte` (number 또는 `Date` → epoch ms)
- **집합:** `$in`, `$nin` (string | number | boolean으로 구성된 비어 있지 않은 배열, `Date` → epoch ms)
- **존재 여부:** `$exists` (boolean) **지원되지 않음/허용되지 않음(거부됨):** `$not`, `$nor`, `$regex`, `$all`, `$elemMatch`, `$size`, `$text`, etc.

**예:**

```typescript
// Implicit AND
{ genre: { $in: ["documentary", "comedy"] }, year: { $gte: 2020 } }

// Explicit logicals and ranges
{
  $and: [
    { price: { $gte: 100, $lte: 1000 } },
    { $or: [{ stock: { $gt: 0 } }, { preorder: true }] }
  ]
}

// Dates in range (converted to epoch ms)
{ timestamp: { $gt: new Date("2024-01-01T00:00:00Z") } }
```

> **노트:** 인덱스 생성 시 `nonFilterableMetadataKeys`를 설정하면 해당 키는 저장되지만 필터에서는 **사용할 수 없습니다**.

## 오류 처리

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

```typescript
try {
  await store.query({
    indexName: 'index-name',
    queryVector: queryVector,
  })
} catch (error) {
  if (error instanceof VectorStoreError) {
    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
    console.log(error.details) // Additional error context
  }
}
```

## 환경변수

앱을 연결할 때 일반적인 환경 변수:

- `S3_VECTORS_BUCKET_NAME`: S3 **벡터 버킷** 이름(`vectorBucketName`을 채우는 데 사용).
- `AWS_REGION`: S3 벡터 버킷의 AWS 리전입니다.
- **AWS 자격 증명**: 표준 AWS SDK Provider 체인(`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_PROFILE` 등)을 통해 제공합니다.

## 모범 사례

- 임베딩 Model과 일치하도록 측정 방식(`cosine` 또는 `euclidean`)을 설정하세요. `dotproduct`는 지원되지 않습니다.
- **필터링 가능한** 메타데이터는 작고 구조화된 형태(string/number/boolean)로 유지하세요. 대용량 텍스트(예: `content`)는 **필터링 불가능**으로 저장하세요.
- 중첩된 메타데이터에는 **점으로 구분된 경로**를 사용하고, 복잡한 로직에는 명시적인 `$and`/`$or`를 사용하세요.
- 자주 실행되는 경로에서 `describeIndex()`를 호출하지 마세요. `count`는 페이지가 매겨진 `ListVectors`를 사용하여 계산됩니다(**O(n)**).
- 원시 벡터가 필요할 때만 `includeVector: true`를 사용하세요.

## 관련된

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