Sintaxis de consulta de Lucene en Azure AI Search

Al crear consultas en Azure AI Search, 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 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 en campo y la mejora de términos. Esta consulta busca hoteles en los que el campo de la categoría contenga el término budget. Los documentos que contienen la expresión "recently renovated" tienen una clasificación más alta como resultado del valor de impulso del término (3).

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-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).

Fundamentos de 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:
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

Nota:

Aunque el escape mantiene juntos los tokens, el análisis léxico durante la indexación puede eliminarlos. Por ejemplo, el analizador de Lucene estándar dividirá palabras con guiones, espacios en blanco y otros caracteres. Si necesita caracteres especiales 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 Azure AI Search. 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.

Operador de texto	Carácter	Ejemplo	Uso
y	+	wifi AND luxury	Especifica los términos que debe contener una coincidencia. En el ejemplo, el motor de consultas busca documentos que contengan wifi y luxury. El carácter más (+) también se puede usar directamente delante de un término para hacer que sea obligatorio. Por ejemplo, +wifi +luxury estipula que ambos términos deben aparecer en algún lugar en el campo de un documento.
O BIEN	(none) 1	wifi OR luxury	Busca una coincidencia cuando se encuentra cualquiera de los términos. En este ejemplo, el motor de consultas devuelve una coincidencia en los documentos que contengan wifi, luxury o ambos. Como OR es el operador de conjunción predeterminado, podría también dejarlo fuera, de forma que wifi luxury sea el equivalente de wifi OR luxury.
NOT	!, -	wifi –luxury	Devuelve una coincidencia en los documentos que excluyen el término. Por ejemplo, wifi –luxury busca documentos que contengan el término wifi, pero que no tengan luxury.

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

Operador booleano NOT

Importante

El operador NOT (NOT, ! o -) se comporta de forma diferente en la sintaxis completa que en la sintaxis simple.

• 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.

Tipo de consulta	Modo de búsqueda	Consulta de ejemplo	Behavior
Sencillo	cualquiera	wifi -luxury	Devuelve todos los documentos del índice. Los documentos con el término "wifi" o los documentos que no tienen el término "luxury" se clasifican por encima de otros documentos. La consulta se expande a wifi OR -luxury OR *.
Simple	all	wifi -luxury	Devuelve solo los documentos del índice que contienen el término "wifi" y no contienen el término "luxury". La consulta se expande a wifi AND -luxury AND *.
Completo	cualquiera	wifi -luxury	Devuelve solo los documentos del índice que contienen el término "wifi" y, a continuación, se quitan de los resultados los documentos que contienen el término "luxury".
Completo	all	wifi -luxury	Devuelve solo los documentos del índice que contienen el término "wifi" y, a continuación, se quitan de los resultados los documentos que contienen el término "luxury".

Búsqueda clasificada 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.

Nota:

Al usar expresiones de búsqueda clasificada por campos, no es necesario usar el parámetro searchFields porque cada expresión de búsqueda clasificada por campos tiene un nombre de campo especificado explícitamente. Pero tenga en cuenta que todavía puede usar el parámetro searchFields si quiere ejecutar una consulta donde algunas partes se limitan a un campo específico y el resto se podría aplicar a varios campos. Por ejemplo, la consulta search=genre:jazz NOT history&searchFields=description coincidiría con jazz únicamente con el campo genre, aunque coincidiría con NOT history con el campo description. El nombre de campo proporcionado en fieldName:searchExpression siempre tiene prioridad sobre el parámetro searchFields. Por eso en este ejemplo no es necesario incluir genre en el parámetro searchFields.

Búsqueda borrosa

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

La "priorización de términos" hace referencia a la clasificación de un documento superior si contiene el término prioritario con respecto a los documentos que no lo contienen. Esto difiere de los perfiles de puntuación en los que aumentan ciertos campos, en lugar de términos específicos.

En el siguiente ejemplo se muestran las diferencias. Imagine que hay un perfil de puntuación que impulsa las coincidencias en un campo determinado, como genre en el ejemplo musicstoreindex. La priorización de términos podría utilizarse para dar mayor prioridad a determinados términos de búsqueda frente a otros. Por ejemplo, rock^2 electronic impulsa los documentos que contengan los términos de búsqueda en el campo de género frente a otros campos que permitan búsquedas en el índice. Además, los documentos que contienen el término de búsqueda rock tienen una clasificación mayor que los del término de búsqueda electronic como resultado del valor de impulso de términos (2).

Para impulsar un término, use el símbolo de intercalación, ^, con un factor de impulso (un número) al final del término que está buscando. También puede impulsar frases. Cuanto mayor sea el factor de impulso, más relevante será el término en relación con otros términos de búsqueda. Por defecto, el factor de impulso es 1. Aunque el factor de impulso debe ser positivo, puede ser inferior a 1 (por ejemplo, 0,20).

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 Azure AI Search, una expresión regular se encierra entre barras diagonales /.

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 comodines

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.

Tipo de afijo	Descripción y ejemplos
prefix	El fragmento del término viene antes que * o ?. Por ejemplo, la expresión de consulta search=alpha* devuelve alphanumeric o alphabetical. La coincidencia de prefijos es compatible tanto con la sintaxis simple como con la completa.
sufijo	El fragmento del término viene después de * o ?, con una barra diagonal para delimitar la construcción. Por ejemplo, search=/.*numeric/ devuelve alphanumeric.
infijo	Los fragmentos del término incluyen * o ?. Por ejemplo, search=non*al devuelve non-numerical y nonsensical.

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.

Nota:

Como norma general, la coincidencia de patrones es lenta, por lo que es posible que desee explorar métodos alternativos, como la tokenización de n-gramas perimetrales que crea tokens para las secuencias de caracteres de un término. Con la tokenización de n-gramas, el índice será mayor, pero las consultas se pueden ejecutar más rápidamente, en función de la construcción del patrón y la longitud de las cadenas que se van a indexar. Para más información, consulte Búsqueda de términos parciales y patrones con caracteres especiales.

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 Azure AI Search.

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

Azure AI Search 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)

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

La agrupación de campos es parecida pero establece el ámbito de la agrupación en un único campo. Por ejemplo, hotelAmenities:(gym+(wifi|pool)) busca en el campo hotelAmenities coincidencias con gym y wifi, o gym y pool.

Límites de tamaño de la consulta

Azure AI Search 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
• Buscar en documentos
• OData expression syntax for filters and sorting (Sintaxis de expresiones de OData para filtros y ordenación)
• Sintaxis de consulta simple en Azure AI Search