Sintaxis de consulta simple en Azure AI Search

Artículo
12/10/2024

Para escenarios de búsqueda de texto completo, Búsqueda de Azure AI implementa dos lenguajes de consulta basados en Lucene, cada uno alineado con un analizador de consultas. Analizador de consultas simple es el valor predeterminado. Trata casos de uso comunes e intenta interpretar una solicitud aunque no esté compuesta perfectamente. El otro analizador es Lucene Query Parser y admite construcciones de consulta más avanzadas.

Este artículo es la referencia de sintaxis de consulta para el analizador de consultas simple.

La sintaxis de consulta para ambos analizadores se aplica a expresiones de consulta pasadas en el parámetro search de una solicitud de consulta. No se debe confundirse con la sintaxis de OData, que tiene su propia sintaxis y reglas para las expresiones filter y orderby de la misma solicitud.

Aunque el analizador simple se basa en la clase del analizador de consultas simples de Apache Lucene, su implementación en Azure AI Search excluye la búsqueda aproximada. Si necesita realizar una búsqueda aproximada, considere la posibilidad de usar la sintaxis de consulta completa de Lucene alternativa en su lugar.

Ejemplo (sintaxis simple)

En este ejemplo se muestra una consulta simple, que se distingue por "queryType": "simple" y una sintaxis válida. Aunque el tipo de consulta se establece a continuación, es el valor predeterminado y se puede omitir a menos que se revierta de un tipo alternativo. El ejemplo siguiente es una búsqueda mediante términos independientes, con el requisito de que todos los documentos coincidentes incluyan "pool".

POST https://{{service-name}}.search.windows.net/indexes/hotel-rooms-sample/docs/search?api-version=2024-07-01
{
  "queryType": "simple",
  "search": "budget hotel +pool",
  "searchMode": "all"
}

El parámetro searchMode es significativo en este ejemplo. Cada vez que los operadores booleanos están en la consulta, normalmente se debe establecer searchMode=all para asegurar que se busca la coincidencia con todos los criterios. De lo contrario, puede usar el valor predeterminado searchMode=any que favorece la coincidencia sobre la precisión.

Para ver ejemplos adicionales, consulte los ejemplos de sintaxis de consulta simple. Para más información sobre la solicitud de consultas y los parámetros, consulte la Búsqueda de documentos (API de REST).

Búsqueda de palabras clave en términos y frases

Las cadenas que se pasan al parámetro search pueden incluir términos o frases en cualquier idioma compatible, operadores booleanos, operadores de precedencia, caracteres comodín o prefijos para las consultas de tipo "comienza con", caracteres de escape y caracteres de codificación de direcciones URL. El search es opcional. Si no se especifica, la búsqueda (search=* o search=" ") devuelve los 50 documentos principales de forma arbitraria (sin clasificar).

Una búsqueda de términos es una consulta para uno o varios términos, donde cualquiera de ellos se considera una coincidencia.
Una búsqueda de frases es una frase exacta entre comillas " ". Por ejemplo, mientras que Roach Motel (sin comillas) buscaría documentos que contuvieran Roach y/o Motel en cualquier lugar y en cualquier orden, "Roach Motel" (con comillas) solo encontrará coincidencias en documentos que contengan esa frase completa junta y en ese orden (el análisis léxico sigue aplicándose).

En función de su cliente de búsqueda, es posible que quiera aplicar una marca de escape a las comillas al realizar una búsqueda de frases. Por ejemplo, en una solicitud POST, una frase de búsqueda en "Roach Motel" en el cuerpo de la solicitud podría especificarse como "\"Roach Motel\"". Si usa los SDK de Azure, el cliente de búsqueda escapa las comillas cuando serializa el texto de búsqueda. La frase de búsqueda se puede enviar como "Roach Motel".

De forma predeterminada, todas las cadenas pasadas en el parámetro search se someten a un análisis léxico. Asegúrese de que comprende el comportamiento de la tokenización del analizador que está utilizando. A menudo, cuando los resultados de la consulta son inesperados, se puede realizar un seguimiento de la manera en que se tokenizan los términos en el momento de la consulta. Puede probar la tokenización en cadenas específicas para confirmar la salida.

Cualquier entrada de texto con uno o varios términos se considera un punto inicial válido para la ejecución de consultas. Azure AI Search encontrará coincidencias en los documentos que contengan cualquiera de los términos, o todos ellos, incluidas las variaciones encontradas durante el análisis del texto.

Por muy sencillo que parezca, hay un aspecto de la ejecución de consultas en Azure AI Search que puede producir resultados inesperados, aumentando (en lugar de disminuir) los resultados de búsqueda a medida que se agregan más términos y operadores a la cadena de entrada. Que se produzca o no esta expansión realmente depende de la inclusión de un operador NOT, combinado con una configuración del parámetro searchMode, que determina cómo se interpreta NOT en términos de comportamientos de AND o OR. Para obtener más información, consulte el operador NOT en Operadores booleanos.

Operadores booleanos

Puede incrustar operadores booleanos en una cadena de consulta para mejorar la precisión de una coincidencia. En la sintaxis simple, los operadores booleanos están basados en caracteres. Recuerde que no se admiten operadores de texto, como la palabra AND.

Carácter Ejemplo Uso

+ pool + ocean Una operación AND. Por ejemplo, pool + ocean estipula que un documento debe contener ambos términos.

| pool | ocean Una operación OR busca una coincidencia cuando se encuentra cualquiera de los términos. En este ejemplo, el motor de consultas devolverá una coincidencia en los documentos que contenga pool, ocean o ambos. Como pool ocean es el operador de conjunción predeterminado, podría también dejarlo fuera, de forma que OR sea el equivalente de pool | ocean.

Carácter	Ejemplo	Uso
`+`	`pool + ocean`	Una operación `AND`. Por ejemplo, `pool + ocean` estipula que un documento debe contener ambos términos.
`\|`	`pool \| ocean`	Una operación `OR` busca una coincidencia cuando se encuentra cualquiera de los términos. En este ejemplo, el motor de consultas devolverá una coincidencia en los documentos que contenga `pool`, `ocean` o ambos. Como `pool ocean` es el operador de conjunción predeterminado, podría también dejarlo fuera, de forma que `OR` sea el equivalente de `pool \| ocean`.
`-`	`pool – ocean`	Una operación `NOT` devuelve coincidencias en documentos que excluyen el término. El parámetro `searchMode` de una solicitud de consulta controla si un término con el operador `NOT` también cuenta con `AND` o `OR` en otros términos de la consulta (suponiendo que no haya ningún operador booleano en los demás términos). Los valores válidos son `any` o `all`. `searchMode=any` aumenta la recuperación de consultas al incluirse más resultados y, de forma predeterminada, `-` se interpretará como "OR NOT". Por ejemplo, `pool - ocean` encontrará coincidencias en los documentos que contengan el término `pool` o en aquellos que no contengan el término `ocean`. `searchMode=all` aumenta la precisión de las consultas al incluirse menos resultados y, de forma predeterminada, `-` se interpretará como "AND NOT". Por ejemplo, con `searchMode=any`, la consulta `pool - ocean` coincidirá con los documentos que contienen el término "pool" y todos los documentos que no contienen el término "ocean". Este es posiblemente un comportamiento más intuitivo para el operador `-`. Por lo tanto, debe considerar el uso de `searchMode=all` en lugar de `searchMode=any` si desea optimizar las búsquedas para precisión en lugar de para recuperación, y si los usuarios utilizan con frecuencia el operador `-` en las búsquedas. Al decidir sobre una configuración de `searchMode`, tenga en cuenta los patrones de interacción del usuario para las consultas que realice en varias aplicaciones. Es más probable que los usuarios que buscan información incluyan un operador en una consulta, en lugar de sitios de comercio electrónico que tengan más estructuras de navegación integradas.

-

pool – ocean

Una operación NOT devuelve coincidencias en documentos que excluyen el término.

El parámetro searchMode de una solicitud de consulta controla si un término con el operador NOT también cuenta con AND o OR en otros términos de la consulta (suponiendo que no haya ningún operador booleano en los demás términos). Los valores válidos son any o all.

searchMode=any aumenta la recuperación de consultas al incluirse más resultados y, de forma predeterminada, - se interpretará como "OR NOT". Por ejemplo, pool - ocean encontrará coincidencias en los documentos que contengan el término pool o en aquellos que no contengan el término ocean.

searchMode=all aumenta la precisión de las consultas al incluirse menos resultados y, de forma predeterminada, - se interpretará como "AND NOT". Por ejemplo, con searchMode=any, la consulta pool - ocean coincidirá con los documentos que contienen el término "pool" y todos los documentos que no contienen el término "ocean". Este es posiblemente un comportamiento más intuitivo para el operador -. Por lo tanto, debe considerar el uso de searchMode=all en lugar de searchMode=any si desea optimizar las búsquedas para precisión en lugar de para recuperación, y si los usuarios utilizan con frecuencia el operador - en las búsquedas.

Al decidir sobre una configuración de searchMode, tenga en cuenta los patrones de interacción del usuario para las consultas que realice en varias aplicaciones. Es más probable que los usuarios que buscan información incluyan un operador en una consulta, en lugar de sitios de comercio electrónico que tengan más estructuras de navegación integradas.

Consultas de prefijo

En el caso de las consultas de tipo "empieza con", agregue un operador de sufijo (*) como marcador de posición para la última parte de un término. Una consulta de prefijo debe comenzar con al menos un carácter alfanumérico para poder agregar el operador de sufijo.

Carácter	Ejemplo	Uso
`*`	`lingui*` coincidirá con "linguistic" o "linguini".	El asterisco (`*`) representa uno o varios caracteres de longitud arbitraria, sin distinción de mayúsculas y minúsculas.

De forma similar a los filtros, una consulta de prefijo busca una coincidencia exacta. Como tal, no hay ninguna puntuación de relevancia (todos los resultados reciben una puntuación de búsqueda de 1,0). Tenga en cuenta que las consultas de prefijo pueden ser lentas, en especial si el índice es grande y el prefijo está formado por un número pequeño de caracteres. Podría funcionar más rápido una metodología alternativa, como la tokenización de n-gramas perimetrales. Los términos que usan la búsqueda de prefijos no pueden tener más de 1000 caracteres.

La sintaxis simple solo admite la coincidencia de prefijos. En cuanto a la coincidencia de sufijos o interfijos en la parte inicial o intermedia de un término, use la sintaxis de Lucene completa para la búsqueda con caracteres comodín.

Escape de los operadores de búsqueda

En la sintaxis simple, los operadores de búsqueda incluyen estos caracteres: + | " ( ) ' \

Si alguno de estos caracteres forma parte de un token en el índice, aplique el escape anteponiendo un carácter de barra diagonal inversa (\) en la consulta. Por ejemplo, supongamos que ha usado un analizador personalizado para la tokenización de todo el término y el índice contiene la cadena "Luxury+Hotel". Para obtener una coincidencia exacta en este token, inserte un carácter de escape: search=luxury\+hotel.

Con el fin de simplificar las cosas para los casos más típicos, existen dos excepciones a esta regla donde la secuencia de escape no es necesaria:

El operador NOT - necesita escaparse solamente si es el primer carácter después de un espacio en blanco. Si - aparece en el centro (por ejemplo, en 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD), puede omitir el escape.
El operador de sufijo * solo debe ser un carácter de escape si es el último carácter antes de un espacio en blanco. Si * aparece en el centro (por ejemplo, en 4*4=16), no se necesita ningún escape.

Nota:

De forma predeterminada, el analizador estándar eliminará y dividirá palabras en guiones, espacios en blanco, y comercial y otros caracteres durante el análisis léxico. Si necesita que caracteres especiales permanezcan en la cadena de consulta, es posible que necesite un analizador que los conserve en el índice. Algunas opciones incluyen analizadores de lenguaje natural de Microsoft, que conserva palabras con guiones o un analizador personalizado para patrones más complejos. Para más información, vea Términos parciales, patrones y caracteres especiales.

Codificación de caracteres reservados y no seguros en las direcciones URL

Asegúrese de que todos los caracteres reservados y no seguros estén codificados en una dirección URL. Por ejemplo, "#" es un carácter no seguro, ya que es un identificador de delimitador o fragmento en una dirección URL. El carácter debe codificarse con %23 si se usa en una dirección URL. "&" y "=" son ejemplos de caracteres reservados, ya que delimitan parámetros y especifican valores en Búsqueda de Azure AI. Para más información, consulte RFC1738: Localizadores uniformes de recursos (URL).

Los caracteres no seguros son " ` < > # % { } | \ ^ ~ [ ]. Los caracteres reservados son ; / ? : @ = + &.

Caracteres especiales

Los caracteres especiales pueden ir desde los símbolos de moneda como “$” o “€” hasta los emojis. Muchos analizadores, incluido el analizador estándar predeterminado, excluirán los caracteres especiales durante la indexación, lo que significa que no se representarán en el índice.

Si necesita representar los caracteres especiales, puede asignar un analizador que los conserve:

El analizador de espacios en blanco considera como token cualquier secuencia de caracteres separada por espacios en blanco (por lo que el emoji "❤" se consideraría un token).
Un analizador de idioma, como el analizador de inglés de Microsoft (en.microsoft), incluiría la cadena “$” o "€" como un token.

Para la confirmación, puede probar un analizador para ver qué tokens se generan para una cadena determinada. Como podría esperar, es posible que no obtenga una tokenización completa de un único analizador. Una solución consiste en crear varios campos que contengan el mismo contenido, pero con diferentes asignaciones de analizador (por ejemplo, description_en, description_fr, etc. para los analizadores de idioma).

Al usar caracteres Unicode, asegúrese de que los símbolos se escapen correctamente en la dirección URL de la consulta (por ejemplo, para "❤" usaría la secuencia de escape %E2%9D%A4+). Algunos clientes web realizan esta traducción automáticamente.

Precedencia (agrupación)

Puede usar paréntesis para crear subconsultas, incluidos los operadores dentro de la instrucción entre paréntesis. Por ejemplo, motel+(wifi|luxury) buscará los documentos que contengan el término "motel" y "wifi" o "luxury" (o ambos).

Límites de tamaño de las consultas

Si la aplicación genera consultas de búsqueda mediante programación, se recomienda diseñarla de manera que no genere consultas de tamaño ilimitado.

En cuanto al operador GET, la longitud de la dirección URL no puede superar los 8 KB.
En el caso de POST (y cualquier otra solicitud), donde el cuerpo de la solicitud incluya search y otros parámetros como filter y orderby, el tamaño máximo es de 16 MB. Entre los límites adicionales se incluyen:
- La longitud máxima de la cláusula de búsqueda es de 100 000 caracteres.
- El número máximo de cláusulas en search (expresiones separadas por AND u OR) es 1024.
- El tamaño máximo del término de búsqueda es de 1000 caracteres para la búsqueda de prefijos.
- También hay un límite de aproximadamente 32 KB en el tamaño de cualquier término individual en una consulta.

Para más información sobre los límites de las consultas, consulte Límites de solicitud de API.

Pasos siguientes

Si va a crear consultas mediante programación, consulte el artículo Búsqueda de texto completo en Azure AI Search para conocer las fases del procesamiento de consultas y las implicaciones del análisis de texto.

Asimismo, también puede revisar los siguientes artículos para obtener más información sobre la creación de consultas:

Compartir vía