Sintassi di query semplice in Azure AI Search

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 Simple Query Parser è l'impostazione predefinita. Illustra i casi d'uso comuni e tenta di interpretare una richiesta anche se non è perfettamente composta. L'altro parser è Lucene Query Parser e supporta costruzioni di query più avanzate.

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

La sintassi delle query per entrambi i parser si applica alle espressioni di query passate nel parametro search di una richiesta di query. Non deve essere confusa con la sintassi OData, la quale ha una propria sintassi e delle proprie regole specifiche per le espressioni filter e orderby nella stessa richiesta.

Anche se il parser semplice si basa sulla classe Apache Lucene Simple Query Parser, l'implementazione in Azure AI Search esclude la ricerca fuzzy. Se hai bisogno di una ricerca fuzzy, prendi in considerazione invece la sintassi completa delle query Lucene come 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 sia impostato di seguito, esso è predefinito e può essere tralasciato a meno che non si stia tornando da un tipo alternativo. L'esempio seguente è una ricerca su termini indipendenti, con un requisito che tutti i documenti corrispondenti includano "pool".

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

Il searchMode parametro è 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 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 search parametro 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. Il search parametro è facoltativo. Non specificato, la 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 uno 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. In una richiesta POST, ad esempio, una ricerca "Roach Motel" di frasi nel corpo della richiesta potrebbe essere specificata come "\"Roach Motel\"". Se si usano gli SDK di Azure, il client di ricerca sfugge le 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 search parametro vengono sottoposte a analisi lessicali. 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 input di testo con uno o più termini è considerato un punto di partenza valido per l'esecuzione di query. Azure AI Search corrisponderà ai documenti contenenti uno o tutti i termini, incluse eventuali variazioni rilevate durante l'analisi del testo.

Per quanto possa sembrare semplice, c'è un aspetto dell'esecuzione delle query in Azure AI Search che potrebbe produrre risultati imprevisti, aumentando piuttosto che riducendo i risultati della ricerca quando vengono aggiunti più termini e operatori alla stringa di input. L'effettiva esecuzione di questa espansione dipende dall'inclusione di un operatore NOT, combinata con un'impostazione del 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 uno dei due termini. Nell'esempio, il motore di query restituirà una corrispondenza nei documenti contenenti pool, ocean o entrambi. Poiché OR è l'operatore di congiunzione predefinito, è anche possibile estrarlo, in modo che pool ocean sia l'equivalente di pool | ocean.
- pool – ocean Un'operazione NOT restituisce corrispondenze nei documenti che escludono quel 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 includono 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 a 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à 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". Questo è probabilmente un comportamento più intuitivo per l'operatore - . Pertanto, è consigliabile usare searchMode=all invece di searchMode=any se si desidera ottimizzare le ricerche di precisione anziché richiamo e gli utenti usano spesso l'operatore - nelle ricerche.

Quando si sceglie un'impostazione searchMode, bisogna considerare 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, rispetto ai siti di e-commerce che dispongono 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 di testo normale prima di poter aggiungere l'operatore di suffisso.

Carattere Esempio Utilizzo
* lingui* corrisponderà a "linguistico" o "linguini" L'asterisco (*) rappresenta uno o più caratteri di lunghezza arbitraria, senza distinguere 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 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 di termini interi 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. Se l'oggetto - appare al centro (ad esempio, in 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD), è possibile ignorare l'operazione di escape.

  • L'operatore suffisso * deve essere seguito da un carattere di escape solo se è l'ultimo carattere prima di uno spazio bianco. Se l'oggetto * viene visualizzato al centro (ad esempio, in 4*4=16), non è necessario eseguire alcuna 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 opzioni includono gli analizzatori della lingua naturale di Microsoft, che mantiene le parole con trattini, o un analizzatore personalizzato per modelli più complessi. Per altre informazioni, vedere Termini, modelli e caratteri speciali parziali.

Codifica di caratteri non sicuri e riservati 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 in %23 se usato in un URL. '& ' e '=' sono esempi di caratteri riservati come delimitano i parametri e specificano i valori in Azure AI Search. 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 i 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 di spazi vuoti considera qualsiasi sequenza di caratteri separata da spazi vuoti come token ( quindi l'emoji '❤' verrebbe considerata un token).

  • Un analizzatore language, ad esempio l'analizzatore inglese Microsoft (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 si potrebbe prevedere, 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_endescription_fre così via per gli analizzatori del linguaggio.

Quando si usano caratteri Unicode, assicurarsi che i simboli siano correttamente preceduti da una sequenza di escape nell'URL della query (ad esempio, per '❤' userebbe la sequenza di escape %E2%9D%A4+). Alcuni client Web eseguono automaticamente questa traduzione.

Precedenza (raggruppamento)

È possibile usare le parentesi per creare sottoquery, includendo gli operatori all'interno dell'istruzione tra parentesi. Ad esempio, motel+(wifi|luxury) cercherà i documenti contenenti il termine "motel" e "wifi" o "luxury" (o 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, ad filter 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 Ricerca di testo completa 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:

  • Last updated on