Filtra la búsqueda de palabras clave en Búsqueda de Azure AI

Un filtro proporciona criterios basados en valores para incluir o excluir contenido antes de la ejecución de consultas para la búsqueda de palabras clave, o antes o después de la ejecución de consultas para la búsqueda vectorial. Los filtros se aplican a campos no vectores, pero se pueden usar en la búsqueda vectorial si los documentos incluyen campos no vectores. Por ejemplo, en el caso de los índices organizados en torno al contenido fragmentado, es posible que tenga campos de nivel primario o campos de metadatos que se puedan filtrar.

En este artículo se explica el filtrado de la búsqueda de palabras clave. Para obtener más información sobre los vectores, vea Agregar un filtro en una consulta vectorial.

Se especifica un filtro mediante la sintaxis de expresión de filtro OData. A diferencia de la palabra clave y la búsqueda vectorial, un filtro solo se realiza correctamente si la coincidencia es exacta.

Cuándo usar un filtro

Los filtros son fundamentales para varias experiencias de búsqueda, como la búsqueda geoespacial "buscar cerca de mí", la navegación por facetas y los filtros de seguridad que muestran solo los documentos que un usuario puede ver. Si implementa cualquiera de estas experiencias, se requiere un filtro. Es el filtro asociado a la consulta de búsqueda que proporciona las coordenadas de geolocalización, la categoría de faceta seleccionada por el usuario o el identificador de seguridad del solicitante.

Entre los escenarios comunes se incluyen:

• Segmentación de resultados de búsqueda en función del contenido del índice. Dado un esquema con ubicación de hotel, categorías y comodidades, puede crear un filtro para que coincida explícitamente con criterios (en Seattle, junto al agua, con una vista).

• Implemente una experiencia de búsqueda que incluya una dependencia de filtro:

  • La navegación por facetas usa un filtro para devolver la categoría de faceta seleccionada por el usuario.
  • La búsqueda geoespacial usa un filtro para pasar coordenadas de la ubicación actual en aplicaciones y funciones "buscar cerca de mí" que coinciden dentro de un área o distancia.
  • Los filtros de seguridad pasan los identificadores de seguridad como criterios de filtro, donde una coincidencia en el índice actúa como un proxy para los derechos de acceso al documento.

• Realice una "búsqueda de números". Los campos numéricos se pueden recuperar y pueden aparecer en los resultados de la búsqueda, pero no se pueden buscar (sujeto a la búsqueda de texto completo) individualmente. Si necesita criterios de selección basados en datos numéricos, use un filtro.

Cómo se ejecutan los filtros

En el momento de la consulta, un analizador de filtros acepta criterios como entrada, convierte la expresión en expresiones booleanas atómicas representadas como un árbol y, a continuación, evalúa el árbol de filtro sobre campos filtrables en un índice.

El filtrado se produce junto con la búsqueda, calificando los documentos que se van a incluir en el procesamiento descendente para la recuperación de documentos y la puntuación de relevancia. Combinado con la cadena de búsqueda, el filtro reduce de forma eficaz el conjunto de recuperación de la operación de búsqueda posterior. Cuando se usa solo (por ejemplo, cuando la cadena de consulta está vacía donde search=*), los criterios de filtro son la única entrada.

Cómo se definen los filtros

Los filtros se aplican al contenido de texto y numérico que no sea vectorial en campos atribuidos como filterable.

Los filtros son expresiones de OData, articuladas en la sintaxis filter compatibles con Búsqueda de Azure AI.

Puede especificar un filtro para cada operación de búsqueda , pero el propio filtro puede incluir varios campos, varios criterios y, si usa una ismatch función, varias expresiones de búsqueda de texto completo. En una expresión de filtro de varias partes, puede especificar predicados en cualquier orden (sujeto a las reglas de precedencia del operador). No hay ninguna ganancia apreciable en el rendimiento si intenta reorganizar predicados en una secuencia determinada.

Uno de los límites de una expresión de filtro es el límite de tamaño máximo de la solicitud. Toda la solicitud, incluido el filtro, puede ser un máximo de 16 MB para POST o 8 KB para GET. También hay un límite en el número de cláusulas de la expresión de filtro. Una buena regla general es que, si tiene cientos de cláusulas, corre el riesgo de alcanzar el límite. Se recomienda diseñar su aplicación de modo que evite generar filtros de tamaño ilimitado.

Los ejemplos siguientes representan definiciones de filtro prototípicas en varias 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" }
};

Patrones de filtro

En los ejemplos siguientes se muestran varios patrones de uso para escenarios de filtro. Para obtener más ideas, vea Ejemplos de sintaxis > de expresiones de OData.

• Los $filter independientes, sin una cadena de consulta, resultan útiles cuando la expresión de filtro puede calificar completamente los documentos de interés. Sin una cadena de consulta, no hay ningún análisis léxico o lingüístico, sin puntuación ni clasificación. Observe que la cadena de búsqueda es simplemente un asterisco, lo que significa "coincidir con todos los documentos".

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

• Combinación de cadena de consulta y $filter, donde el filtro crea el subconjunto y la cadena de consulta proporciona las entradas de términos para la búsqueda de texto completo sobre el subconjunto filtrado. La adición de términos (cines a poca distancia) introduce puntuaciones de búsqueda en los resultados, donde los documentos que mejor coinciden con los términos se clasifican en primer lugar. El uso de un filtro con una cadena de consulta es el patrón de uso más común.

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

• Consultas compuestas, separadas por "or", cada una con sus propios criterios de filtro (por ejemplo, 'beagles' en 'perro' o 'siamés' en 'gato'). Las expresiones combinadas con or se evalúan individualmente, y la unión de documentos que coinciden con cada expresión es devuelta en la respuesta. Este patrón de uso se logra a través de la search.ismatchscoring función . También puede usar la versión sin puntuación, 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
  

  También es posible combinar la búsqueda de texto completo a través de search.ismatchscoring con filtros mediante and en lugar de or, pero esto es funcionalmente equivalente al uso de los search parámetros y $filter en una solicitud de búsqueda. Por ejemplo, las dos consultas siguientes generan el mismo resultado:

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

Requisitos de campo para el filtrado

En la API REST, el filtrado está activado de forma predeterminada para campos simples. Los campos filtrables aumentan el tamaño del índice; Asegúrese de establecer "filterable": false para los campos que no planea usar realmente en un filtro. Para obtener más información sobre la configuración de las definiciones de campo, vea Crear índice.

En los SDK de Azure, la función de filtrado está desactivada de forma predeterminada. Puede hacer que un campo se pueda filtrar estableciendo la propiedad IsFilterable del objeto SearchField correspondiente en true. En el ejemplo siguiente, el atributo se establece en la Rating propiedad de una clase de modelo que se asigna a la definición de índice.

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

Hacer que un campo existente se pueda filtrar

No se pueden modificar los campos existentes para que se puedan filtrar. En su lugar, debe añadir un nuevo campo o reconstruir el índice. Para obtener más información sobre cómo volver a generar un índice o volver a rellenar campos, vea Cómo recompilar un índice de Búsqueda de Azure AI.

Aspectos básicos del filtro de texto

Los filtros de texto evalúan los campos de texto contra las cadenas literales especificadas en el filtro: $filter=Category eq 'Resort and Spa'

A diferencia de la búsqueda de texto completo, no hay ningún análisis léxico ni separación de palabras para filtros de texto, por lo que las comparaciones son solo para coincidencias exactas. Por ejemplo, suponga que un campo f contiene "día soleado", $filter=f eq 'sunny' no coincide, pero $filter=f eq 'sunny day' lo hará.

Las cadenas de texto son sensibles a mayúsculas y minúsculas, lo que significa que los filtros de texto también son sensibles a mayúsculas y minúsculas de forma predeterminada. Por ejemplo, $filter=f eq 'Sunny day' no encontrará "día soleado". Sin embargo, puede usar un normalizador para que el filtrado no distinga mayúsculas de minúsculas.

Enfoques para el filtrado de texto

Aspectos básicos del filtro numérico

Los campos numéricos searchable no se consideran en el contexto de la búsqueda de texto completo. Solo las cadenas están sujetas a la búsqueda de texto completo. Por ejemplo, si escribe 99,99 como término de búsqueda, no obtendrá los artículos con un precio de 99,99 USD. En su lugar, verá elementos que tienen el número 99 en campos de cadena del documento. Por lo tanto, si tiene datos numéricos, la suposición es que las usará para filtros, incluidos intervalos, facetas, grupos, etc.

Los documentos que contienen campos numéricos (precio, tamaño, SKU, identificador) proporcionan esos valores en los resultados de búsqueda si el campo está marcado como retrievable. El punto aquí es que la propia búsqueda de texto completo no es aplicable a los tipos de campo numéricos.

Pasos siguientes

En primer lugar, pruebe Search explorer en el portal de Azure para enviar consultas con parámetros $filter. El índice real-estate-sample proporciona resultados interesantes para las siguientes consultas filtradas al pegarlas en la barra de búsqueda:

# 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'

Para trabajar con más ejemplos, consulte Ejemplos de sintaxis > de expresiones de filtro de OData.

Consulte también

• Cómo funciona la búsqueda de texto completo en Búsqueda de Azure AI
• API REST de documentos de búsqueda
• Sintaxis de consulta simple
• Sintaxis de consulta de Lucene
• Tipos de datos admitidos