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 della query per un parser si applica alle espressioni di query passate nel parametro "search" di una richiesta DI RICERCA documenti (API REST), non per essere confusa con la sintassi OData usata per le espressioni "$filter " e " $orderby" nella stessa richiesta. I parametri OData dispongono di sintassi e regole diverse per la creazione di query, l'eliminazione di stringhe e così via.

Anche se il parser semplice è basato sulla classe Apache Lucene Simple Query Parser , 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 semplice query, distinta in base "queryType": "simple" alla sintassi valida. Anche se il tipo di query è impostato di seguito, è il valore predefinito e può essere omesso a meno che non si stia ripristinando da un tipo alternativo. L'esempio seguente è una ricerca su 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 siano corrispondenti. In caso contrario, è possibile usare il valore predefinito "searchMode=any" che favorisce il richiamo sulla precisione.

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

Ricerca di parole chiave per 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", i caratteri di escape e i caratteri di codifica URL. Il parametro "search" è facoltativo. Non specificato, ricerca (search=* o search=" ") restituisce i primi 50 documenti in ordine arbitrario (non classificato).

  • Una ricerca di termini è una query di uno o più termini, in cui una delle condizioni viene considerata una corrispondenza.

  • Una ricerca di frasi è una frase esatta racchiusa tra virgolette " ". Ad esempio, mentre Roach Motel (senza virgolette) cercare documenti contenenti e/o Motel ovunque in qualsiasi ordine, "Roach Motel" (con virgolette) corrisponderanno solo i documenti che Roach contengono l'intera frase insieme e in tale ordine (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, verrà specificata una ricerca "Roach Motel" di frasi nel corpo della richiesta come "\"Roach Motel\"".

Per impostazione predefinita, tutte le stringhe passate al parametro "ricerca" subiscono analisi lessicali. Assicurarsi di comprendere il comportamento di tokenizzazione dell'analizzatore in uso. Spesso, quando i risultati delle query sono imprevisti, il motivo può essere tracciato su come i termini vengono tokenizzati 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 qualsiasi o tutte le condizioni, incluse eventuali variazioni trovate durante l'analisi del testo.

Come semplice come questo suono, c'è un aspetto dell'esecuzione di query in Ricerca cognitiva di Azure che potrebbe produrre risultati imprevisti, aumentando anziché riducendo i risultati della ricerca come 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 NON 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 combinazione predefinito, è anche possibile lasciarlo fuori, 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 altri risultati e per impostazione predefinita - verrà interpretato come "OR NOT". Ad esempio, pool - ocean corrisponderà ai documenti che contengono il termine o quelli che non contengono il termine poolocean.

searchMode=all aumenta la precisione delle query includendo meno risultati e per impostazione predefinita - verrà interpretato come "AND NOT". Ad esempio, con searchMode=any, 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 anziché se si desidera ottimizzare le ricerche invece searchMode=any di richiamare la precisione e gli utenti usano searchMode=all 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. Gli utenti che stanno cercando informazioni sono più probabilità di includere un operatore in una query, anziché siti di e-commerce con strutture di spostamento più predefinite.

Query di prefisso

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

Carattere Esempio Utilizzo
* lingui* corrisponderà a "linguistico" o "linguini" L'asterisco (*) rappresenta uno o più caratteri di lunghezza arbitraria, ignorando il caso.

Analogamente ai filtri, una query di prefisso cerca una corrispondenza esatta. Di conseguenza, non esiste alcun 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-gram perimetrale, potrebbe essere più veloce. I termini con la ricerca del prefisso non possono essere più lunghi di 1000 caratteri.

La sintassi semplice supporta solo la corrispondenza dei prefisso. Per suffisso o prefisso corrispondente 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 tramite il prefisso con una singola barra rovesciata (\) nella query. Si supponga, ad esempio, di usare un analizzatore personalizzato per l'intera tokenizzazione del 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 non è necessaria l'uscita:

  • L'operatore - NOT deve essere eliminato 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'uscita-.

  • L'operatore * suffisso deve essere 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'escaping*.

Nota

Per impostazione predefinita, l'analizzatore standard eliminerà e interromperà le parole su trattini, spazi vuoti, amperandi 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 analizzatori di linguaggio naturale Microsoft, 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 ; / ? : @ = + &.

Caratteri speciali

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

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

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

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

Per conferma, è possibile testare un analizzatore per visualizzare i token generati per una determinata stringa. Come si potrebbe aspettarsi, potrebbe non 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 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).

Limiti delle dimensioni delle query

Se l'applicazione genera query di ricerca a livello di codice, è consigliabile progettarla in modo da non generare 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, ad esempio filter e orderby, la dimensione massima è di 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 costruiscono query a livello di codice, vedere Ricerca full-text in Ricerca cognitiva di Azure per comprendere le fasi dell'elaborazione delle query e le implicazioni dell'analisi del testo.

È anche possibile esaminare gli articoli seguenti per altre informazioni sulla costruzione di query: