Compartir vía

Introducción al lenguaje de OData para las expresiones $filter, $orderby y $select en Azure AI Search

  • Artículo

En este artículo se proporciona información general sobre el lenguaje de expresiones de OData que se usa en $filter, $order-by, y $select expresiones para la búsqueda de palabras clave en Azure AI Search sobre campos numéricos y de cadena (novector).

El lenguaje se presenta en sentido ascendente, empezando por los elementos más básicos. Las expresiones OData que se pueden construir en una solicitud de consulta pueden ser desde simples hasta muy complejas, pero todas comparten elementos comunes. Entre los elementos compartidos se incluyen los siguientes:

  • Rutas de acceso de campo, que hacen referencia a campos específicos del índice.
  • Constantes, que son valores literales de un tipo de datos determinado.

Una vez que comprenda estos conceptos comunes, puede continuar con la sintaxis de nivel superior para cada expresión:

  • Las expresiones $filter se evalúan durante el análisis de la consulta y se restringe la búsqueda a campos específicos o se agregan criterios de coincidencia que se usan durante los exámenes de índice.
  • Las expresiones $orderby se aplican como un paso posterior al procesamiento en un conjunto de resultados para ordenar los documentos que se devuelven.
  • Las expresiones $select determinan qué campos de un documento se incluyen en el conjunto de resultados.

La sintaxis de estas expresiones es distinta de la sintaxis de consulta simple o completa que se usa en el parámetro search, aunque hay cierto solapamiento en la sintaxis de los campos de referencia.

Para obtener ejemplos en otros lenguajes, como Python o C#, consulte los ejemplos del repositorioazure-search-vector-samples.

Nota:

La terminología de Azure AI Search tiene ciertas diferencias con respecto al estándar de OData. Lo que llamamos un campo en Azure AI Search se denomina una propiedad en OData y lo mismo sucede con ruta de acceso de campo y ruta de acceso de propiedad. Un índice que contiene documentos en Azure AI Search se conoce más generalmente en OData como un conjunto de entidades que contiene entidades. En esta referencia se usará la terminología de Azure AI Search.

Rutas de acceso de campo

La siguiente EBNF (notación de Backus-Naur extendida) define la gramática de las rutas de acceso de campo:

field_path ::= identifier('/'identifier)*

identifier ::= [a-zA-Z_][a-zA-Z_0-9]*

También está disponible un diagrama de sintaxis interactivo:

Diagrama de sintaxis de OData para Azure AI Search

Nota:

Consulte Referencia de la sintaxis de expresiones de OData para Azure AI Search para obtener la EBNF completa.

Una ruta de acceso de campo se compone de uno o varios identificadores separados por barras diagonales. Cada identificador es una secuencia de caracteres que debe comenzar con una letra ASCII o un carácter de subrayado y contener solo letras ASCII, dígitos o caracteres de subrayado. Las letras pueden ser mayúsculas o minúsculas.

Un identificador puede hacer referencia al nombre de un campo o a una variable de rango en el contexto de una expresión de colección (any o all) en un filtro. Una variable de rango es como una variable de bucle que representa el elemento actual de la colección. Si las colecciones son complejas, esa variable representa un objeto, que es el motivo de que pueda usar rutas de acceso de campo para hacer referencia a subcampos de la variable. Esta sintaxis es análoga a la notación de puntos de muchos lenguajes de programación.

En la tabla siguiente se muestran ejemplos de rutas de acceso de campo:

Ruta de acceso de campo Descripción
HotelName Hace referencia a un campo de nivel superior del índice.
Address/City Hace referencia al subcampo City de un campo complejo en el índice; Address es de tipo Edm.ComplexType en este ejemplo.
Rooms/Type Hace referencia al subcampo Type de un campo de colección complejo en el índice; Rooms es de tipo Collection(Edm.ComplexType) en este ejemplo.
Stores/Address/Country Hace referencia al subcampo Country del subcampo Address de un campo de colección complejo en el índice; Stores es de tipo Collection(Edm.ComplexType) y Address es de tipo Edm.ComplexType en este ejemplo.
room/Type Hace referencia al subcampo Type de la variable de rango room, por ejemplo, en la expresión de filtro Rooms/any(room: room/Type eq 'deluxe').
store/Address/Country Hace referencia al subcampo Country del subcampo Address de la variable de rango store, por ejemplo, en la expresión de filtro Stores/any(store: store/Address/Country eq 'Canada').

El significado de una ruta de acceso de campo varía según el contexto. En los filtros, una ruta de acceso de campo hace referencia al valor de una única instancia de un campo en el documento actual. En otros contextos, como $orderby, $select o en la búsqueda clasificada por campos de la sintaxis completa de Lucene, una ruta de acceso de campo hace referencia al campo propiamente dicho. Esta diferencia tiene algunas consecuencias en cómo se usan las rutas de acceso de campo en los filtros.

Considere la ruta de acceso de campo Address/City. En un filtro, esta ruta hacer referencia a una única ciudad del documento actual, como "San Francisco". En cambio, Rooms/Type hace referencia al subcampo Type para muchas habitaciones (por ejemplo, "standard" para la primera habitación, "deluxe" para la segunda, etc.). Puesto que Rooms/Type no hace referencia a una única instancia del subcampo Type, no se puede usar directamente en un filtro. Así que, para filtrar por el tipo de habitación, usaría una expresión lambda con una variable de rango, como esta:

Rooms/any(room: room/Type eq 'deluxe')

En este ejemplo, la variable de rango room aparece en la ruta de acceso de campo room/Type. De este modo, room/Type hace referencia al tipo de habitación actual en el documento actual. Como es una única instancia del subcampo Type, se puede usar directamente en el filtro.

Uso de rutas de acceso de campo

Las rutas de acceso de campo se usan muchos parámetros de las API REST de Azure AI Search. En la tabla siguiente se enumeran todos los lugares donde pueden usarse, además de las restricciones sobre su uso:

API Nombre de parámetro Restricciones
Create or Update Index suggesters/sourceFields Ninguno
Create or Update Index scoringProfiles/text/weights Solo puede hacer referencia a campos que permiten realizar búsquedas.
Create or Update Index scoringProfiles/functions/fieldName Solo puede hacer referencia a campos filtrables.
Buscar search cuando queryType es full Solo puede hacer referencia a campos que permiten realizar búsquedas.
Buscar facet Solo puede hacer referencia a campos clasificables
Buscar highlight Solo puede hacer referencia a campos que permiten realizar búsquedas.
Buscar searchFields Solo puede hacer referencia a campos que permiten realizar búsquedas.
Suggest y Autocomplete searchFields Solo puede hacer referencia a campos que forman parte de un proveedor de sugerencias.
Search, Suggest y Autocomplete $filter Solo puede hacer referencia a campos filtrables.
Search y Suggest $orderby Solo puede hacer referencia a campos ordenables.
Search, Suggest y Lookup $select Solo puede hacer referencia a campos recuperables

Constantes

Las constantes en OData son valores literales de un determinado tipo de Entity Data Model (EDM). Consulte Tipos de datos admitidos para ver una lista de los tipos que se admiten en Azure AI Search. No se admiten constantes de tipos de colección.

En la tabla siguiente se muestran ejemplos de constantes para cada uno de los tipos de datos novector que admiten expresiones de OData:

Tipo de datos Constantes de ejemplo
Edm.Boolean true, false
Edm.DateTimeOffset 2019-05-06T12:30:05.451Z
Edm.Double 3.14159, -1.2e7, NaN, INF, -INF
Edm.GeographyPoint geography'POINT(-122.131577 47.678581)'
Edm.GeographyPolygon geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))'
Edm.Int32 123, -456
Edm.Int64 283032927235
Edm.String 'hello'

Caracteres especiales de escape en constantes de cadena

Las constantes de cadena en OData están delimitadas por comillas simples. Si tiene que crear una consulta con una constante de cadena que, a su vez, pueda contener comillas simples, puede escapar las comillas incrustadas si las duplica.

Por ejemplo, una frase con un apóstrofo sin formato, como "Alice's car", se representaría en OData como la constante de cadena 'Alice''s car'.

Importante

Al construir filtros mediante programación, es importante recordar escapar las constantes de cadena que proceden de los datos proporcionados por el usuario. Esto es para mitigar la posibilidad de ataques por inyección de código, en especial cuando se usan filtros para implementar el recorte de seguridad.

Sintaxis de las constantes

El siguiente EBNF (notación de Backus-Naur extendida) define la gramática de la mayoría de las constantes que se muestran en la tabla anterior. La gramática de los tipos geoespaciales se puede encontrar en Funciones geoespaciales de OData en Azure AI Search.

constant ::=
    string_literal
    | date_time_offset_literal
    | integer_literal
    | float_literal
    | boolean_literal
    | 'null'

string_literal ::= "'"([^'] | "''")*"'"

date_time_offset_literal ::= date_part'T'time_part time_zone

date_part ::= year'-'month'-'day

time_part ::= hour':'minute(':'second('.'fractional_seconds)?)?

zero_to_fifty_nine ::= [0-5]digit

digit ::= [0-9]

year ::= digit digit digit digit

month ::= '0'[1-9] | '1'[0-2]

day ::= '0'[1-9] | [1-2]digit | '3'[0-1]

hour ::= [0-1]digit | '2'[0-3]

minute ::= zero_to_fifty_nine

second ::= zero_to_fifty_nine

fractional_seconds ::= integer_literal

time_zone ::= 'Z' | sign hour':'minute

sign ::= '+' | '-'

/* In practice integer literals are limited in length to the precision of
the corresponding EDM data type. */
integer_literal ::= digit+

float_literal ::=
    sign? whole_part fractional_part? exponent?
    | 'NaN'
    | '-INF'
    | 'INF'

whole_part ::= integer_literal

fractional_part ::= '.'integer_literal

exponent ::= 'e' sign? integer_literal

boolean_literal ::= 'true' | 'false'

También está disponible un diagrama de sintaxis interactivo:

Diagrama de sintaxis de OData para Azure AI Search

Nota:

Consulte Referencia de la sintaxis de expresiones de OData para Azure AI Search para obtener la EBNF completa.

Generación de expresiones a partir de rutas de acceso de campo y constantes

Las rutas de acceso de campo y las constantes son la parte más básica de una expresión de OData, pero ya son expresiones completas por derecho propio. De hecho, el parámetro $select de Azure AI  Search no es más que una lista separada por comas de rutas de acceso de campo y $orderby no es mucho más complicado que $select. Si resulta que tiene un campo de tipo Edm.Boolean en el índice, puede escribir incluso un filtro que no sea si no la ruta de acceso de ese campo. Las constantes true y false son igualmente filtros válidos.

Sin embargo, es más común tener expresiones complejas que hacen referencia a más de un campo y constante. Estas expresiones se compilan de diferentes maneras según el parámetro.

La siguiente EBNF (notación de Backus-Naur extendida) define la gramática de los parámetros $filter, $orderby y $select. Estos parámetros se generan a partir de expresiones más sencillas que hacen referencia a las rutas de acceso de campo y a las constantes:

filter_expression ::= boolean_expression

order_by_expression ::= order_by_clause(',' order_by_clause)*

select_expression ::= '*' | field_path(',' field_path)*

También está disponible un diagrama de sintaxis interactivo:

Diagrama de sintaxis de OData para Azure AI Search

Nota:

Consulte Referencia de la sintaxis de expresiones de OData para Azure AI Search para obtener la EBNF completa.

Pasos siguientes

Los parámetros $orderby y $select son ambos listas separadas por comas de expresiones más sencillas. El parámetro $filter es una expresión booleana que se compone de subexpresiones más sencillas. Estas subexpresiones se combinan mediante operadores lógicos, como and, or y not, operadores de comparación, como eq, lt, gt, etc. y operadores de colección, como any y all.

Los parámetros $filter, $orderby, y $select se exploran con más detalle en los siguientes artículos: