Sintaxis de consulta simple en Búsqueda de Azure AI

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. El analizador de consultas simples es el valor predeterminado. Trata los casos de uso comunes e intenta interpretar una solicitud aunque no esté perfectamente compuesta. 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 de consultas se aplica a las expresiones de consulta pasadas en el parámetro search de una solicitud de consulta, sin confundirse con la sintaxis de OData, que tiene su propia sintaxis y reglas para las expresiones filter y orderby en la misma solicitud.

Aunque el analizador simple se basa en la clase Apache Lucene Simple Query Parser, su implementación en Búsqueda de Azure AI excluye la búsqueda aproximada. Si necesita una búsqueda aproximada, considere la sintaxis alternativa de consulta completa de Lucene en su lugar.

Ejemplo (sintaxis simple)

En este ejemplo se muestra una consulta simple, distinguido por "queryType": "simple" y 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 en términos independientes, con un requisito de que todos los documentos coincidentes incluyan "pool".

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

El searchMode parámetro es relevante en este ejemplo. Siempre que los operadores booleanos estén en la consulta, generalmente debe establecerse searchMode=all para asegurarse de que se cumplen todos los criterios. De lo contrario, puede usar el valor predeterminado searchMode=any que da prioridad a la recuperación en lugar de a la precisión.

Para obtener más ejemplos, consulte Ejemplos de sintaxis de consulta simple. Para más información sobre la solicitud de consulta y los parámetros, consulte Buscar documentos (API REST).

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

Las cadenas que se pasan al search parámetro pueden incluir términos o frases en cualquier lenguaje admitido, operadores booleanos, operadores de precedencia, caracteres comodín o prefijo para consultas "comienzan con", caracteres de escape y caracteres de codificación url. El search parámetro es opcional. Sin especificar, la búsqueda (search=* o search=" ") devuelve los 50 documentos principales en orden arbitrario (sin clasificar).

  • Una búsqueda de términos es una consulta de uno o varios términos, donde cualquiera de los términos se considera una coincidencia.

  • Una búsqueda de frases es una frase exacta entre comillas " ". Por ejemplo, Roach Motel (sin comillas) buscaría documentos que contengan Roach y/o Motel en cualquier parte y en cualquier orden, mientras que "Roach Motel" (con comillas) solo mostrará documentos que contengan esa frase completa junta y en ese orden (el análisis léxico todavía se aplica).

Según el cliente de búsqueda, es posible que tenga que escapar las comillas en una búsqueda de frases. Por ejemplo, en una solicitud POST, una búsqueda de frases en "Roach Motel" en el cuerpo de la solicitud podría especificarse como "\"Roach Motel\"". Si utiliza los SDKs 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 search parámetro se someten al análisis léxico. Asegúrese de comprender el comportamiento de tokenización del analizador que está usando. A menudo, cuando los resultados de la consulta son inesperados, se puede rastrear el motivo de cómo 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 de partida válido para la ejecución de consultas. Búsqueda de Azure AI coincidirá con documentos que contengan cualquiera o todos los términos, 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 Búsqueda de Azure AI que podría producir resultados inesperados, aumentando los resultados de búsqueda en lugar de reducirlos a medida que se agregan más términos y operadores a la cadena de entrada. Si esta expansión realmente se produce depende de la inclusión de un operador NOT, combinado con una searchMode configuración de parámetro que determina cómo NOT se interpreta en términos de los comportamientos de AND o OR. Para obtener más información, consulte el NOT operador en Operadores booleanos.

Operadores booleanos

Puede insertar 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. No se admiten operadores de texto, como la palabra AND.

Carácter Ejemplo Uso
+ pool + ocean Una AND operación. Por ejemplo, pool + ocean estipula que un documento debe contener ambos términos.
| pool | ocean Una OR operación busca una coincidencia cuando se encuentra cualquiera de los términos. En el ejemplo, el motor de consultas devolverá una coincidencia en los documentos que contienen bien pool, bien ocean, o ambos. Dado OR que es el operador de combinación predeterminado, también puede dejarlo fuera, de modo que pool ocean sea el equivalente de pool | ocean.
- pool – ocean Una NOT operación 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 se AND o OR con otros términos en la consulta (asumiendo que no haya operadores booleanos en los demás términos). Los valores válidos incluyen any o all.

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

searchMode=all aumenta la precisión de las consultas mediante la inclusión de 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". Esto es posiblemente un comportamiento más intuitivo para el - operador. Por lo tanto, debe considerar la posibilidad de usar searchMode=all en lugar de searchMode=any si desea optimizar las búsquedas de precisión en lugar de la recuperación , y los usuarios suelen usar el - operador en las búsquedas.

Al decidir una searchMode configuración, tenga en cuenta los patrones de interacción del usuario para las consultas 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 estructuras de navegación más integradas.

Consultas de prefijo

Para las consultas "comienza con", agregue un operador de sufijo (*) como marcador para el resto de un término. Una consulta de prefijo debe comenzar con al menos un carácter de texto sin formato 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 cualquier longitud, ignorando mayúsculas y minúsculas.

De forma similar a los filtros, una consulta de prefijo busca una coincidencia exacta. Por lo tanto, 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, especialmente si el índice es grande y el prefijo consta de un pequeño número de caracteres. Una metodología alternativa, como la tokenización perimetral de n-gramas, puede funcionar más rápido. 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. Para el sufijo o el infijo que coincidan con el final o medio de un término, use la sintaxis completa de Lucene para la búsqueda con caracteres comodín.

Operadores de búsqueda de escape

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, pónguelo mediante el prefijo con una sola barra diagonal inversa (\) en la consulta. Por ejemplo, supongamos que usó un analizador personalizado para la tokenización de términos completos 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.

Para simplificar los casos más típicos, hay dos excepciones a esta regla en las que no se necesita el escape:

  • El operador - NOT solo debe escaparse si es el primer carácter después de un espacio en blanco. - Si aparece en el medio (por ejemplo, en 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD), puede omitir el escape.

  • El operador * de sufijo solo debe escaparse si es el último carácter antes de un espacio en blanco. * Si aparece en el medio (por ejemplo, en 4*4=16), no se necesita ningún escape.

Nota

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

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

Asegúrese de que todos los caracteres no seguros y reservados están codificados en una dirección URL. Por ejemplo, "#" es un carácter no seguro porque es un identificador de fragmento o delimitador en una dirección URL. El carácter se debe codificar en %23 si se usa en una dirección URL. & ' y '=' son ejemplos de caracteres reservados a medida que delimitan los parámetros y especifican valores en Búsqueda de Azure AI. Para obtener 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 oscilar entre símbolos de moneda como '$' o '€', a emojis. Muchos analizadores, incluido el analizador estándar predeterminado, excluirán caracteres especiales durante la indexación, lo que significa que no se representarán en el índice.

Si necesita una representación de caracteres especial, puede asignar un analizador que los conserve:

  • El analizador de espacios en blanco considera cualquier secuencia de caracteres separada por espacios en blanco como tokens (por lo que el emoji "❤" se consideraría un token).

  • Un analizador language, como el analizador en inglés de Microsoft (en.microsoft), tomaría la cadena "$" o "€" como token.

Para obtener confirmación, puede probar un analizador para ver qué tokens se generan para una cadena determinada. Como cabrí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 lenguaje).

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 "❤" se 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, incluyendo operadores dentro de la declaración entre paréntesis. Por ejemplo, motel+(wifi|luxury) buscará documentos que contengan el término "motel" y "wifi" o "lujo" (o ambos).

Límites de tamaño de consulta

Si su aplicación genera consultas de búsqueda programáticamente, se recomienda diseñarla de forma que no genere consultas de tamaño ilimitado.

  • Para GET, la longitud de la dirección URL no puede superar los 8 KB.

  • Para POST (y cualquier otra solicitud), donde el cuerpo de la solicitud incluye 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 de search (expresiones separadas por AND o 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 de una consulta.

Para más información sobre los límites de consulta, consulte Límites de solicitudes de API.

Pasos siguientes

Si va a construir consultas programáticamente, revise Búsqueda de texto completo en Búsqueda de Azure AI para comprender las etapas del procesamiento de consultas y las implicaciones del análisis de texto.

También puede revisar los siguientes artículos para obtener más información sobre la construcción de consultas:

  • Last updated on