Sintassi della query Lucene in Ricerca cognitiva di Azure

Quando si creano query in Ricerca cognitiva di Azure, è possibile scegliere la sintassi completa di Analisi query lucene per i moduli di query specializzati: caratteri jolly, ricerca fuzzy, ricerca di prossimità, espressioni regolari. Gran parte della sintassi di Analisi query lucene viene implementata intatta in Ricerca cognitiva di Azure, ad eccezione delle ricerche di *intervallo, che vengono costruite tramite $filter espressioni.

Per usare la sintassi lucene completa, si imposta queryType su "full" e si passa un'espressione di query modellata per il carattere jolly, la 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 documenti (API REST).

Esempio (sintassi completa)

L'esempio seguente è una richiesta di ricerca costruita usando la sintassi completa. Questo esempio specifico mostra la ricerca in campo e il termine boosting. Cerca alberghi in cui il campo categoria contiene il termine "budget". Tutti i documenti contenenti la frase "recentemente rinnovata" sono classificati più alti a causa del valore di aumento 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 delle query lucene. Per informazioni dettagliate sulla richiesta di query e sui parametri, tra cui searchMode, vedere Ricerca 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 tramite prefisso con una singola barra rovesciata (\). Ad esempio, per una ricerca con caratteri jolly su https://, dove :// fa parte della stringa di query, è necessario specificare search=https\:\/\/*. Analogamente, un modello di numero di telefono di escape potrebbe essere simile a questo \+1 \(800\) 642\-7676.

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

Nota

Anche se l'uscita mantiene insieme i token, l'analisi lessicale durante l'indicizzazione può rimuoverli. Ad esempio, l'analizzatore Lucene standard interromperà le parole sui trattini, sugli spazi vuoti e su altri caratteri. Se sono necessari caratteri speciali nella stringa di query, potrebbe essere necessario un analizzatore che li conserva nell'indice. Alcune scelte includono Microsoft analizzatori del linguaggio naturale, che conserva parole trattine 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 non sicuri e riservati 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 in quanto delimitano i parametri e specificano i valori in Ricerca cognitiva di Azure. Per altre informazioni, 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.

Operatore di testo Carattere Esempio Utilizzo
AND + wifi AND luxury Specifica i termini che deve contenere una corrispondenza. Nell'esempio, il motore di query cercherà documenti contenenti sia wifi che luxury. Il carattere più (+) può 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 combinazione predefinito, è anche possibile lasciarlo fuori, in modo che wifi luxury sia l'equivalente di wifi OR luxury.
NOT !, - wifi –luxury Restituisce le corrispondenze nei documenti che escludono il termine. Ad esempio, wifi –luxury cercherà i documenti con il wifi termine ma non luxury.

È importante notare che l'operatore NOT (NOT, !o ) -si comporta in modo diverso nella sintassi completa rispetto alla sintassi semplice. Nella sintassi completa, le negazioni saranno sempre ANDed nella query in modo che venga interpretato come "wifi AND NOT luxury" indipendentemente dal fatto che wifi -luxury il searchMode parametro sia impostato su any o all. In questo modo si ottiene un comportamento più intuitivo per le negazioni per impostazione predefinita.

Una singola negazione, ad esempio la query -luxury , non è consentita nella sintassi di ricerca completa e restituirà sempre un set di risultati vuoto.

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

Ricerca in campi

È possibile definire un'operazione di ricerca a 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 gli 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 in campi, non è necessario usare il searchFields parametro perché ogni espressione di ricerca in 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 sono con ambito a 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 NOT history al description campo. Il nome del searchFields campo fornito in fieldName:searchExpression ha sempre la precedenza sul parametro, che è il motivo per cui in questo esempio non è necessario includere genre nel searchFields parametro.

Ricerca fuzzy

Una ricerca fuzzy trova corrispondenze in termini che hanno 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, ma è possibile aggiungere 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 "aeroporto" entro cinque parole l'uno dall'altro in un documento.

Aumento priorità dei termini

L'aumento del termine fa riferimento alla classificazione di un documento più alto se contiene il termine incrementato, rispetto ai 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 il valore di un termine, usare il simbolo "^", con un fattore di boost (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 /.

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 altri requisiti per i caratteri di escape. Per JSON, le stringhe che includono una barra vengono precedute da una barra rovesciata: "microsoft.com/azure/" diventa search=/.*microsoft.com\/azure\/.*/ dove search=/.* <string-placeholder>.*/ imposta l'espressione regolare ed microsoft.com\/azure\/ è la stringa con una barra preceduta da un carattere di escape.

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

Ricerca con caratteri jolly

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

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

Tipo affiss Descrizione ed esempi
prefix Il frammento di termine precede * o ?. Ad esempio, un'espressione di query di search=alpha* restituisce "alfanumerico" o "alfabetico". La corrispondenza dei prefissi è supportata sia nella sintassi semplice che completa.
suffix Il frammento di termine viene dopo * o ?, con una barra per delimitare il costrutto. Ad esempio, search=/.*numeric/ restituisce "alfanumerico".
infisso I frammenti di termini racchiudono * o ?. Ad esempio, search=non*al restituisce "non numerico" e "senza distinzione".

È 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 barra dell'espressione / regolare. In genere, non è possibile usare un * simbolo o ? come primo carattere di un termine, senza ./ È anche importante notare che il * comportamento di si comporta in modo diverso quando viene usato all'esterno delle query regex. All'esterno o ai delimitatori di barra / regex, è * 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 criteri è lenta, quindi è consigliabile esplorare metodi alternativi, ad esempio la tokenizzazione di n grammi perimetrali che crea token per sequenze di caratteri in un termine. Con la tokenizzazione n-gram, l'indice sarà maggiore, 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, carattere jolly o espressioni regolari vengono passate così com'è 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à delle stringhe in modo che il termine parziale e la corrispondenza dei criteri abbiano esito positivo. Per altre informazioni, vedere Ricerca parziale dei termini nelle query Ricerca cognitiva di Azure.

Si consideri una situazione in cui è possibile che la query di ricerca 'terminat*' restituisca risultati contenenti termini come 'terminate', 'terminate' e 'terminates'.

Se si usasse l'analizzatore en.lucene (inglese Lucene), si applicherebbe uno stemming aggressivo di ogni termine. Ad esempio, 'terminate', 'termination', '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. 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 la lemmatizzazione anziché lo stemming. Ciò significa che tutti i token generati devono essere parole in inglese valide. Ad esempio, 'terminate', 'terminates' e 'terminazione' rimarranno per lo più interi 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 alcuni casi, potresti voler cercare un carattere speciale, ad esempio un'emoji '❤' o il segno '€'. In questi casi, assicurarsi che l'analizzatore usato non filtri tali caratteri. L'analizzatore standard ignora molti caratteri speciali, escludendoli dall'indice.

Gli analizzatori che tokenizzeranno caratteri speciali includono l'analizzatore "spazi vuoti", che prende in considerazione le sequenze di caratteri separate da spazi vuoti come token (quindi la stringa "❤" verrebbe considerata un token). Inoltre, un analizzatore del 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 caratteri Unicode, assicurarsi che i simboli siano preceduti correttamente da un carattere di escape 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 alle dimensioni e alla composizione delle query (il numero di clausole). Esistono anche limiti per la lunghezza della ricerca di prefissi e per la complessità della ricerca regex e dei caratteri jolly. Se l'applicazione genera query di ricerca a livello di codice, è consigliabile progettarla in modo che non generi query di dimensioni non associate.

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

Vedi anche