Filtres pour la recherche de mots clés dans Recherche Azure AI

Un filtre fournit des critères basés sur des valeurs pour inclure ou exclure du contenu avant l’exécution de requête pour la recherche par mot clé, ou avant ou après l’exécution de requête pour la recherche vectorielle. Les filtres sont appliqués aux champs non-vecteurs, mais peuvent être utilisés dans la recherche vectorielle si les documents incluent des champs non-vecteurs. Par exemple, pour les index organisés autour du contenu segmenté, vous pouvez avoir des champs de niveau parent ou des champs de métadonnées qui peuvent être filtrés.

Cet article explique le filtrage pour la recherche de mots clés. Pour plus d’informations sur les vecteurs, consultez Ajouter un filtre dans une requête vectorielle.

Un filtre est spécifié à l’aide de la syntaxe d’expression de filtre OData. Contrairement à la recherche de mots clés et de vecteurs, un filtre réussit uniquement si la correspondance est exacte.

Quand utiliser un filtre

Les filtres sont fondamentaux pour plusieurs expériences de recherche, notamment la recherche géospatiale « trouver près de moi », la navigation à facettes et les filtres de sécurité qui affichent uniquement ces documents qu’un utilisateur est autorisé à voir. Si vous implémentez l’une de ces expériences, un filtre est requis. Il s’agit du filtre attaché à la requête de recherche qui fournit les coordonnées de géolocalisation, la catégorie de facette sélectionnée par l’utilisateur ou l’ID de sécurité du demandeur.

Les scénarios courants sont les suivants :

• Segmentez les résultats de la recherche en fonction du contenu de l’index. Compte tenu d’un schéma avec l’emplacement, les catégories et les commodités de l’hôtel, vous pouvez créer un filtre pour correspondre explicitement aux critères (à Seattle, sur l’eau, avec une vue).

• Mettez en place une expérience de recherche qui inclut une dépendance au filtre :

  • La navigation à facettes utilise un filtre pour renvoyer la catégorie de facette sélectionnée par l’utilisateur.
  • La recherche géospatiale utilise un filtre pour passer les coordonnées de l’emplacement actuel dans les applications et fonctions « trouver près de moi » qui correspondent dans une zone ou par distance.
  • Les filtres de sécurité utilisent des identificateurs de sécurité en tant que critères de filtre, où une correspondance dans l’index sert de proxy pour les droits d’accès au document.

• Effectuez une « recherche de nombres ». Les champs numériques sont récupérables et peuvent apparaître dans les résultats de recherche, mais ils ne sont pas pouvant faire l’objet d’une recherche en texte intégral individuellement. Si vous avez besoin de critères de sélection basés sur des données numériques, utilisez un filtre.

Comment les filtres sont exécutés

Au moment de la requête, un analyseur de filtre accepte des critères comme entrée, convertit l’expression en expressions booléennes atomiques représentées sous forme d’arborescence, puis évalue l’arborescence de filtres sur les champs filtrables dans un index.

Le filtrage se produit en tandem avec la recherche, qui qualifie les documents à inclure dans le traitement en aval pour la récupération de documents et le scoring de pertinence. Lorsqu’il est associé à une chaîne de recherche, le filtre réduit efficacement l’ensemble de rappels de l’opération de recherche suivante. Lorsqu’elle est utilisée seule (par exemple, lorsque la chaîne de requête est vide où search=*), les critères de filtre sont la seule entrée.

Définition des filtres

Les filtres s’appliquent au contenu texte et numérique (non-vecteur) sur les champs qui sont attribués en tant que filterable.

Les filtres sont des expressions OData, exprimées dans la syntaxe filter prises en charge par Recherche Azure AI.

Vous pouvez spécifier un filtre pour chaque opération de recherche , mais le filtre lui-même peut inclure plusieurs champs, plusieurs critères et, si vous utilisez une ismatch fonction, plusieurs expressions de recherche en texte intégral. Dans une expression de filtre en plusieurs parties, vous pouvez spécifier des prédicats dans n’importe quel ordre (soumis aux règles de précédence de l’opérateur). Il n’y a pas de gain appréciable en termes de performances si vous essayez de réorganiser les prédicats dans une séquence particulière.

L’une des limites d’une expression de filtre est la limite de taille maximale de la requête. La requête entière, inclusive du filtre, peut être d’un maximum de 16 Mo pour POST, ou de 8 Ko pour GET. Il existe également une limite quant au nombre de clauses de votre expression de filtre. Une bonne règle de pouce est que si vous avez des centaines de clauses, vous risquez d’atteindre la limite. Nous vous recommandons de concevoir votre application de telle sorte qu’elle ne génère pas de filtres de taille non délimitée.

Les exemples suivants représentent des définitions de filtre prototypage dans plusieurs API.

POST https://[service name].search.windows.net/indexes/hotels/docs/search?api-version=2026-04-01
{
    "search": "*",
    "filter": "Rooms/any(room: room/BaseRate lt 150.0)",
    "select": "HotelId, HotelName, Rooms/Description, Rooms/BaseRate"
}

options = new SearchOptions()
{
    Filter = "Rating gt 4",
    OrderBy = { "Rating desc" }
};

Modèles de filtre

Les exemples suivants illustrent plusieurs modèles d’utilisation pour les scénarios de filtre. Pour plus d’idées, consultez exemples de syntaxe > d’expression OData.

• Les $filter autonomes, sans chaîne de requête, sont utiles lorsque l’expression de filtre est en mesure de qualifier pleinement les documents intéressants. Sans chaîne de requête, il n’existe aucune analyse lexicale ou linguistique, aucun scoring et aucun classement. Notez que la chaîne de recherche n’est qu’un astérisque, ce qui signifie « faire correspondre tous les documents ».

  {
    "search": "*",
    "filter": "Rooms/any(room: room/BaseRate ge 60 and room/BaseRate lt 300) and Address/City eq 'Honolulu"
  }
  

• Combinaison de chaîne de requête et de $filter, où le filtre crée le sous-ensemble et la chaîne de requête fournit les entrées de terme pour la recherche en texte intégral sur le sous-ensemble filtré. L’ajout de termes (théâtres accessibles à pied) introduit des scores de pertinence dans les résultats, dans lesquels les documents correspondant le mieux aux termes sont mieux classés. L’utilisation d’un filtre avec une chaîne de requête est le modèle d’utilisation le plus courant.

  {
    "search": "walking distance theaters",
    "filter": "Rooms/any(room: room/BaseRate ge 60 and room/BaseRate lt 300) and Address/City eq 'Seattle'"
  }
  
  

• Requêtes composées, séparées par « ou », chacune avec ses propres critères de filtre (par exemple, « beagles » dans « dog » ou « siamese » dans « cat »). Les expressions, combinées avec or, sont évaluées individuellement, avec l'union des documents correspondant à chaque expression envoyée en réponse. Ce modèle d’utilisation est obtenu par le biais de la search.ismatchscoring fonction. Vous pouvez également utiliser la version sans notation, search.ismatch.

  # Match on hostels rated higher than 4 OR 5-star motels.
  $filter=search.ismatchscoring('hostel') and Rating ge 4 or search.ismatchscoring('motel') and Rating eq 5
  
  # Match on 'luxury' or 'high-end' in the description field OR on category exactly equal to 'Luxury'.
  $filter=search.ismatchscoring('luxury | high-end', 'Description') or Category eq 'Luxury'&$count=true
  

  Il est également possible de combiner la recherche en texte intégral via search.ismatchscoring avec des filtres à l’aide de and au lieu de or, mais cela équivaut fonctionnellement à l’utilisation des paramètres search et $filter dans une requête de recherche. Par exemple, les deux requêtes suivantes produisent le même résultat :

  $filter=search.ismatchscoring('pool') and Rating ge 4
  
  search=pool&$filter=Rating ge 4
  

Exigences de champ pour le filtrage

Dans l’API REST, le filtrage est activé par défaut pour les champs simples. Les champs filtrables augmentent la taille de l’index ; veillez à définir "filterable": false pour les champs que vous ne prévoyez pas d’utiliser réellement dans un filtre. Pour plus d’informations sur les paramètres des définitions de champs, consultez Créer un index.

Dans le SDK Azure, le filtrage est off par défaut. Vous pouvez rendre un champ filtrable en définissant la propriété IsFilterable de l’objet SearchField correspondant sur true. Dans l’exemple suivant, l’attribut est défini sur la Rating propriété d’une classe de modèle qui correspond à la définition d’index.

[SearchField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
public double? Rating { get; set; }

Rendre un champ existant filtrable

Vous ne pouvez pas modifier les champs existants pour les rendre filtrables. Au lieu de cela, vous devez ajouter un nouveau champ ou reconstruire l’index. Pour plus d’informations sur la reconstruction d’un index ou le remplissage de champs, consultez How to rebuild an Recherche Azure AI index.

Notions de base du filtre de texte

Les filtres de texte comparent les champs de chaîne aux chaînes littérales que vous fournissez dans le filtre : $filter=Category eq 'Resort and Spa'

Contrairement à la recherche en texte intégral, il n’y a pas d’analyse lexicale ou de rupture de mots pour les filtres de texte, de sorte que les comparaisons ne concernent que les correspondances exactes. Par exemple, supposons qu’un champ f contient « jour ensoleillé », $filter=f eq 'sunny' ne correspond pas, mais $filter=f eq 'sunny day' le fera.

Les chaînes de texte respectent la casse, et les filtres de texte respectent la casse par défaut. Par exemple, $filter=f eq 'Sunny day' ne trouve pas « jour ensoleillé ». Toutefois, vous pouvez utiliser un normaliseur pour faire en sorte que le filtrage ne respecte pas la casse.

Approches pour le filtrage sur le texte

Notions de base du filtre numérique

Les champs numériques ne sont pas searchable dans le contexte de la recherche en texte intégral. Seules les chaînes sont soumises à la recherche en texte intégral. Par exemple, si vous entrez 99,99 en tant que terme de recherche, vous ne récupérerez pas les articles facturés à 99,99 $. Au lieu de cela, vous verrez les éléments qui ont le nombre 99 dans les champs de chaîne du document. Par conséquent, si vous avez des données numériques, l’hypothèse est que vous les utiliserez pour les filtres, notamment les plages, les facettes, les groupes, etc.

Les documents qui contiennent des champs numériques (prix, taille, référence SKU, ID) fournissent ces valeurs dans les résultats de recherche si le champ est marqué retrievable. Voici que la recherche en texte intégral elle-même n’est pas applicable aux types de champs numériques.

Étapes suivantes

Tout d’abord, essayez Search Explorer dans le portail Azure pour envoyer des requêtes avec des paramètres $filter. L'index immobilier-échantillon réel fournit des résultats intéressants pour les requêtes filtrées suivantes en les collant dans la barre de recherche :

# Geo-filter returning documents within 5 kilometers of Redmond, Washington state
# Use $count=true to get a number of hits returned by the query
# Use $select to trim results, showing values for named fields only
# Use search=* for an empty query string. The filter is the sole input

search=*&$count=true&$select=description,city,postCode&$filter=geo.distance(location,geography'POINT(-122.121513 47.673988)') le 5

# Numeric filters use comparison like greater than (gt), less than (lt), not equal (ne)
# Include "and" to filter on multiple fields (baths and bed)
# Full text search is on John Leclerc, matching on John or Leclerc

search=John Leclerc&$count=true&$select=source,city,postCode,baths,beds&$filter=baths gt 3 and beds gt 4

# Text filters can also use comparison operators
# Wrap text in single or double quotes and use the correct case
# Full text search is on John Leclerc, matching on John or Leclerc

search=John Leclerc&$count=true&$select=source,city,postCode,baths,beds&$filter=city gt 'Seattle'

Pour utiliser d’autres exemples, consultez exemples de syntaxe > d’expression de filtre OData.

Voir aussi

• Comment fonctionne la recherche en texte intégral dans Recherche Azure AI
• API REST De recherche de documents
• Syntaxe de requête simple
• Syntaxe de requête Lucene
• Types de données pris en charge