Sintassi di query semplice in Azure AI Search

  • Articolo

Per gli scenari di ricerca full-text, Azure AI Search implementa due linguaggi di query basati su Lucene, ognuno allineato a un parser di query. Il parser di query semplice è l'impostazione predefinita. Illustra i casi d'uso comuni e tenta di interpretare una richiesta anche se non perfettamente composta. L'altro parser è il parser di query Lucene e supporta costruzioni di query più avanzate.

Questo articolo è il riferimento alla sintassi delle query per il parser di query semplici.

La sintassi delle query per entrambi i parser si applica alle espressioni di query passate nel parametro search di una richiesta di query, da non confondere con la sintassi OData, con la propria sintassi e le regole per le espressioni filter e orderby nella stessa richiesta.

Anche se il parser semplice si basa sulla classe parser di query semplici Lucene di apache, l'implementazione in Azure AI Search esclude la ricerca fuzzy. Se si necessita di ricerca fuzzy, prendere in considerazione l'alternativa della sintassi di query Lucene completa.

Schema (sintassi semplice)

In questo esempio viene illustrata una query semplice, distinta per "queryType": "simple" e sintassi valida. Anche se il tipo di query viene impostato di seguito, si tratta dell'impostazione predefinita e può essere omessa, a meno che non si stia effettuando il ripristino da un tipo alternativo. L'esempio seguente è una ricerca su termini indipendenti, con il requisito che tutti i documenti corrispondenti includano "piscina".

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

Il parametro searchMode è rilevante in questo esempio. Quando nella query sono presenti operatori booleani, è in genere consigliabile impostare searchMode=all per assicurarsi che venga trovata una corrispondenza per tutti i criteri. In caso contrario, è possibile usare il searchMode=any predefinito che favorisce 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 Cerca 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 query "inizia con", caratteri di escape e caratteri di codifica URL. search è facoltativo. Ricerca non specificata (search=* o search=" ") restituisce i primi 50 documenti in ordine arbitrario (non classificato).

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

  • Una ricerca di frasi è una frase esatta racchiusa tra virgolette " ". Ad esempio, mentre Roach Motel (senza virgolette) cerca i documenti contenenti Roach e/o Motel ovunque e in qualsiasi ordine, "Roach Motel" (con le virgolette) troverà solo i documenti contenenti l'intera frase in quell'ordine specifico (l'analisi lessicale è comunque applicabile).

A seconda del client di ricerca, potrebbe essere necessario eseguire l'escape delle virgolette nella ricerca di frasi. In una richiesta POST, ad esempio, una ricerca di frasi su "Roach Motel" nel corpo della richiesta potrebbe essere specificata come "\"Roach Motel\"". Se si usano gli SDK di Azure, il client di ricerca esegue l'escape delle virgolette quando serializza il testo di ricerca. La frase di ricerca può essere inviata come "Roach Motel".

Per impostazione predefinita, tutte le stringhe passate nel parametro search vengono sottoposte ad analisi lessicale. Assicurarsi di comprendere il comportamento di tokenizzazione dell'analizzatore in uso. Spesso, quando i risultati delle query sono imprevisti, è possibile tracciare il motivo per cui i termini vengono tokenizzati in fase di query. È possibile testare la tokenizzazione in stringhe specifiche per confermare l'output.

Qualsiasi testo di input con uno o più termini è considerato un valido punto di partenza per l'esecuzione di una query. Azure AI Search troverà le corrispondenze con i documenti contenenti uno o tutti i termini, incluse eventuali varianti trovate durante l'analisi del testo.

Per quanto possa sembrare semplice, esiste un aspetto dell'esecuzione delle query in Azure AI Search che potrebbe generare risultati imprevisti, aumentando invece di ridurre i risultati della ricerca quando altri termini e operatori vengono aggiunti alla stringa di input. Che questa espansione si verifichi o meno dipende dall'inclusione di un operatore NOT, combinato con un'impostazione del parametro searchMode che determina come NOT viene interpretato dal punto di vista dei comportamenti di AND o OR. Per altre informazioni, vedere la sezione operatore NOTalla voce 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 uno dei due termini. Nell'esempio, il motore di query restituirà una corrispondenza nei documenti contenenti pool o ocean o entrambi. Poiché OR è l'operatore di congiunzione predefinito, è anche possibile escluderlo, 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 parametro searchMode 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 livello di richiamo delle query includendo più risultati e per impostazione predefinita il segno - verrà interpretato come "OR NOT". Ad esempio, pool - ocean troverà la corrispondenza con documenti contenenti il termine pool o quelli non contenenti il termine ocean.

L'uso di searchMode=all aumenta il livello di precisione delle query includendo meno risultati e per impostazione predefinita il segno - verrà interpretato come "AND NOT". Ad esempio, con searchMode=any la query pool - ocean corrisponderà ai documenti che contengono il termine "piscina" e con tutti i documenti che non contengono il termine "oceano". Si tratta di un comportamento verosimilmente più intuitivo per l'operatore -. Valutare quindi l'opportunità di usare searchMode=all invece di searchMode=any se si vuole ottimizzare il livello di precisione delle ricerche invece che quello di richiamo e gli utenti usano spesso l'operatore - nelle ricerche.

Quando si decide un'impostazione di searchMode, prendere in considerazione i modelli di interazione utente per le query nelle varie applicazioni. È più probabile che gli utenti che cercano informazioni includano un operatore in una query, anziché siti di e-commerce maggiormente dotati di strutture di navigazione 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 di suffisso.

Carattere Esempio Utilizzo
* lingui* corrisponderà a "linguistico" o "linguine" 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 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 edge n-gram, potrebbe essere 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 dell'infisso con la parte finale o interna di un termine, utilizzare 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 anteponendo una barra rovesciata singola (\) nella query. Si supponga, ad esempio, di aver usato un analizzatore personalizzato per la tokenizzazione di termini interi e che l'indice contenga la stringa "Luxury+Hotel". Per ottenere una corrispondenza esatta su questo token, inserire un carattere escape: search=luxury\+hotel.

Per semplificare i casi più comuni, sono previste due eccezioni a questa regola, in cui i caratteri escape non sono necessari:

  • L'operatore NOT - deve essere preceduto da un carattere escape solo se è il primo carattere dopo uno spazio vuoto. Se il - 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 escape solo se è l'ultimo carattere prima di uno spazio vuoto. Se il * viene visualizzato al centro (ad esempio, in 4*4=16), non è necessario effettuare 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 è necessario che caratteri speciali rimangano nella stringa di query, potrebbe essere necessario un analizzatore che li conserva nell'indice. Alcune scelte includono analizzatori dl linguaggio naturale Microsoft, che conservano parole con trattini, o un analizzatore personalizzato per modelli più complessi. Per altre informazioni, vedere Termini parziali, pattern 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 perché delimitano i parametri e specificano i valori in Azure AI Search. Per maggiori 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, incluso l'analizzatore standard predefinito, escluderanno i caratteri speciali durante l'indicizzazione, il che significa che tali caratteri non verranno rappresentati nell'indice.

Se è necessaria una rappresentazione di caratteri speciali, è possibile assegnare un analizzatore che li mantenga:

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

  • Un analizzatore del linguaggio come l'analizzatore Microsoft per l'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 è lecito attendersi, non è possibile ottenere una tokenizzazione completa da un singolo analizzatore. Una soluzione alternativa consiste nel creare più campi contenenti 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 '❤' usare la sequenza di escape %E2%9D%A4+). Alcuni client Web 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) cercherà i documenti contenenti i termini "motel" e "wifi" o "luxury" (oppure entrambi).

Limiti di dimensione delle query

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

  • Per GET, la lunghezza dell'URL non può superare gli 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 è 16 MB. I limiti aggiuntivi includono:

    • La lunghezza massima della clausola di ricerca è 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 con prefisso.
    • È previsto anche un limite di circa 32 kB per la dimensione di ogni singolo termine di 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 Ricerca full-text in Azure AI Search 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: