Sintassi di query semplice in Ricerca cognitiva di Azure

Ricerca cognitiva di Azure implementa due linguaggi di query basati su Lucene: Simple Query Parser e Lucene Query Parser. Il parser semplice è più flessibile e tenterà di interpretare una richiesta anche se non è perfettamente composta. Poiché è flessibile, è l'impostazione predefinita per le query in Ricerca cognitiva di Azure.

La sintassi di query per uno dei due parser si applica alle espressioni di query passate nel parametro "search" di una richiesta dell'API REST (Search Documents), per non confondere con la sintassi OData usata per le espressioni "$filter" e "$orderby" nella stessa richiesta. I parametri OData hanno sintassi e regole diverse per la creazione di query, l'escape di stringhe e così via.

Anche se il parser semplice è basato sulla classe Parser Di query semplice Apache Lucene , l'implementazione in Ricerca cognitiva esclude la ricerca fuzzy. Se è necessaria una ricerca fuzzy, considerare invece la sintassi di query Lucene completa alternativa.

Esempio (sintassi semplice)

In questo esempio viene illustrata una query semplice, distinta per "queryType": "simple" e sintassi valida. Anche se il tipo di query è impostato di seguito, è l'impostazione predefinita e può essere omesso a meno che non si stia ripristinando da un tipo alternativo. L'esempio seguente è una ricerca in termini indipendenti, con un requisito che tutti i documenti corrispondenti includono "pool".

POST https://{{service-name}}.search.windows.net/indexes/hotel-rooms-sample/docs/search?api-version=2020-06-30
{
  "queryType": "simple",
  "search": "budget hotel +pool",
  "searchMode": "all"
}

Il parametro "searchMode" è rilevante in questo esempio. Ogni volta che gli operatori booleani si trovano nella query, è consigliabile impostare "searchMode=all" in genere per assicurarsi che tutti i criteri corrispondano. In caso contrario, è possibile usare l'impostazione predefinita "searchMode=any" che favorisca il richiamo rispetto alla precisione.

Per altri esempi, vedere Esempi di sintassi di query semplici. Per informazioni dettagliate sulla richiesta di query e sui parametri, vedere Cercare documenti (API REST).

Ricerca di parole chiave in termini e frasi

Le stringhe passate al parametro "search" possono includere termini o frasi in qualsiasi linguaggio supportato, operatori booleani, operatori di precedenza, caratteri jolly o caratteri di prefisso per le query "inizia con", caratteri di escape e caratteri di codifica URL. Il parametro "search" è facoltativo. La ricerca (search=* o search=" ") non specificata restituisce i primi 50 documenti in ordine arbitrario (non classificato).

  • Una ricerca di termini è una query di uno o più termini, in cui uno qualsiasi dei termini viene considerato una corrispondenza.

  • Una ricerca di frasi è una frase esatta racchiusa tra virgolette " ". Ad esempio, mentre Roach Motel (senza virgolette) cercherebbe documenti contenenti Roach e/o Motel ovunque in qualsiasi ordine, "Roach Motel" (con virgolette) corrisponderà solo ai documenti che contengono l'intera frase insieme e in tale ordine (l'analisi lessicale è ancora applicabile).

    A seconda del client di ricerca, potrebbe essere necessario eseguire l'escape delle virgolette in una ricerca di frasi. Ad esempio, in Postman in una richiesta POST, una ricerca "Roach Motel" di frasi nel corpo della richiesta verrebbe specificata come "\"Roach Motel\"".

Per impostazione predefinita, tutte le stringhe passate nel parametro "search" vengono sottoposte a analisi lessicali. Assicurarsi di comprendere il comportamento di tokenizzazione dell'analizzatore in uso. Spesso, quando i risultati della query sono imprevisti, il motivo può essere tracciato alla modalità di tokenizzazione dei termini in fase di query. È possibile testare la tokenizzazione in stringhe specifiche per confermare l'output.

Qualsiasi input di testo con uno o più termini è considerato un punto di partenza valido per l'esecuzione di query. Ricerca cognitiva di Azure corrisponderà ai documenti contenenti uno o tutti i termini, incluse eventuali variazioni rilevate durante l'analisi del testo.

Come sembra semplice come questo, c'è un aspetto dell'esecuzione di query in Ricerca cognitiva di Azure che potrebbe produrre risultati imprevisti, aumentando invece di diminuire i risultati della ricerca man mano che più termini e operatori vengono aggiunti alla stringa di input. Se questa espansione si verifica effettivamente dipende dall'inclusione di un operatore NOT, combinata con un'impostazione di parametro "searchMode" che determina come NOT viene interpretato in termini di comportamenti AND o OR. Per altre informazioni, vedere l'operatore NOT in Operatori booleani.

Operatori booleani

È possibile incorporare operatori booleani in una stringa di query per migliorare la precisione di una corrispondenza. Nella sintassi semplice gli operatori booleani sono basati su caratteri. Gli operatori di testo, ad esempio la parola AND, non sono supportati.

Carattere Esempio Utilizzo
+ pool + ocean Operazione AND. Ad esempio, pool + ocean stabilisce che un documento deve contenere entrambi i termini.
| pool | ocean Un'operazione OR trova una corrispondenza quando viene trovato un termine. Nell'esempio, il motore di query restituirà la corrispondenza nei documenti contenenti pool o ocean entrambi. Poiché OR è l'operatore di congiunzione predefinito, è anche possibile ometterlo, in modo che pool ocean sia l'equivalente di pool | ocean.
- pool – ocean Un'operazione NOT restituisce corrispondenze nei documenti che escludono il termine.

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, pool - ocean corrisponderà ai documenti che contengono il termine pool o quelli che non contengono il termine ocean.

searchMode=all aumenta la precisione delle query includendo un minor numero di risultati e per impostazione predefinita verrà interpretata - come "AND NOT". Ad esempio, con searchMode=and, la query pool - ocean corrisponderà ai documenti che contengono il termine "pool" e tutti i documenti che non contengono il termine "oceano". 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.

Query con prefisso

Per le query "inizia con", aggiungere un operatore suffisso (*) come segnaposto per il resto di un termine. Prima di poter aggiungere l'operatore suffisso, una query di prefisso deve iniziare con almeno un carattere alfanumerico.

Carattere Esempio Utilizzo
* lingui* corrisponderà a "linguistico" o "linguini" L'asterisco (*) rappresenta uno o più caratteri di lunghezza arbitraria, ignorando la distinzione tra maiuscole e minuscole.

Analogamente ai filtri, una query di prefisso cerca una corrispondenza esatta. Di conseguenza, non esiste un punteggio di pertinenza (tutti i risultati ricevono un punteggio di ricerca pari a 1,0). Tenere presente che le query di prefisso possono essere lente, soprattutto se l'indice è grande e il prefisso è costituito da un numero ridotto di caratteri. Una metodologia alternativa, ad esempio la tokenizzazione n-grammo perimetrale, potrebbe risultare più veloce. I termini che usano la ricerca con prefisso non possono superare i 1000 caratteri.

La sintassi semplice supporta solo la corrispondenza dei prefissi. Per la corrispondenza del suffisso o del prefisso rispetto alla fine o alla metà di un termine, usare la sintassi Lucene completa per la ricerca con caratteri jolly.

Escape degli operatori di ricerca

Nella sintassi semplice gli operatori di ricerca includono questi caratteri: + | " ( ) ' \

Se uno di questi caratteri fa parte di un token nell'indice, eseguirne l'escape anteponendolo a una singola barra rovesciata (\) nella query. Si supponga, ad esempio, di aver usato un analizzatore personalizzato per la tokenizzazione dell'intero termine e che l'indice contenga la stringa "Luxury+Hotel". Per ottenere una corrispondenza esatta su questo token, inserire un carattere di escape: search=luxury\+hotel.

Per semplificare i casi più tipici, esistono due eccezioni a questa regola in cui l'escape non è necessario:

  • L'operatore - NOT deve essere preceduto da un carattere di escape solo se è il primo carattere dopo uno spazio vuoto. Se l'oggetto - viene visualizzato al centro (ad esempio, in 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD), è possibile ignorare l'escape.

  • L'operatore * suffisso deve essere preceduto da un carattere di escape solo se è l'ultimo carattere prima di uno spazio vuoto. Se l'oggetto * viene visualizzato al centro (ad esempio, in 4*4=16), non è necessario eseguire l'escape.

Nota

Per impostazione predefinita, l'analizzatore standard eliminerà e interromperà le parole su trattini, spazi vuoti, e commerciale e altri caratteri durante l'analisi lessicale. Se sono necessari caratteri speciali per rimanere nella stringa di query, potrebbe essere necessario un analizzatore che li conserva nell'indice. Alcune scelte includono Microsoft analizzatori del linguaggio naturale, che mantiene le 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

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

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

Caratteri speciali

I caratteri speciali possono variare da simboli di valuta come '$' o '€', a emoji. Molti analizzatori, incluso l'analizzatore standard predefinito, escluderanno caratteri speciali durante l'indicizzazione, il che significa che non saranno rappresentati nell'indice.

Se è necessaria una rappresentazione di caratteri speciale, è possibile assegnare un analizzatore che li mantiene:

  • L'analizzatore "spazi vuoti" considera qualsiasi sequenza di caratteri separata da spazi vuoti come token( pertanto l'emoji '❤' verrebbe considerata un token).

  • Un analizzatore del linguaggio, ad esempio Microsoft analizzatore inglese ("en.microsoft"), accetta la stringa '$' o '€' come token.

Per confermare, è possibile testare un analizzatore per vedere quali token vengono generati per una determinata stringa. Come ci si può aspettare, potrebbe non essere possibile ottenere la tokenizzazione completa da un singolo analizzatore. Una soluzione alternativa consiste nel creare più campi che contengono lo stesso contenuto, ma con assegnazioni di analizzatori diverse,ad esempio"description_en", "description_fr" e così via per gli analizzatori del linguaggio).

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

Limiti delle dimensioni delle query

Se l'applicazione genera query di ricerca a livello di codice, è consigliabile progettarla in modo che non generi query di dimensioni non associate.

  • Per GET, la lunghezza dell'URL non può superare 8 KB.

  • Per POST (e qualsiasi altra richiesta), dove il corpo della richiesta include search e altri parametri, filter ad esempio e orderby, la dimensione massima è 16 MB. I limiti aggiuntivi includono:

    • La lunghezza massima della clausola di ricerca è di 100.000 caratteri.
    • Il numero massimo di clausole in search (espressioni separate da AND o OR) è 1024.
    • La dimensione massima del termine di ricerca è di 1000 caratteri per la ricerca del prefisso.
    • Esiste anche un limite di circa 32 KB per le dimensioni di qualsiasi singolo termine in una query.

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

Passaggi successivi

Se si creeranno query a livello di codice, esaminare la ricerca full-text in Ricerca cognitiva di Azure per comprendere le fasi dell'elaborazione delle query e le implicazioni dell'analisi del testo.

Per altre informazioni sulla costruzione di query, vedere gli articoli seguenti: