Sintassi delle query Lucene in Ricerca cognitiva di Azure

Quando si creano query, è possibile scegliere la sintassi del parser di query Lucene per moduli di query specializzati: caratteri jolly, ricerca fuzzy, ricerca di prossimità, espressioni regolari. Gran parte della sintassi Del parser di query Lucene viene implementata intatta in Ricerca cognitiva di Azure, ad eccezione delle ricerche di intervalli costruite tramite $filter espressioni.

Per usare la sintassi Lucene completa, si imposterà queryType su "full" e si passerà 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 search parametro di una richiesta di ricerca di 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 il boosting dei termini. Cerca gli hotel in cui il campo categoria contiene il termine "budget". Tutti i documenti contenenti la frase "recentemente rinnovata" vengono classificati più in alto in seguito al valore di boost del termine (3).

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

Anche se non è specifico di alcun tipo di query, il searchMode parametro è 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 Search Documents (REST API).

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 qualsiasi 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 al seguente \+1 \(800\) 642\-7676.

I caratteri speciali che richiedono l'escape includono quanto segue:
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

Nota

Anche se l'escape mantiene insieme i token, l'analisi lessicale durante l'indicizzazione può rimuoverli. Ad esempio, l'analizzatore Lucene standard interromperà le parole su trattini, spazi vuoti e altri caratteri. Se sono necessari caratteri speciali nella stringa di query, potrebbe essere necessario un analizzatore che li conserva nell'indice. Alcune scelte includono analizzatori del linguaggio naturale Microsoft, che conserva parole sillabate o un analizzatore personalizzato per modelli più complessi. Per altre informazioni, vedere Termini parziali, modelli e caratteri speciali.

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 mentre delimitano i parametri e specificano i valori in Ricerca cognitiva di Azure. Per altri dettagli, vedere RFC1738: URL (Uniform Resource Locators).

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.

Operatore di testo Carattere Esempio Utilizzo
AND + wifi AND luxury Specifica i termini che una corrispondenza deve contenere. Nell'esempio il motore di query cercherà i documenti contenenti sia che wifiluxury. Il carattere più (+) può anche essere usato direttamente davanti a un termine per renderlo obbligatorio. Ad esempio, +wifi +luxury stabilisce che entrambi i termini devono essere presenti nel campo di un singolo documento.
OR (nessuno) 1 wifi OR luxury Trova una corrispondenza quando viene trovato un termine. Nell'esempio, il motore di query restituirà la corrispondenza nei documenti contenenti wifi o luxury entrambi. Poiché OR è l'operatore di congiunzione predefinito, è anche possibile ometterlo, in modo che wifi luxury sia l'equivalente di wifi OR luxury.
NOT !, - wifi –luxury Restituisce corrispondenze nei documenti che escludono il termine. Ad esempio, wifi –luxury cercherà i documenti con il wifi termine ma non luxury.

Il searchMode parametro in una richiesta di query controlla se un termine con l'operatore NOT è ANDed o ORed con altri termini nella query (presupponendo che non siano presenti operatori booleani negli altri termini). I valori validi sono any o all.

searchMode=any aumenta il richiamo delle query includendo più risultati e per impostazione predefinita - verrà interpretato come "OR NOT". Ad esempio, wifi -luxury corrisponderà ai documenti che contengono il termine wifi o quelli che non contengono il termine luxury.

searchMode=all aumenta la precisione delle query includendo un minor numero di risultati e, per impostazione predefinita, verrà interpretata come "AND NOT". Ad esempio, wifi -luxury corrisponderà ai documenti che contengono il termine wifi e non conterranno il termine "lusso". Si tratta di un comportamento verosimilmente più intuitivo per l'operatore -. Pertanto, è consigliabile usare searchMode=all anziché searchMode=any se si vogliono ottimizzare le ricerche di precisione anziché richiamo e gli utenti usano spesso l'operatore - nelle ricerche.

Quando si decide un'impostazione searchMode , prendere in considerazione i modelli di interazione utente per le query in varie applicazioni. È più probabile che gli utenti che cercano informazioni includano un operatore in una query, anziché siti di e-commerce con strutture di navigazione più integrate.

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

Ricerca campiata

È possibile definire un'operazione di ricerca con campi con la fieldName:searchExpression sintassi, 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).

Nota

Quando si usano espressioni di ricerca con campi, non è necessario usare il searchFields parametro perché ogni espressione di ricerca campi ha un nome di campo specificato in modo esplicito. Tuttavia, è comunque possibile usare il searchFields parametro se si vuole eseguire una query in cui alcune parti hanno come ambito un campo specifico e il resto può essere applicato a diversi campi. Ad esempio, la query search=genre:jazz NOT history&searchFields=description corrisponde jazz solo al genre campo , mentre corrisponde al NOT historydescription campo . Il nome del campo specificato in fieldName:searchExpression ha sempre la precedenza sul searchFields parametro , motivo per cui in questo esempio non è necessario includere genre nel searchFields parametro .

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 a termini, non frasi, ma è possibile accodare la tilde a ogni termine singolarmente in un nome o una frase in più parti. Ad esempio, "Unviersty~ di~ "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 carattere tilde "~" alla fine di una frase seguito dal numero di parole che creano il limite di prossimità. Ad esempio, "hotel airport"~5 troverà i termini "hotel" e "airport" entro 5 parole di distanza una dall'altra in un documento.

Aumento priorità dei termini

Questa definizione si riferisce alla 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 sia presente un profilo di punteggio che aumenta le corrispondenze in un determinato campo , ad esempio 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 genre 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 un termine, usare il segno di caret, "^", simbolo con un fattore di aumento (un numero) alla fine del termine che si sta cercando. È 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 di priorità è 1. Anche se il fattore di aumento di priorità deve essere positivo, può essere minore di 1 (ad esempio 0,20).

Ricerca basata su espressioni regolari

Una ricerca di espressioni regolari trova una corrispondenza in base ai modelli validi in Apache Lucene, come documentato nella classe RegExp. In Ricerca cognitiva di Azure un'espressione regolare è racchiusa tra le /barre in avanti .

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 lingue impongono requisiti di carattere di escape aggiuntivi. Per JSON, le stringhe che includono una barra in avanti vengono escape con una barra indietro: "microsoft.com/azure/" diventa search=/.*microsoft.com\/azure\/.*/ dove search=/.* <string-placeholder>.*/ configura l'espressione regolare ed microsoft.com\/azure\/ è la stringa con una barra in uscita.

Due simboli comuni nelle query regex sono . e *. Un oggetto . corrisponde a uno qualsiasi carattere e a corrisponde * al carattere precedente zero o più volte. Ad esempio, /be./ corrisponderà ai termini "bee" e "bet" mentre /be*/ corrisponderebbe "bee", "bee" e "bee" ma non "bet". Insieme, .* consente di corrispondere a qualsiasi serie di caratteri in modo /be.*/ che corrisponda a qualsiasi termine che inizia con "be" come "meglio".

Ricerca con caratteri jolly

È possibile usare la sintassi generalmente riconosciuta per ricerche con caratteri jolly multipli () o singoli (*?). La sintassi Lucene completa supporta il prefisso, il prefisso e la corrispondenza del suffisso.

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

Tipo di affisso Descrizione ed esempi
prefix Il frammento di termini viene prima * o ?. Ad esempio, un'espressione di query di search=alpha* restituisce "alfanumerico" o "alfabetica". La corrispondenza del prefisso è supportata sia nella sintassi semplice che completa.
suffix Il frammento di termini viene dopo * o ?, con una barra in avanti per delimitare il costrutto. Ad esempio, search=/.*numeric/ restituisce "alfanumerico".
infisso Frammenti di termini racchiudere * o ?. Ad esempio, search=non*al restituisce "non numerico" e "non disensico".

È possibile combinare gli operatori in un'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 del suffisso richiede i delimitatori di barra / regolare. In genere, non è possibile usare un simbolo o ? come primo carattere di un * termine, senza ./ È anche importante notare che il comportamento si comporta in modo diverso quando usato all'esterno * delle query regex. All'esterno o ai delimitatori di barra / regex, l'oggetto * è un carattere jolly e corrisponderà a qualsiasi serie di caratteri come .* in regex. Ad esempio, search=/non.*al/ produrrà lo stesso set di risultati di search=non*al.

Nota

Come regola, la corrispondenza dei modelli è lenta in modo da poter esplorare metodi alternativi, ad esempio la tokenizzazione n-gram perimetrale che crea token per sequenze di caratteri in un termine. Con la tokenizzazione n-gram, l'indice sarà più grande, ma le query potrebbero essere eseguite più velocemente, a seconda della costruzione del modello e della lunghezza delle stringhe indicizzate. Per altre informazioni, vedere Ricerca e modelli di termini parziali con caratteri speciali.

Impatto di un analizzatore sulle query con caratteri jolly

Durante l'analisi delle query, le query formulate come prefisso, suffisso, caratteri jolly o espressioni regolari vengono passate come è 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 che mantiene l'integrità della stringa in modo che il termine parziale e la corrispondenza dei modelli abbiano esito positivo. Per altre informazioni, vedere Ricerca di termini parziali nelle query di Ricerca cognitiva di Azure.

Si consideri una situazione in cui è possibile che la query di ricerca 'terminat*' restituisca i risultati che contengono termini come 'termina', 'terminazione' e 'terminazioni'.

Se si usasse l'analizzatore en.lucene (inglese Lucene), si applicherebbe uno stemma aggressivo di ogni termine. Ad esempio, 'terminazione', 'terminazione', 'terminazioni' 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 in alcun modo. Pertanto 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 lemmatizzazione invece di stemming. Ciò significa che tutti i token generati devono essere parole in inglese valide. Ad esempio, "termina", "termina" e "terminazione" rimarrà per lo più intero nell'indice e 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

Ricerca cognitiva di Azure 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 filtra tali caratteri. L'analizzatore standard ignora molti caratteri speciali, esclusi dall'indice.

Gli analizzatori che tokenizzeranno caratteri speciali includono l'analizzatore "whitespace", che prende in considerazione eventuali sequenze di caratteri separate da spazi vuoti come token (quindi la stringa "❤" verrebbe considerata un token). Inoltre, un analizzatore di linguaggio come l'analizzatore inglese Microsoft ("en.microsoft"), accetta la stringa "€" come token. È possibile testare un analizzatore per visualizzare i token generati per una determinata query.

Quando si usano i caratteri Unicode, assicurarsi che i simboli vengano eliminati correttamente nell'URL della query (ad esempio per "❤" userebbe la sequenza %E2%9D%A4+di escape). Postman esegue automaticamente questa traduzione.

Precedenza (raggruppamento)

È possibile usare le parentesi per creare sottoquery, inclusi gli operatori nell'istruzione tra parentesi. Ad esempio, motel+(wifi|luxury) cercherà 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 "gym" e "wifi" oppure "gym" e "pool" nel campo "hotelAmenities".

Limiti delle dimensioni delle query

Ricerca cognitiva di Azure impone limiti alle dimensioni e alla composizione delle query perché le query non associate possono destabilizzare il servizio di ricerca. Esistono limiti per le dimensioni e la composizione delle query (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