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

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 :

// 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
• Chroma
• Cloudflare Vectorize
• libSQL
• MongoDB
• OracleDB
• PgStore
• Pinecone
• Qdrant
• Upstash
• Amazon S3 Vectors