Sintassi di query Lucene in Azure AI Search

Quando si creano query in Azure AI Search, è possibile scegliere la sintassi parser di query Lucene per moduli di query specializzati, ad esempio caratteri jolly, ricerca fuzzy, ricerca per prossimità, espressioni regolari. La maggior parte della sintassi del parser di query Lucene viene implementata in Azure AI Search senza essere modificata, ad eccezione delle ricerche basate su intervalli che vengono create tramite le espressioni $filter.

Per usare la sintassi Lucene completa, impostare queryType su full e passare un'espressione di query basata su caratteri jolly, ricerca fuzzy o una delle altre forme di query supportate dalla sintassi completa. In REST le espressioni di query vengono fornite nel parametro search di una richiesta Cerca documenti (API REST).

Esempio (sintassi completa)

L'esempio seguente è una richiesta di ricerca costruita usando la sintassi completa. Questo particolare esempio mostra la ricerca in campo e l'aumento di priorità dei termini. Cerca gli hotel in cui il campo categoria contiene il termine budget. I documenti contenenti la frase "recently renovated" avranno una posizione superiore nella classifica, come risultato del valore di aumento di priorità di un termine (3).

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

Anche se non è specifico di alcun tipo di query, il parametro searchMode è rilevante in questo esempio. Quando nella query sono presenti operatori, è in genere consigliabile impostare searchMode=all per assicurarsi che venga trovata una corrispondenza per tutti i criteri.

Per altri esempi, vedere Esempi di sintassi di query Lucene. Per informazioni dettagliate sulla richiesta di query e sui parametri, incluso searchMode, vedere Cerca documenti (API REST).

Nozioni fondamentali sulla sintassi

Le nozioni fondamentali seguenti sulla sintassi si applicano a tutte le query che usano la sintassi Lucene.

Valutazione degli operatori nel contesto

Il posizionamento determina se un simbolo viene interpretato come operatore o semplicemente come un altro carattere in una stringa.

Nella sintassi Lucene completa, ad esempio, la tilde (~) viene usata sia per la ricerca fuzzy che per la ricerca per prossimità. Quando viene inserita dopo una frase tra virgolette, ~ richiama la ricerca per prossimità. Quando viene inserita alla fine di un termine, ~ richiama la ricerca fuzzy.

All'interno di un termine, ad esempio business~analyst, il carattere non viene valutato come operatore. In questo caso, supponendo che la query sia relativa a un termine o a una frase, la ricerca full-text con l'analisi lessicale elimina il carattere ~ e suddivide il termine business~analyst in due: business OR analyst.

L'esempio precedente è relativo alla tilde (~), ma lo stesso principio si applica a ogni operatore.

Escape dei caratteri speciali

Per usare uno degli operatori di ricerca come parte del testo di ricerca, eseguire l'escape del carattere anteponendolo a una singola barra rovesciata (\). Ad esempio, per una ricerca con caratteri jolly in https://, dove :// fa parte della stringa di query, è necessario specificare search=https\:\/\/*. Analogamente, un modello di numero di telefono preceduto da escape potrebbe essere simile a \+1 \(800\) 642\-7676.

I caratteri speciali che devono essere preceduti da un carattere di escape includono i seguenti:
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

Codifica dei caratteri riservati e non sicuri negli URL

Assicurarsi che tutti i caratteri riservati e non sicuri siano codificati in un URL. #, ad esempio, è un carattere non sicuro perché è un identificatore di frammento/ancoraggio in un URL. Il carattere deve essere codificato al %23, se usato in un URL. & e = sono esempi di caratteri riservati perché delimitano i parametri e specificano i valori in Azure AI Search. Per altri dettagli, vedere RFC1738: Uniform Resource Locators (URL).

I caratteri non sicuri sono " ` < > # % { } | \ ^ ~ [ ]. I caratteri riservati sono ; / ? : @ = + &.

Operatori booleani

È possibile incorporare operatori booleani in una stringa di query per migliorare la precisione di una corrispondenza. La sintassi completa supporta operatori di testo oltre agli operatori di caratteri. Specificare sempre gli operatori booleani di testo (AND, OR, NOT) in lettere tutte maiuscole.

¹ Il carattere | non è supportato per le operazioni OR.

Operatore booleano NOT

• Nella sintassi semplice viene sempre aggiunto un carattere jolly alle query con negazione. Ad esempio, la query -luxury viene espansa automaticamente in -luxury *.
• Nella sintassi completa le query con negazione non possono essere combinate con un carattere jolly. Ad esempio, le query -luxury * non sono consentite.
• Nella sintassi completa le query con una singola negazione non sono consentite. Ad esempio, la query -luxury non è consentita.
• Nella sintassi completa le negazioni si comportano come se contenessero sempre AND nella query indipendentemente dalla modalità di ricerca.
  • Ad esempio, la query di sintassi completa wifi -luxury nella sintassi completa recupera solo i documenti che contengono il termine wifi, quindi applica la negazione -luxury a tali documenti.
• Se si desidera usare le negazioni per eseguire ricerche in tutti i documenti nell'indice, è consigliabile usare una sintassi semplice con la modalità di ricerca any.
• Se si desidera usare le negazioni per eseguire ricerche in un sottoinsieme di documenti nell'indice, è consigliabile usare una sintassi semplice con la modalità di ricerca.

Ricerca con campi

È possibile definire un'operazione di ricerca con campi con la sintassi fieldName:searchExpression, in cui l'espressione di ricerca può essere una singola parola o una frase o un'espressione più complessa tra parentesi, facoltativamente con operatori booleani. Ecco alcuni esempi:

• genre:jazz NOT history

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

Assicurarsi di inserire più stringhe racchiuse tra virgolette se si vuole che entrambe le stringhe siano valutate come una singola entità, in questo caso per la ricerca di due artisti distinti nel campo artists.

Il campo specificato in fieldName:searchExpression deve essere un campo searchable. Per informazioni dettagliate sull'uso di attributi dell'indice nelle definizioni campo, vedere Create Index (Creare l'indice).

Ricerca fuzzy

Una ricerca fuzzy trova corrispondenze in termini con una costruzione simile, espandendo un termine fino al massimo di 50 termini che soddisfano i criteri di distanza di due o meno. Per altre informazioni, vedere Ricerca fuzzy.

Per eseguire una ricerca fuzzy, usare il carattere tilde ~ alla fine di una singola parola con un parametro facoltativo, un numero compreso tra 0 e 2 (impostazione predefinita), che specifica il numero minimo di operazioni di modifica o "edit distance". Ad esempio, blue~ o blue~1 restituirà blue, blues e glue.

La ricerca fuzzy può essere applicata solo ai termini, non alle frasi racchiuse tra virgolette, ma è possibile accodare la tilde a ogni termine singolarmente in un nome o una frase in più parti. Ad esempio, Unviersty~ of~ Wshington~ corrisponderebbe a University of Washington.

Ricerca per prossimità

Le ricerche per prossimità vengono usate per trovare termini che si trovano vicini in un documento. Inserire un simbolo tilde ~ alla fine di una frase seguito dal numero di parole che creano il limite di prossimità. Ad esempio, "hotel airport"~5 trova i termini hotel e airport entro cinque parole l'uno dall'altro in un documento.

Ottimizzazione dei termini

L'aumento di priorità di un termine si riferisce alla classificazione più alta di un documento se contiene il termine con aumento di priorità, rispetto a documenti che non contengono il termine. Questo comportamento è diverso dall'assegnazione di punteggi ai profili, perché questo metodo assegna priorità ad alcuni campi, invece che a termini specifici.

L'esempio seguente illustra le differenze. Si supponga che esista un profilo di punteggio che migliora le corrispondenze in un determinato campo, ad esempio genre (genere) nell'esempio musicstoreindex. L'aumento di priorità di un termine si usa per assegnare a determinati termini di ricerca una priorità maggiore rispetto ad altri. Ad esempio, rock^2 electronic aumenta la priorità nell'indice dei documenti che contengono tali termini di ricerca nel campo genere rispetto a quelli con altri campi ricercabili. Inoltre, i documenti che contengono il termine di ricerca rock verranno classificati con una priorità superiore rispetto all'altro termine di ricerca electronic come risultato del valore di priorità del termine (2).

Per aumentare la priorità di un termine, usare il carattere accento circonflesso, ^, con un fattore di aumento di priorità (un numero) alla fine del termine da cercare. È anche possibile aumentare la priorità delle frasi. Maggiore è il fattore di aumento di priorità, più rilevante sarà il termine rispetto ad altri termini di ricerca. Per impostazione predefinita, il fattore di aumento è pari a 1. Anche se il fattore di aumento di priorità deve essere positivo, può essere minore di 1 (ad esempio 0,20).

Ricerca con espressioni regolari

Una ricerca con espressione regolare trova una corrispondenza in base ai criteri validi in Apache Lucene, come indicato nella classe RegExp. In Azure AI Search un'espressione regolare è racchiusa tra barre /.

Ad esempio, per trovare i documenti contenenti motel o hotel specificare /[mh]otel/. Le ricerche basate su espressioni regolari vengono confrontate con parole singole.

Alcuni strumenti e linguaggi impongono requisiti aggiuntivi per i caratteri di escape oltre alle regole di escape imposte da Azure AI Search. Per JSON, le stringhe che includono una barra vengono precedute da una barra rovesciata: microsoft.com/azure/ diventa search=/.*microsoft.com\/azure\/.*/ in cui search=/.* <string-placeholder>.*/ configura l'espressione regolare e microsoft.com\/azure\/ è la stringa con una barra di escape.

Due simboli comuni nelle query regex sono . e *. . corrisponde a un carattere qualsiasi e * corrisponde al carattere precedente zero o più volte. Ad esempio, /be./ corrisponde ai termini bee e bet, mentre /be*/ corrisponde a be, bee e beee ma non a bet. Insieme, .* consente di trovare le corrispondenze con qualsiasi serie di caratteri in modo che /be.*/ corrisponda a qualsiasi termine che inizia con be, ad esempio better.

Se si verificano errori di sintassi nell'espressione regolare, esaminare le regole di escape per i caratteri speciali. È anche possibile provare un client diverso per verificare se il problema è specifico dello strumento.

Ricerca con caratteri jolly

È possibile usare una sintassi generalmente riconosciuta per ricerche con caratteri jolly per trovare più caratteri (*) o un singolo carattere (?). La sintassi Lucene completa supporta la corrispondenza del prefisso e del suffisso. Usare la sintassi con espressioni regolari per la corrispondenza dei suffissi.

Si noti che il parser di query Lucene supporta l'utilizzo di questi simboli con un singolo termine, non una frase.

È possibile combinare gli operatori in un'unica espressione. Ad esempio, 980?2* corrisponde a 98072-1222 e 98052-1234, dove ? corrisponde a un singolo carattere (obbligatorio) e * corrisponde ai caratteri di una lunghezza arbitraria che segue.

La corrispondenza dei suffissi richiede i delimitatori / della barra delle espressioni regolari. In genere, non è possibile usare un simbolo * o ? come primo carattere di un termine senza /. È importante notare anche che * si comporta in modo diverso quando è usato fuori dalle query regex. Al di fuori del delimitatore / della barra regex * è un carattere jolly e corrisponde a qualsiasi serie di caratteri, in modo molto simile a .* in regex. Ad esempio, search=/non.*al/ produce lo stesso set di risultati di search=non*al.

Effetto di un analizzatore sulle query con caratteri jolly

Durante l'analisi delle query, le query formulate come prefisso, suffisso, carattere jolly o espressioni regolari vengono passate così come sono all'albero delle query, ignorando l'analisi lessicale. Le corrispondenze verranno trovate solo se l'indice contiene le stringhe nel formato specificato dalla query. Nella maggior parte dei casi, è necessario un analizzatore durante l'indicizzazione per mantenere l'integrità delle stringhe in modo che i criteri di ricerca e i termini parziali abbiano esito positivo. Per altre informazioni, vedere Ricerca di termini parziali nelle query di Azure AI Search.

Si consideri una situazione in cui si desidera che la query di ricerca terminal* restituisca risultati contenenti termini quali terminate, terminatione terminates.

Se si usasse l'analizzatore en.lucene (English Lucene), si applicherebbe lo stemming aggressivo di ogni termine. Ad esempio, terminate, termination e terminates verranno tutti tokenizzati fino al token termi nell'indice. D'altra parte, i termini nelle query che usano caratteri jolly o la ricerca fuzzy non vengono analizzati affatto, quindi non ci sarebbero risultati che corrisponderebbero alla query terminat*.

D'altra parte, gli analizzatori Microsoft (in questo caso, l'analizzatore en.microsoft) sono un po 'più avanzati e usano la lemmatizzazione invece dello stemming. Ciò significa che tutti i token generati devono essere parole inglesi valide. Ad esempio, terminate, terminates e termination rimarranno per lo più interi nell'indice e questa sarebbe una scelta preferibile per gli scenari che dipendono molto dai caratteri jolly e dalla ricerca fuzzy.

Punteggio delle query con caratteri jolly e regex

Azure AI Search usa il punteggio basato sulla frequenza (BM25) per le query di testo. Per le query con caratteri jolly e regex, in cui l'ambito dei termini può essere potenzialmente ampio, il fattore frequenza viene tuttavia ignorato per evitare che la classificazione privilegi le corrispondenze con termini più rari. Tutte le corrispondenze vengono trattate equamente per le ricerche con caratteri jolly e regex.

Caratteri speciali

In alcune circostanze potresti voler cercare un carattere speciale, ad esempio un'emoji '❤' o il segno '€'. In questi casi assicurarsi che l'analizzatore usato non escluda tali caratteri. L'analizzatore standard ignora molti caratteri speciali, escludendoli dall'indice.

Gli analizzatori che tokenizzano caratteri speciali includono l'analizzatore di spazi vuoti, che prende in considerazione qualsiasi sequenza di caratteri separati da spazi vuoti come token (quindi la stringa ❤ verrebbe considerata un token). Inoltre, un analizzatore del linguaggio come l'analizzatore Microsoft per l'inglese ("en.microsoft"), accetta la stringa "€" come token. È possibile testare un analizzatore per vedere quali token genera per una determinata query.

Quando si usano caratteri Unicode, assicurarsi che i simboli siano preceduti correttamente da un carattere di escape nell'URL della query( ad esempio, per ❤ usare la sequenza di escape %E2%9D%A4+). Alcuni client REST eseguono automaticamente questa traduzione.

Precedenza (raggruppamento)

È possibile usare le parentesi per creare sottoquery, inclusi gli operatori nell'istruzione tra parentesi. Ad esempio, motel+(wifi|luxury) cerca i documenti contenenti i termini motel e wifi o luxury (oppure entrambi).

Il raggruppamento di campi è simile, ma definisce un singolo campo come ambito del raggruppamento. Ad esempio, hotelAmenities:(gym+(wifi|pool)) cerca nel campo hotelAmenities gym e wifi o gym e pool.

Limiti di dimensione delle query

Azure AI Search imposta limiti per le dimensioni e la composizione delle query perché le query non associate possono destabilizzare il servizio di ricerca. Esistono limiti per le dimensioni e la composizione delle query (il numero di clausole). Esistono anche limiti per la lunghezza della ricerca del prefisso e per la complessità della ricerca regex e della ricerca con caratteri jolly. Se l'applicazione genera query di ricerca a livello di codice, è consigliabile progettarla in modo che non generi query di dimensioni illimitate.

Per altre informazioni sui limiti delle query, vedere Limiti delle richieste API.

Vedi anche

• Esempi di query per la ricerca semplice
• Esempi di query per la ricerca Lucene completa
• Eseguire ricerche nei documenti
• Sintassi delle espressioni OData per filtri e ordinamento
• Sintassi di query semplice in Azure AI Search