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

# Magasin de vecteurs Amazon S3

La classe `S3Vectors` propose une recherche vectorielle à l’aide d’[Amazon S3 Vectors (Preview)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors.html). Elle stocke les vecteurs dans des **buckets de vecteurs** et effectue des recherches de similarité dans des **index vectoriels**, avec des filtres de métadonnées fondés sur JSON.

> **Attention:** Amazon S3 Vectors est un service Preview. Les fonctionnalités Preview peuvent être modifiées ou supprimées sans préavis et ne sont pas couvertes par les SLA AWS. Son comportement, ses limites et sa disponibilité régionale peuvent changer à tout moment. Cette bibliothèque peut introduire des changements cassants afin de rester alignée sur AWS.

## Installation

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

## Exemple d’utilisation

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

## Options du constructeur

**vectorBucketName** (`string`): Nom du bucket de vecteurs S3 Vectors cible.

**clientConfig** (`S3VectorsClientConfig`): Options du client AWS SDK v3 (par exemple, region, credentials).

**nonFilterableMetadataKeys** (`string[]`): Clés de métadonnées qui ne doivent PAS être filtrables (appliquées à l’index lors de sa création). Utilisez-les pour les champs de texte volumineux comme content.

## Méthodes

### `createIndex()`

Crée un nouvel index vectoriel dans le bucket de vecteurs configuré. Si l’index existe déjà, l’appel valide le schéma et n’a aucun effet (la métrique et la dimension existantes sont conservées).

**indexName** (`string`): Nom logique de l’index. Normalisé en interne : les traits de soulignement sont remplacés par des traits d’union et le nom est converti en minuscules.

**dimension** (`number`): Dimension du vecteur (doit correspondre à votre modèle d’embedding)

**metric** (`'cosine' | 'euclidean'`): Métrique de distance pour la recherche de similarité. dotproduct n’est pas pris en charge par S3 Vectors. (Default: `cosine`)

### `upsert()`

Ajoute ou remplace des vecteurs (écriture d’enregistrements complets). Si `ids` n’est pas fourni, des UUID sont générés.

**indexName** (`string`): Nom de l’index dans lequel effectuer l’upsert

**vectors** (`number[][]`): Tableau de vecteurs d’embedding

**metadata** (`Record<string, any>[]`): Métadonnées de chaque vecteur

**ids** (`string[]`): ID de vecteur facultatifs (générés automatiquement s’ils ne sont pas fournis)

### `query()`

Recherche les voisins les plus proches avec un filtrage facultatif des métadonnées.

**indexName** (`string`): Nom de l’index à interroger

**queryVector** (`number[]`): Vecteur de requête pour trouver des vecteurs similaires

**topK** (`number`): Nombre de résultats à renvoyer (Default: `10`)

**filter** (`S3VectorsFilter`): Filtre de métadonnées fondé sur JSON prenant en charge $and, $or, $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists.

**includeVector** (`boolean`): Indique s’il faut inclure les vecteurs dans les résultats (Default: `false`)

> **Remarque:** Les résultats incluent `score = 1/(1 + distance)` afin qu’un score plus élevé soit préférable tout en préservant le classement de distance sous-jacent.

### `describeIndex()`

Renvoie des informations sur l’index.

**indexName** (`string`): Nom de l’index à décrire.

Renvoie :

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

### `deleteIndex()`

Supprime un index et ses données.

**indexName** (`string`): Index à supprimer.

### `listIndexes()`

Répertorie tous les index du bucket de vecteurs configuré.

Renvoie : `Promise<string[]>`

### `updateVector()`

Met à jour un vecteur ou des métadonnées pour un ID précis dans un index.

**indexName** (`string`): Index contenant le vecteur.

**id** (`string`): ID à mettre à jour.

**update** (`object`): Données de mise à jour contenant le vecteur et/ou les métadonnées

**update.vector** (`number[]`): Nouvelles données vectorielles à mettre à jour

**update.metadata** (`Record<string, any>`): Nouvelles métadonnées à mettre à jour

### `deleteVector()`

Supprime un vecteur spécifique par ID.

**indexName** (`string`): Index contenant le vecteur.

**id** (`string`): ID à supprimer.

### `disconnect()`

Ferme le gestionnaire HTTP AWS SDK sous-jacent afin de libérer les sockets.

## Types de réponse

Les résultats de requête sont renvoyés dans ce format :

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

## Syntaxe des filtres

S3 Vectors prend en charge un sous-ensemble strict d’opérateurs et de types de valeurs. Le traducteur de filtres Mastra :

- **Canonicalise les ET implicites** : `{a:1,b:2}` → `{ $and: [{a:1},{b:2}] }`.
- **Normalise les valeurs Date** en ms depuis l’époque pour les comparaisons numériques et les éléments de tableau.
- **Interdit Date** dans les positions d’égalité (`field: value` ou `$eq/$ne`). Les valeurs d’égalité doivent être de type **string | number | boolean**.
- **Rejette** null/undefined pour l’égalité. L’**égalité de tableaux** n’est pas prise en charge (utilisez `$in`/`$nin`).
- Seuls **`$and` / `$or`** sont autorisés comme opérateurs logiques de premier niveau.
- Les opérateurs logiques doivent contenir des **conditions de champ** (et non des opérateurs directs).

**Opérateurs pris en charge :**

- **Logiques :** `$and`, `$or` (tableaux non vides)
- **De base :** `$eq`, `$ne` (string | number | boolean)
- **Numériques :** `$gt`, `$gte`, `$lt`, `$lte` (number ou `Date` → ms depuis l’époque)
- **Tableau :** `$in`, `$nin` (tableaux non vides de string | number | boolean ; `Date` → ms depuis l’époque)
- **Élément :** `$exists` (boolean)

**Non pris en charge / interdits (rejetés) :** `$not`, `$nor`, `$regex`, `$all`, `$elemMatch`, `$size`, `$text`, etc.

**Exemples :**

```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") } }
```

> **Remarque:** Si vous définissez `nonFilterableMetadataKeys` lors de la création de l’index, ces clés sont stockées mais **ne peuvent pas** être utilisées dans les filtres.

## Gestion des erreurs

Le magasin lève des erreurs typées que vous pouvez intercepter :

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

## Variables d’environnement

Variables d’environnement typiques lors de la configuration de votre application :

- `S3_VECTORS_BUCKET_NAME` : nom de votre **bucket de vecteurs** S3 (utilisé pour renseigner `vectorBucketName`).
- `AWS_REGION` : région AWS du bucket S3 Vectors.
- **Informations d’identification AWS** : via la chaîne de fournisseurs AWS SDK standard (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_PROFILE`, etc.).

## Bonnes pratiques

- Choisissez la métrique (`cosine` ou `euclidean`) qui correspond à votre modèle d’embedding. `dotproduct` n’est pas pris en charge.
- Gardez les métadonnées **filtrables** petites et structurées (string/number/boolean). Stockez les textes volumineux (par exemple, `content`) comme **non filtrables**.
- Utilisez des **chemins avec des points** pour les métadonnées imbriquées et des `$and`/`$or` explicites pour la logique complexe.
- Évitez d’appeler `describeIndex()` sur les chemins critiques. `count` est calculé avec `ListVectors` paginé (**O(n)**).
- Utilisez `includeVector: true` seulement lorsque vous avez besoin des vecteurs bruts.

## Pages associées

- [Filtres de métadonnées](https://mastra.zisheng.pro/fr/reference/rag/metadata-filters)