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

# Filtres de métadonnées

Mastra fournit une syntaxe unifiée de filtrage des métadonnées pour toutes les bases vectorielles, fondée sur la syntaxe de requête MongoDB/Sift. Chaque base vectorielle traduit ces filtres dans son format de requête natif. Par exemple, PgVector utilise les prédicats JSONB de PostgreSQL, tandis qu’OracleDB stocke les métadonnées au format Oracle JSON et compile les filtres en prédicats `JSON_VALUE`, `JSON_EXISTS`, `REGEXP_LIKE` et `LIKE` avec des valeurs liées.

## Exemple de base

```typescript
import { PgVector } from '@mastra/pg'

const store = new PgVector({
  id: 'pg-vector',
  connectionString,
})

const results = await store.query({
  indexName: 'my_index',
  queryVector: queryVector,
  topK: 10,
  filter: {
    category: 'electronics', // Simple equality
    price: { $gt: 100 }, // Numeric comparison
    tags: { $in: ['sale', 'new'] }, // Array membership
  },
})
```

## Opérateurs pris en charge

### Comparaisons de base

`$eq`Correspond aux valeurs égales à la valeur indiquée{ age: { $eq: 25 } }Supported by: Tous sauf Couchbase`$ne`Correspond aux valeurs différentes{ status: { $ne: 'inactive' } }Supported by: Tous sauf Couchbase`$gt`Supérieur à{ price: { $gt: 100 } }Supported by: Tous sauf Couchbase`$gte`Supérieur ou égal à{ rating: { $gte: 4.5 } }Supported by: Tous sauf Couchbase`$lt`Inférieur à{ stock: { $lt: 20 } }Supported by: Tous sauf Couchbase`$lte`Inférieur ou égal à{ priority: { $lte: 3 } }Supported by: Tous sauf Couchbase

### Opérateurs de tableau

`$in`Correspond à n’importe quelle valeur du tableau{ category: { $in: \["A", "B"] } }Supported by: Tous sauf Couchbase`$nin`Ne correspond à aucune des valeurs{ status: { $nin: \["deleted", "archived"] } }Supported by: Tous sauf Couchbase`$all`Correspond aux tableaux contenant tous les éléments{ tags: { $all: \["urgent", "high"] } }Supported by: Astra, Pinecone, Upstash, MongoDB, OracleDB`$elemMatch`Correspond aux éléments de tableau répondant aux critères{ scores: { $elemMatch: { $gt: 80 } } }Supported by: libSQL, PgVector, MongoDB, OracleDB

### Opérateurs logiques

`$and`ET logique{ $and: \[{ price: { $gt: 100 } }, { stock: { $gt: 0 } }] }Supported by: Tous sauf Vectorize et Couchbase`$or`OU logique{ $or: \[{ status: "active" }, { priority: "high" }] }Supported by: Tous sauf Vectorize et Couchbase`$not`NON logique{ price: { $not: { $lt: 100 } } }Supported by: Astra, Qdrant, Upstash, PgVector, libSQL, MongoDB, OracleDB`$nor`NON-OU logique{ $nor: \[{ status: "deleted" }, { archived: true }] }Supported by: Qdrant, Upstash, PgVector, libSQL, MongoDB, OracleDB

### Opérateurs d’élément

`$exists`Correspond aux documents contenant le champ{ rating: { $exists: true } }Supported by: Tous sauf Vectorize, Chroma et Couchbase

### Opérateurs personnalisés

`$contains`Le texte contient la sous-chaîne{ description: { $contains: "sale" } }Supported by: Upstash, libSQL, PgVector, OracleDB`$regex`Correspondance avec une expression régulière{ name: { $regex: "^test" } }Supported by: Qdrant, PgVector, Upstash, MongoDB, OracleDB`$size`Vérification de la longueur du tableau{ tags: { $size: 3 } }Supported by: Astra, libSQL, PgVector, MongoDB, OracleDB`$geo`Requête géospatiale{ location: { $geo: { type: "radius", ... } } }Supported by: Qdrant`$datetime`Requête sur une plage de dates et heures{ created: { $datetime: { range: { gt: "2024-01-01" } } } }Supported by: Qdrant`$hasId`Vérification de l’existence d’un ID de vecteur{ $hasId: \["id1", "id2"] }Supported by: Qdrant`$hasVector`Vérification de l’existence d’un vecteur{ $hasVector: true }Supported by: Qdrant

## Règles et restrictions communes

1. Les noms de champs ne peuvent pas :

   - Contenir de points (.), sauf s’ils font référence à des champs imbriqués
   - Commencer par $ ou contenir des caractères nuls
   - Être des chaînes vides

2. Les valeurs doivent :

   - Être de types JSON valides (chaîne, nombre, booléen, objet, tableau)
   - Ne pas être indéfinies
   - Avoir un type adapté à l’opérateur (par exemple, des nombres pour les comparaisons numériques)

3. Les opérateurs logiques :

   - Doivent contenir des conditions valides
   - Ne peuvent pas être vides
   - Doivent être correctement imbriqués
   - Peuvent uniquement être utilisés au niveau supérieur ou imbriqués dans d’autres opérateurs logiques
   - Ne peuvent pas être utilisés au niveau d’un champ ni imbriqués dans un champ
   - Ne peuvent pas être utilisés dans un opérateur
   - Valide : `{ "$and": [{ "field": { "$gt": 100 } }] }`
   - Valide : `{ "$or": [{ "$and": [{ "field": { "$gt": 100 } }] }] }`
   - Non valide : `{ "field": { "$and": [{ "$gt": 100 }] } }`
   - Non valide : `{ "field": { "$gt": { "$and": [{...}] } } }`

4. Opérateur $not :

   - Doit être un objet
   - Ne peut pas être vide
   - Peut être utilisé au niveau d’un champ ou au niveau supérieur
   - Valide : `{ "$not": { "field": "value" } }`
   - Valide : `{ "field": { "$not": { "$eq": "value" } } }`

5. Imbrication des opérateurs :

   - Les opérateurs logiques doivent contenir des conditions de champ, et non des opérateurs directs
   - Valide : `{ "$and": [{ "field": { "$gt": 100 } }] }`
   - Non valide : `{ "$and": [{ "$gt": 100 }] }`

## Remarques propres à chaque base vectorielle

### Astra

- Les requêtes sur les champs imbriqués sont prises en charge au moyen de la notation par points
- Les champs de type tableau doivent être explicitement définis comme des tableaux dans les métadonnées
- Les valeurs des métadonnées sont sensibles à la casse

### ChromaDB

- Les filtres Where renvoient uniquement les résultats pour lesquels le champ filtré existe dans les métadonnées
- Les champs de métadonnées vides ne sont pas inclus dans les résultats du filtre
- Les champs de métadonnées doivent être présents pour les correspondances négatives (par exemple, $ne ne correspond pas aux documents dont le champ est absent)

### Cloudflare Vectorize

- Nécessite une indexation explicite des métadonnées avant de pouvoir utiliser le filtrage
- Utilisez `createMetadataIndex()` pour indexer les champs sur lesquels vous souhaitez appliquer un filtre
- Jusqu’à 10 index de métadonnées par index Vectorize
- Les valeurs de chaîne sont indexées sur les 64 premiers octets (avec troncature aux limites UTF-8)
- Les valeurs numériques utilisent la précision float64
- Le filtre JSON doit faire moins de 2 048 octets
- Les noms de champs ne peuvent pas contenir de points (.) ni commencer par $
- Les noms de champs sont limités à 512 caractères
- Après la création de nouveaux index de métadonnées, les vecteurs doivent être de nouveau upsertés pour figurer dans les résultats filtrés
- Les requêtes de plage peuvent être moins précises avec de très grands jeux de données (\~10 millions de vecteurs ou plus)

### libSQL

- Prend en charge les requêtes sur des objets imbriqués avec la notation par points
- Les champs de type tableau sont validés afin de vérifier qu’ils contiennent des tableaux JSON valides
- Les comparaisons numériques conservent une gestion correcte des types
- Les tableaux vides dans les conditions sont gérés sans erreur
- Les métadonnées sont stockées dans une colonne JSONB pour permettre des requêtes efficaces

### OracleDB

- Les métadonnées sont stockées au format Oracle JSON avec chaque ligne `VECTOR`
- Les comparaisons scalaires utilisent `JSON_VALUE`, tandis que les vérifications de tableaux, d’existence et de correspondance d’éléments utilisent `JSON_EXISTS`
- `$regex` utilise `REGEXP_LIKE` d’Oracle ; pour les chaînes, `$contains` utilise `LIKE` sans tenir compte de la casse
- Les champs imbriqués sont pris en charge avec la notation par points et convertis en chemins Oracle JSON entre guillemets
- Les valeurs de métadonnées fournies par l’utilisateur sont liées en tant que paramètres au lieu d’être interpolées dans le SQL

### PgVector

- Prise en charge complète des fonctionnalités natives de requête JSON de PostgreSQL
- Gestion efficace des opérations sur les tableaux grâce aux fonctions de tableau natives
- Gestion correcte des types pour les nombres, les chaînes et les booléens
- Les requêtes sur les champs imbriqués utilisent en interne la syntaxe de chemin JSON de PostgreSQL
- Les métadonnées sont stockées dans une colonne JSONB pour permettre une indexation efficace

### Pinecone

- Les noms des champs de métadonnées sont limités à 512 caractères
- Les valeurs numériques doivent être comprises dans la plage ±1e38
- La taille totale des tableaux dans les métadonnées est limitée à 64 Ko
- Les objets imbriqués sont aplatis avec la notation par points
- Les mises à jour des métadonnées remplacent l’intégralité de l’objet de métadonnées

### Qdrant

- Prend en charge le filtrage avancé avec des conditions imbriquées
- Les champs du payload (métadonnées) doivent être explicitement indexés pour pouvoir être filtrés
- Utilisez `createPayloadIndex()` pour indexer les champs sur lesquels vous souhaitez appliquer un filtre :

```typescript
// Index a field before filtering on it
await store.createPayloadIndex({
  indexName: 'my_index',
  fieldName: 'source',
  fieldSchema: 'keyword', // 'keyword' | 'integer' | 'float' | 'geo' | 'text' | 'bool' | 'datetime' | 'uuid'
})

// Now filtering works
const results = await store.query({
  indexName: 'my_index',
  queryVector: queryVector,
  filter: { source: 'document-a' },
})
```

- Gestion efficace des requêtes géospatiales
- Gestion particulière des valeurs nulles et vides
- Fonctionnalités de filtrage propres aux vecteurs
- Les valeurs de date et heure doivent respecter le format RFC 3339

### Upstash

- Les clés des champs de métadonnées sont limitées à 512 caractères
- La taille des requêtes est limitée (évitez les clauses IN volumineuses)
- Les valeurs null/undefined ne sont pas prises en charge dans les filtres
- Conversion interne vers une syntaxe similaire à SQL
- Les comparaisons de chaînes sont sensibles à la casse
- Les mises à jour des métadonnées sont atomiques

### MongoDB

- Prise en charge complète de la syntaxe de requête MongoDB/Sift pour les filtres de métadonnées
- Prend en charge tous les opérateurs standard de comparaison, de tableau, logiques et d’élément
- Prend en charge les champs imbriqués et les tableaux dans les métadonnées
- Le filtrage peut s’appliquer à la fois à `metadata` et au contenu du document d’origine à l’aide des options `filter` et `documentFilter`, respectivement
- `filter` s’applique à l’objet de métadonnées ; `documentFilter` s’applique aux champs du document d’origine
- Aucune limite artificielle concernant la taille ou la complexité des filtres (sous réserve des limites de requête de MongoDB)
- Il est recommandé d’indexer les champs de métadonnées pour obtenir des performances optimales

### Couchbase

- Les filtres de métadonnées ne sont actuellement pas pris en charge. Le filtrage doit être effectué côté client après la récupération des résultats, ou directement à l’aide des fonctionnalités de recherche du SDK Couchbase pour les requêtes plus complexes.

### Amazon S3 Vectors

- Les valeurs d’égalité doivent être primitives (chaîne/nombre/booléen). `null`/`undefined`, les tableaux, les objets et Date ne sont pas autorisés pour l’égalité. Les opérateurs de plage acceptent des nombres ou Date (les dates sont normalisées en millisecondes depuis l’époque Unix).
- `$in`/`$nin` nécessitent des **tableaux non vides de valeurs primitives** ; les éléments Date sont autorisés et normalisés en millisecondes depuis l’époque Unix. **L’égalité de tableaux** n’est pas prise en charge.
- Le ET implicite est canonisé (`{a:1,b:2}` → `{$and:[{a:1},{b:2}]`). Les opérateurs logiques doivent contenir des conditions de champ et utiliser des tableaux non vides. Ils peuvent uniquement apparaître à la racine ou dans d’autres opérateurs logiques (pas dans les valeurs de champ).
- Les clés répertoriées dans `nonFilterableMetadataKeys` lors de la création de l’index sont stockées, mais ne peuvent pas être filtrées. Ce paramètre est immuable.
- $exists nécessite une valeur booléenne.
- Les filtres undefined/null/vides sont traités comme une absence de filtre.
- Le nom de chaque clé de métadonnées est limité à 63 caractères.
- Métadonnées totales par vecteur : jusqu’à 40 Ko (filtrables et non filtrables)
- Nombre total de clés de métadonnées par vecteur : jusqu’à 10
- Métadonnées filtrables par vecteur : jusqu’à 2 Ko
- Clés de métadonnées non filtrables par index vectoriel : jusqu’à 10

## Ressources associées

- [Astra](https://mastra.zisheng.pro/fr/reference/vectors/astra)
- [Chroma](https://mastra.zisheng.pro/fr/reference/vectors/chroma)
- [Cloudflare Vectorize](https://mastra.zisheng.pro/fr/reference/vectors/vectorize)
- [libSQL](https://mastra.zisheng.pro/fr/reference/vectors/libsql)
- [MongoDB](https://mastra.zisheng.pro/fr/reference/vectors/mongodb)
- [OracleDB](https://mastra.zisheng.pro/fr/reference/vectors/oracledb)
- [PgStore](https://mastra.zisheng.pro/fr/reference/vectors/pg)
- [Pinecone](https://mastra.zisheng.pro/fr/reference/vectors/pinecone)
- [Qdrant](https://mastra.zisheng.pro/fr/reference/vectors/qdrant)
- [Upstash](https://mastra.zisheng.pro/fr/reference/vectors/upstash)
- [Amazon S3 Vectors](https://mastra.zisheng.pro/fr/reference/vectors/s3vectors)