Filtros en consultas de texto

Un filtro proporciona criterios basados en valores para incluir o excluir contenido antes de la ejecución de consultas. Por ejemplo, incluir o excluir documentos en función de las fechas, las ubicaciones o el idioma. Los filtros se especifican en campos individuales. Una definición de campo se debe atribuir como "filtrable" si desea usarla en expresiones de filtro.

Se especifica un filtro mediante la sintaxis de expresión de filtro de OData. A diferencia de la búsqueda de texto completo, un filtro solo es correcto si se produce una coincidencia exacta.

Cuándo se debe usar un filtro

Los filtros son fundamentales para varias experiencias de búsqueda, como la búsqueda geoespacial de servicios cercanos, la navegación por facetas y los filtros de seguridad que muestran únicamente los documentos que un usuario tiene permiso para ver. Si implementa alguna de estas experiencias, se necesita un filtro. El filtro asociado a la consulta de búsqueda proporciona coordenadas de geolocalización, la categoría de faceta que seleccionó el usuario o el id. de seguridad del solicitante.

Entre los escenarios habituales se incluyen los siguientes:

  • Segmentación de los resultados de la búsqueda en función del contenido del índice. A partir de un esquema con la ubicación, las categorías y los servicios de los hoteles, puede crear un filtro para que coincida explícitamente con los criterios (por ejemplo, en Seattle, sobre el agua, con vistas).

  • Implementación de una experiencia de búsqueda con una dependencia de filtro:

    • La navegación por facetas usa un filtro para devolver la categoría de faceta que seleccionó el usuario.
    • La Búsqueda geoespacial usa un filtro para pasar las coordenadas de la ubicación actual en aplicaciones que buscan servicios cercanos y funciones que coinciden dentro de un área o distancia determinadas.
    • 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.
  • Realización de una "búsqueda de números". Los campos numéricos se pueden recuperar y pueden aparecer en los resultados de búsqueda, pero no se pueden hacer búsquedas (de texto completo) en ellos 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 filtro acepta criterios como entrada, convierte la expresión en expresiones booleanas atómicas representadas como un árbol y, posteriormente, evalúa el árbol de filtro a través de campos por los que se puede filtrar en un índice.

El filtrado se produce en paralelo con la búsqueda y define los documentos que se incluirán en un procesamiento descendente para la recuperación de documentos y la puntuación de importancia. 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 en search=*), los criterios de filtro son la única entrada.

Definición de filtros

Los filtros son expresiones de OData que se articulan en la sintaxis de filtro que Azure AI Search admite.

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

Uno de los límites en una expresión de filtro es el límite de tamaño máximo de la solicitud. La solicitud completa, incluido el filtro, puede tener un máximo de 16 MB para POST u 8 KB para GET. También hay un límite en el número de cláusulas de la expresión de filtro. Como regla general, si tiene cientos de cláusulas, está en riesgo de alcanzar el límite. Es recomendable diseñar la aplicación de manera que no genere filtros de tamaño sin enlazar.

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=2020-06-30
{
    "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, consulte OData expression syntax > Examples (Sintaxis de expresiones de OData > Ejemplos).

  • La expresión $filter independiente, sin una cadena de consulta, resulta útil cuando la expresión de filtro puede definir completamente los documentos de interés. Sin una cadena de consulta, no hay ningún análisis lingüístico ni léxico, ninguna puntuación y ninguna clasificación. Observe que la cadena de búsqueda es simplemente un asterisco, que significa "coincidencia 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 una 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 en 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. Usar 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, con la unión de los documentos que coinciden con cada expresión enviada en la respuesta. Este patrón de uso se logra a través de la función search.ismatchscoring. 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 usando and en lugar de or, pero esto es funcionalmente equivalente al uso de los parámetros search y $filter en una solicitud de búsqueda. Por ejemplo, las dos consultas siguientes producen el mismo resultado:

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

Requisitos de campo para filtrar

En la API REST, el filtrado está activado de forma predeterminada para campos simples. Los campos que se pueden filtrar aumentan el tamaño del índice. Asegúrese de definir "filterable": false para los campos que no tiene previsto usar en un filtro. Para obtener más información sobre la configuración de definiciones de campos, consulte Create Index (Creación de índices).

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

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

Hacer que un campo existente se pueda filtrar

No puede modificar los campos existentes para hacer que se puedan filtrar. Como alternativa, deberá agregar un campo nuevo o volver a generar el índice. Para más información sobre cómo volver a compilar un índice o volver a rellenar los campos, consulte Recompilación de índices de Azure AI Search.

Conceptos básicos de filtro de texto

Los filtros de texto coinciden con los campos de cadena en las cadenas literales que se proporcionan 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 los filtros de texto, por lo que las comparaciones se aplican solo a coincidencias exactas. Por ejemplo, si un campo f contiene "sunny day", $filter=f eq 'sunny' no coincide, pero $filter=f eq 'sunny day' sí.

Las cadenas de texto distinguen mayúsculas de minúsculas, lo que significa que los filtros de texto distinguen mayúsculas de minúsculas de forma predeterminada. Por ejemplo, $filter=f eq 'Sunny day' no encontrará "sunny day". Sin embargo, puede usar un normalizador para que el filtrado no distinga mayúsculas de minúsculas.

Enfoques para el filtrado en el texto

Enfoque Descripción Cuándo se deben usar
search.in Una función que coincide con un campo en una lista delimitada de cadenas. Se recomienda para los filtros de seguridad y para los filtros donde se necesita que muchos valores de texto sin formato coincidan con un campo de cadena. La función search.in está diseñada para acelerar el proceso y es mucho más rápida que comparar explícitamente el campo con cada cadena mediante eq y or.
search.ismatch Una función que permite combinar las operaciones de búsqueda de texto completo con operaciones de filtro estrictamente booleano en la misma expresión de filtro. Use search.ismatch (o su equivalente de puntuación, search.ismatchscoring) cuando quiera varias combinaciones de filtro de búsqueda en una sola solicitud. También puede usarla para que un filtro contains filtre una cadena parcial en una cadena mayor.
$filter=field operator string Expresión definida por el usuario compuesta de campos, operadores y valores. Se usa cuando se quieren buscar coincidencias exactas entre un campo de cadena y un valor de cadena.

Conceptos básicos de filtro numérico

Los campos numéricos no se pueden definir como searchable en el contexto de 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á artículos con un precio de 99.99 USD. Lo que se devolverá son elementos con el número 99 en los campos de cadena del documento. Por tanto, si tiene datos numéricos, se asume que los va a usar para los filtros, como rangos, facetas, grupos, etc.

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

Pasos siguientes

En primer lugar, pruebe el Explorador de búsqueda en el portal para enviar consultas con parámetros $filter. El índice real-estate-sample proporciona resultados interesantes para las siguiente 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 OData Filter Expression Syntax > Examples (Sintaxis de expresión de filtro de OData > Ejemplos).

Consulte también