Sintaxis de consulta de Lucene en Búsqueda de Azure AI

Al crear consultas en Búsqueda de Azure AI, puede optar por la sintaxis completa del analizador de consultas Lucene para formularios de consulta especializados: carácter comodín, búsqueda aproximada, búsqueda por proximidad y expresiones regulares. Gran parte de la sintaxis del analizador de consultas Lucene se implementa de manera intacta en Búsqueda de Azure AI, a excepción de las búsquedas de rango, que se construyen mediante expresiones $filter.

Para usar la sintaxis completa de Lucene, establezca el valor de queryType en full y pase una expresión de consulta con un patrón de caracteres comodín, una búsqueda aproximada o uno de los demás formularios de consulta que admite la sintaxis completa. En REST, se proporcionan expresiones de consulta en el parámetro search de una solicitud de búsqueda de documentos (API REST).

Ejemplo (sintaxis completa)

En el ejemplo siguiente se muestra una solicitud de búsqueda construida con la sintaxis completa. En este ejemplo concreto se muestra la búsqueda por campos y la optimización de frases. Esta consulta busca hoteles en los que el campo de la categoría contenga el término budget. Los documentos que contienen la frase "recently renovated" reciben una ponderación adicional y podrían obtener una clasificación superior como resultado del valor de refuerzo de la frase (3).

POST /indexes/hotels-sample/docs/search?api-version=2026-04-01
{
  "queryType": "full",
  "search": "category:budget AND \"recently renovated\"^3",
  "searchMode": "all"
}

Aunque no es específico de ningún tipo de consulta, el parámetro searchMode es relevante en este ejemplo. Cada vez que haya operadores en la consulta, normalmente debe establecer searchMode=all para asegurarse de que se busca la coincidencia con todos los criterios.

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

Aspectos básicos de la sintaxis

Los siguientes fundamentos de sintaxis se aplican a todas las consultas que usan la sintaxis de Lucene.

Evaluación de operadores en contexto

La selección de ubicación determina si un símbolo se interpreta como un operador o como otro carácter de una cadena.

Por ejemplo, en la sintaxis completa de Lucene, se usa la tilde (~) para la búsqueda aproximada y la búsqueda por proximidad. Cuando se coloca detrás de una frase entre comillas, ~ invoca la búsqueda por proximidad. Cuando se coloca al final de un término, ~ invoca la búsqueda aproximada.

Dentro de un término, como business~analyst, el carácter no se evalúa como un operador. En este caso, suponiendo que la consulta es de un término o una frase, la búsqueda de texto completo con análisis léxico elimina la tilde ~ y divide el término business~analyst en dos: business o analyst.

El ejemplo anterior es la tilde (~), pero se aplica el mismo principio a todos los operadores.

Escape de caracteres especiales

Para usar cualquiera de los operadores de búsqueda como parte del texto de búsqueda, escape el carácter poniéndole el prefijo de sola barra invertida (\). Por ejemplo, para realizar una búsqueda con caracteres comodín en https://, donde :// forma parte de la cadena de consulta, debe especificar search=https\:\/\/*. Del mismo modo, un patrón de número de teléfono con escape podría ser similar a este \+1 \(800\) 642\-7676.

Los caracteres especiales que requieren escape son los siguientes:
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

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 obtener más información, consulte RFC1738: Localizadores uniformes de recursos (URL).

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

Operadores booleanos

Puede incrustar operadores booleanos en una cadena de consulta para mejorar la precisión de una coincidencia. La sintaxis completa admite operadores de texto además de operadores de caracteres. Especifique siempre operadores booleanos de texto (AND, OR, NOT) todo en mayúsculas.

¹ Las operaciones OR no admiten el carácter |.

Operador booleano NOT

• En la sintaxis simple, las consultas con negación siempre tienen un carácter comodín agregado automáticamente. Por ejemplo, la consulta -luxury se expande automáticamente a -luxury *.
• En la sintaxis completa, las consultas con negación no se pueden combinar con un carácter comodín. Por ejemplo, no se permiten las consultas -luxury *.
• En la sintaxis completa, no se permiten consultas con una única negación. Por ejemplo, no se permite la consulta -luxury.
• En la sintaxis completa, las negaciones se comportarán como si siempre llevasen el operador AND en la consulta, independientemente del modo de búsqueda.
  • Por ejemplo, la consulta de sintaxis completa wifi -luxury en sintaxis completa solo captura documentos que contienen el término wifi y, a continuación, aplica la negación -luxury a esos documentos.
• Si desea usar negaciones para buscar en todos los documentos del índice, se recomienda la sintaxis simple con el modo de búsqueda any.
• Si desea usar negaciones para buscar en un subconjunto de documentos del índice, se recomienda la sintaxis completa o la sintaxis simple con el modo de búsqueda todo.

Búsqueda por campos

Puede definir una operación de búsqueda clasificada por campos con la sintaxis fieldName:searchExpression, donde la expresión de búsqueda puede ser una sola palabra, una frase o una expresión más compleja entre paréntesis, opcionalmente con operadores booleanos. A continuación se muestran algunos ejemplos:

• genre:jazz NOT history

• artists:("Miles Davis" "John Coltrane")

Asegúrese de colocar varias cadenas entre comillas si quiere que las dos cadenas se evalúen como una sola entidad, como en este caso donde se buscan dos ciudades distintas en el campo artists.

El campo especificado en fieldName:searchExpression debe ser un campo searchable. Consulte Create Index (Crear índice) para más información sobre cómo se usan los atributos de índice en las definiciones de campo.

Búsqueda aproximada

Una búsqueda aproximada busca coincidencias en términos que tienen una construcción similar, expandiendo un término hasta el máximo de 50 términos que cumplen los criterios de distancia de dos o menos. Para más información, vea Búsqueda aproximada.

Para realizar una búsqueda aproximada, use el símbolo ~ de tilde al final de una sola palabra con un parámetro opcional, un número entre 0 y 2 (predeterminado), que especifica la distancia de edición. Por ejemplo, blue~ o blue~1 devolverían blue, blues y glue.

La búsqueda aproximada solo se puede aplicar a términos, no a frases entre comillas, pero se puede anexar la tilde a cada término individualmente en un nombre de varias partes o frase. Por ejemplo, Unviersty~ of~ Wshington~ solo consideraría como coincidencia University of Washington.

Búsqueda por proximidad

Las búsquedas de proximidad se utilizan para buscar términos que están cerca entre sí en un documento. Inserte un símbolo ~ de tilde al final de una frase seguido del número de palabras que crean el límite de proximidad. Por ejemplo, "hotel airport"~5 encuentra los términos hotel y airport con una distancia de cinco palabras entre sí en un documento.

Refuerzo de términos

Piense en la búsqueda como dos pasos. En primer lugar, Búsqueda de Azure AI busca documentos coincidentes. Después, clasifica esas coincidencias. La potenciación de términos afecta solo al segundo paso: puede hacer que los documentos que coincidan con una parte de tu consulta aparezcan más arriba en los resultados.

La mejora de términos difiere de un perfil de puntuación. Un aumento favorece una palabra, frase o grupo en la consulta actual. Un perfil de puntuación favorece campos u otro contenido de índice según las reglas definidas en el índice.

Alcance de mejora

Escriba un símbolo de intercalación (^) y un número positivo inmediatamente después de la parte de la consulta que desea favorecer. Por ejemplo, tax^2 puede situar los documentos que contienen tax por encima de los documentos que solo coinciden con un término sin refuerzo. El valor de aumento predeterminado es 1. También puede usar un valor entre 0 y 1, como 0.2, para dar menos peso a una coincidencia.

La puntuación indica qué palabras afecta cada instrucción:

• Un nombre de campo más dos puntos, denominado prefijo de campo, aparece antes de una palabra, una frase entre comillas o un grupo entre paréntesis. Por ejemplo, content: indica a Búsqueda de Azure AI que busque en el content campo .
• Un aumento, como ^2, aparece después de una palabra, una frase entre comillas o un grupo entre paréntesis. Indica a Búsqueda de Azure AI qué debe favorecer al ordenar las coincidencias.

En la tabla siguiente se usa el valor predeterminado searchMode=any, donde un espacio entre palabras funciona como OR.

Con searchMode=all, la consulta deferred tax^2 requiere que ambas palabras coincidan. El aumento todavía se aplica solo a tax. Para que coincida con una u otra palabra, escriba en cambio deferred OR tax^2.

Coloque el cursor después de la comilla de cierre o del paréntesis de cierre cuando desee aplicar el realce a toda la frase o a todo el grupo. Los paréntesis no crean una frase. Use comillas cuando las palabras deben estar junto entre sí y en un orden específico.

Aumento y ámbito de campo

Un nombre de campo seguido de dos puntos limita dónde busca Búsqueda de Azure AI. Un aumento cambia la forma en que Búsqueda de Azure AI clasifica una coincidencia. Puede usar ambos en la misma consulta.

Por ejemplo, si searchFields se establece en title, la primera consulta busca deferred en content y tax en title. Las comillas y los paréntesis en las otras consultas hacen que ambas palabras permanezcan en content.

Efecto de un analizador en consultas ampliadas

En el caso de palabras, frases y grupos de palabras normales, la mejora no omite el análisis de texto. Antes de comparar, Búsqueda de Azure AI sigue procesando el texto de la consulta mediante el analizador de cada campo. Como resultado, el mismo texto ampliado podría coincidir de forma diferente en los campos que usan analizadores diferentes.

Una frase o grupo con un prefijo de campo usa el analizador de ese campo. El texto sin un prefijo de campo usa el analizador para cada campo que se busca. Por ejemplo, un analizador que convierte el texto a minúsculas puede hacer coincidir "DEFERRED TAX"^2 con términos indexados en minúsculas.

Otros formularios de consulta, como caracteres comodín, expresiones regulares y consultas aproximadas, usan reglas de análisis diferentes. Agregar una mejora no cambia esas reglas. Para obtener más información, vea Fase 2: Análisis léxico.

Búsqueda mediante expresiones regulares

Una búsqueda de expresión regular encuentra una coincidencia en función de los patrones que son válidos en Apache Lucene, como se documenta en la clase RegExp.

En Búsqueda de Azure AI, una expresión regular:

• Se incluye entre barras diagonales /
• Solo minúsculas

Por ejemplo, para encontrar documentos que contengan motel u hotel, especifique /[mh]otel/. Las búsquedas mediante expresiones regulares se comparan con las palabras individuales.

Algunas herramientas y lenguajes imponen requisitos de caracteres de escape adicionales más allá de las reglas de escape impuestas por Búsqueda de Azure AI. En el caso de JSON, las cadenas que incluyen una barra diagonal tienen un carácter de escape con una barra diagonal inversa: microsoft.com/azure/ se convierte en search=/.*microsoft.com\/azure\/.*/, donde search=/.* <string-placeholder>.*/ configura la expresión regular y microsoft.com\/azure\/ es la cadena con una barra diagonal de escape.

Dos símbolos comunes en las consultas regex son . y *. Una expresión . encontrará coincidencia con cualquier carácter único y una expresión * encontrará coincidencia con el carácter anterior cero o más veces. Por ejemplo, /be./ coincide con los términos bee y bet, mientras que /be*/ coincidiría con be, bee y beee, pero no con bet. Juntos, .* le permiten encontrar la coincidencia con cualquier serie de caracteres, por lo que /be.*/ encontrará coincidencia con cualquier término que empiece por be, como better.

Si recibe errores de sintaxis en la expresión regular, revise las reglas de escape de los caracteres especiales. También puede probar otro cliente para confirmar si el problema es específico de la herramienta.

Búsqueda con caracteres comodín

Puede usar la sintaxis generalmente reconocida para búsquedas con caracteres comodín únicas (*) o múltiples (?). La sintaxis de Lucene completa admite la coincidencia de prefijos e infijos. Use la sintaxis de expresión regular para la coincidencia de sufijos.

Tenga en cuenta que el Analizador de consultas de Lucene admite el uso de estos símbolos con un único término y no una frase.

Los operadores se pueden combinar para formar una sola expresión. Por ejemplo, 980?2* coincide con 98072-1222 y 98052-1234, donde ? coincide con un carácter único (obligatorio) y * coincide con caracteres de una longitud arbitraria que siguen.

La coincidencia de sufijos requiere los delimitadores / de barra diagonal de las expresiones regulares. Por lo general, no se puede usar un símbolo * o ? como primer carácter de un término sin la expresión /. También es importante tener en cuenta que * se comporta de forma diferente cuando se usa fuera de las consultas de expresión regular. Fuera de los delimitadores / de barra diagonal de expresión regular, * es un carácter comodín y coincide con cualquier serie de caracteres de forma similar a .* en una expresión regular. Por ejemplo, search=/non.*al/ produce el mismo conjunto de resultados que search=non*al.

Efecto de un analizador en las consultas con caracteres comodín

Durante el análisis de consultas, las consultas que se formulan como prefijo, sufijo, carácter comodín o expresiones regulares se pasan tal cual al árbol de consultas y se omite el análisis léxico. Solo se encontrarán coincidencias si el índice contiene las cadenas en el formato que especifica la consulta. En la mayoría de los casos, durante la indexación necesita un analizador que preserve la integridad de las cadenas para que la coincidencia parcial de patrones y términos sea correcta. Para obtener más información, consulte Búsqueda de términos parciales en las consultas de Búsqueda de Azure AI.

Piense en una situación en la que quiere que la consulta de búsqueda terminal* devuelva resultados que contengan términos como terminate, termination y terminates.

Si usara el analizador en.lucene (Inglés Lucene), aplicaría una lematización agresiva de cada término. Por ejemplo, terminate, termination y terminates se tokenizarán en el token termi del índice. Por otra parte, los términos de las consultas que usan caracteres comodín o búsqueda aproximada no se analizan, por lo que no habrá resultados que coincidan con la consulta terminat*.

Además, los analizadores de Microsoft (en este caso, en.microsoft) son un poco más avanzados y usan lemas en lugar de lexemas. Esto significa que todos los tokens generados deben ser palabras en inglés válidas. Por ejemplo, terminate, terminates y termination se mantendrán en su totalidad en el índice, y esta sería una opción preferible para escenarios que dependen mucho de los caracteres comodín y la búsqueda aproximada.

Puntuación de consultas con carácter comodín y expresión regular

Búsqueda de Azure AI usa la puntuación basada en la frecuencia (BM25) para las consultas de texto. Sin embargo, para consultas con caracteres comodín y expresiones regulares donde el ámbito de los términos puede ser posiblemente amplio, se omite el factor de frecuencia para evitar que la clasificación se desvíe hacia las coincidencias de términos menos frecuentes. Todas las coincidencias se tratan por igual en las búsquedas con caracteres comodín y expresiones regulares.

Caracteres especiales

En algunas circunstancias, es posible que quiera buscar un carácter especial, como el emoji "❤" o el signo "€". En ese caso, asegúrese de que el analizador que usa no filtre esos caracteres. Recuerde que el analizador estándar omite muchos caracteres especiales y los excluye del índice.

Aquellos analizadores que dividen en tokens los caracteres especiales incluyen el analizador de espacios en blanco, que tiene en cuenta todas las secuencias de caracteres separadas por espacios en blanco como tokens (de modo que la cadena ❤ se consideraría un token). Asimismo, un analizador de idioma como el analizador de inglés de Microsoft ("en.microsoft") debe incluir la cadena "€" como un token. Puede probar un analizador para ver qué tokens genera para una consulta determinada.

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

Precedencia (agrupación)

Use paréntesis para controlar qué partes de una consulta se evalúan juntas. Por ejemplo, motel AND (wifi OR luxury) requiere motel y al menos uno de los términos dentro de los paréntesis: wifi o luxury.

Coloque un prefijo de campo antes de un grupo entre paréntesis para buscar en ese grupo completo en un campo. Por ejemplo, hotelAmenities:(wifi OR pool) busca wifi o pool solo en el hotelAmenities campo .

Los paréntesis controlan cómo AND y OR funcionan juntos. No requieren que las palabras aparezcan entre sí ni en un orden específico. Use comillas para ese comportamiento. Para aplicar el modificador a un grupo, coloque el cursor después del paréntesis de cierre, como en hotelAmenities:(wifi OR pool)^2. Para obtener más información, consulte Ámbito de aumento.

Límites de tamaño de las consultas

Búsqueda de Azure AI impone límites en el tamaño y la composición de las consultas porque las consultas sin límites pueden desestabilizar el servicio de búsqueda. Hay límites en el tamaño y la composición de la consulta (el número de cláusulas). También existen límites para la longitud de la búsqueda de prefijos y para la complejidad de la búsqueda con expresión regular y la búsqueda con caracteres comodín. 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.

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

Consulte también

• Ejemplos de consulta para una búsqueda simple
• Ejemplos de consulta para una búsqueda completa de Lucene
• Documentos de búsqueda
• Sintaxis de expresiones de OData para filtros y ordenación
• Sintaxis de consulta simple en Búsqueda de Azure AI