Sintassi di query semplice in Azure ricerca cognitivaSimple query syntax in Azure Cognitive Search

Azure ricerca cognitiva implementa due linguaggi di query basati su Lucene: il parser di query semplice e il parser di query Lucene.Azure Cognitive Search implements two Lucene-based query languages: Simple Query Parser and the Lucene Query Parser. Il parser semplice è più flessibile e tenterà di interpretare una richiesta anche se non è perfettamente composta.The simple parser is more flexible and will attempt to interpret a request even if it's not perfectly composed. Grazie a questa flessibilità, si tratta dell'impostazione predefinita per le query in Azure ricerca cognitiva.Because of this flexibility, it is the default for queries in Azure Cognitive Search.

La sintassi semplice viene usata per le espressioni di query passate nel search parametro di una richiesta di ricerca di documenti (API REST) , da non confondere con la sintassi OData usata per le $filter $orderby espressioni e nella stessa richiesta.The simple syntax is used for query expressions passed in the search parameter of a Search Documents (REST API) request, not to be confused with the OData syntax used for the $filter and $orderby expressions in the same request. I parametri OData hanno sintassi e regole diverse per la costruzione di query, l'escape di stringhe e così via.OData parameters have different syntax and rules for constructing queries, escaping strings, and so on.

Sebbene il parser semplice sia basato sulla classe del parser di query semplice di Apache Lucene , l'implementazione in ricerca cognitiva esclude la ricerca fuzzy.Although the simple parser is based on the Apache Lucene Simple Query Parser class, the implementation in Cognitive Search excludes fuzzy search. Se è necessaria la ricerca fuzzy, considerare invece la sintassi di query Lucene completa alternativa.If you need fuzzy search, consider the alternative full Lucene query syntax instead.

Esempio (sintassi semplice)Example (simple syntax)

Sebbene queryType sia impostato di seguito, è il valore predefinito e può essere omesso a meno che non si ritorni da un tipo alternativo.Although queryType is set below, it's the default and can be omitted unless you are reverting from an alternative type. Nell'esempio seguente viene illustrata una ricerca su termini indipendenti, con il requisito che tutti i documenti corrispondenti includano "pool".The following example is a search over independent terms, with a requirement that all matching documents include "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 searchMode parametro è pertinente in questo esempio.The searchMode parameter is relevant in this example. Ogni volta che gli operatori booleani sono nella query, è necessario impostare in genere searchMode=all per assicurarsi che tutti i criteri corrispondano.Whenever boolean operators are on the query, you should generally set searchMode=all to ensure that all of the criteria is matched. In caso contrario, è possibile utilizzare l'impostazione predefinita searchMode=any che predilige il richiamo sulla precisione.Otherwise, you can use the default searchMode=any that favors recall over precision.

Per altri esempi, vedere esempi di sintassi di query semplici.For additional examples, see Simple query syntax examples. Per informazioni dettagliate sulla richiesta di query e sui parametri, vedere eseguire ricerche nei documenti (API REST).For details about the query request and parameters, see Search Documents (REST API).

Ricerca di parole chiave su termini e frasiKeyword search on terms and phrases

Le stringhe passate al search parametro possono includere termini o frasi in qualsiasi linguaggio supportato, operatori booleani, operatori di precedenza, caratteri jolly o prefisso per le query "inizia con", caratteri di escape e caratteri di codifica URL.Strings passed to the search parameter can include terms or phrases in any supported language, boolean operators, precedence operators, wildcard or prefix characters for "starts with" queries, escape characters, and URL encoding characters. Il search parametro è facoltativo.The search parameter is optional. Non specificato, la ricerca ( search=* o search=" " ) restituisce i primi 50 documenti in ordine arbitrario (non classificato).Unspecified, search (search=* or search=" ") returns the top 50 documents in arbitrary (unranked) order.

  • Una ricerca termini è una query di uno o più termini, in cui uno dei termini viene considerato una corrispondenza.A term search is a query of one or more terms, where any of the terms are considered a match.

  • Una frase di ricerca è una frase esatta racchiusa tra virgolette " " .A phrase search is an exact phrase enclosed in quotation marks " ". Ad esempio, se Roach Motel (senza virgolette) Cerca documenti contenenti Roach e/o Motel in qualsiasi punto in qualsiasi ordine, "Roach Motel" (con virgolette) corrisponderà solo ai documenti che contengono l'intera frase e in questo ordine (l'analisi lessicale si applica comunque).For example, while Roach Motel (without quotes) would search for documents containing Roach and/or Motel anywhere in any order, "Roach Motel" (with quotes) will only match documents that contain that whole phrase together and in that order (lexical analysis still applies).

    A seconda del client di ricerca, potrebbe essere necessario utilizzare caratteri di escape per le virgolette in una ricerca di frasi.Depending on your search client, you might need to escape the quotation marks in a phrase search. Ad esempio, in Substart in una richiesta POST, una frase di ricerca "Roach Motel" nel corpo della richiesta viene specificata come "\"Roach Motel\"" .For example, in Postman in a POST request, a phrase search on "Roach Motel" in the request body would be specified as "\"Roach Motel\"".

Per impostazione predefinita, tutti i termini o le frasi passati nel search parametro vengono sottoposti ad analisi lessicale.By default, all terms or phrases passed in the search parameter undergo lexical analysis. Assicurarsi di comprendere il comportamento di token dell'analizzatore in uso.Make sure you understand the tokenization behavior of the analyzer you are using. Spesso, quando i risultati della query sono imprevisti, è possibile tracciare il motivo per il modo in cui i termini vengono suddivisi in token in fase di query.Often, when query results are unexpected, the reason can be traced to how terms are tokenized at query time.

Qualsiasi testo con uno o più termini è considerato un valido punto di partenza per l'esecuzione di una query.Any text with one or more terms is considered a valid starting point for query execution. Azure ricerca cognitiva corrisponderà ai documenti che contengono uno o tutti i termini, incluse eventuali variazioni trovate durante l'analisi del testo.Azure Cognitive Search will match documents containing any or all of the terms, including any variations found during analysis of the text.

Con la stessa semplicità di questa operazione, esiste un aspetto dell'esecuzione di query in Azure ricerca cognitiva che potrebbe produrre risultati imprevisti, aumentando invece di diminuire i risultati della ricerca, perché vengono aggiunti altri termini e operatori alla stringa di input.As straightforward as this sounds, there is one aspect of query execution in Azure Cognitive Search that might produce unexpected results, increasing rather than decreasing search results as more terms and operators are added to the input string. Il fatto che questa espansione venga effettivamente eseguita dipende dall'inclusione di un operatore NOT, insieme a un' searchMode impostazione di parametro che determina la modalità di interpretazione di not in termini di comportamenti e o o.Whether this expansion actually occurs depends on the inclusion of a NOT operator, combined with a searchMode parameter setting that determines how NOT is interpreted in terms of AND or OR behaviors. Per altre informazioni, vedere operatore NOT sotto operatori booleani.For more information, see the NOT operator under Boolean operators.

Operatori booleaniBoolean operators

È possibile incorporare gli operatori booleani in una stringa di query per migliorare la precisione di una corrispondenza.You can embed Boolean operators in a query string to improve the precision of a match. Nella sintassi semplice, gli operatori booleani sono basati su caratteri.In the simple syntax, boolean operators are character-based. Gli operatori di testo, ad esempio Word e, non sono supportati.Text operators, such as the word AND, are not supported.

CarattereCharacter EsempioExample UsoUsage
+ pool + ocean Operazione AND.An AND operation. Ad esempio, pool + ocean stabilisce che un documento deve contenere entrambi i termini.For example, pool + ocean stipulates that a document must contain both terms.
| pool | ocean Un'operazione o trova una corrispondenza quando viene trovato uno o più termini.An OR operation finds a match when either term is found. Nell'esempio, il motore di query restituirà match nei documenti contenenti pool o ocean o entrambi.In the example, the query engine will return match on documents containing either pool or ocean or both. Poiché OR è l'operatore di congiunzione predefinito, è anche possibile escluderlo, in modo che pool ocean sia l'equivalente di pool | ocean.Because OR is the default conjunction operator, you could also leave it out, such that pool ocean is the equivalent of pool | ocean.
- pool – ocean Un'operazione NOT restituisce corrispondenze sui documenti che escludono il termine.A NOT operation returns matches on documents that exclude the term.

Per ottenere il comportamento previsto in un'espressione NOT, è consigliabile impostare searchMode=all sulla richiesta.To get the expected behavior on a NOT expression, consider setting searchMode=all on the request. In caso contrario, in base al valore predefinito di searchMode=any , si otterranno corrispondenze in pool , più corrispondenze in tutti i documenti che non contengono ocean , che potrebbero essere numerosi documenti.Otherwise, under the default of searchMode=any, you will get matches on pool, plus matches on all documents that do not contain ocean, which could be a lot of documents. Il searchMode parametro in una richiesta di query controlla se un termine con l'operatore Not è individuato o ORed con altri termini nella query (presupponendo che non esista un + | operatore OR su altri termini).The searchMode parameter on a query request controls whether a term with the NOT operator is ANDed or ORed with other terms in the query (assuming there is no + or | operator on the other terms). L'utilizzo di searchMode=all aumenta la precisione delle query includendo un minor numero di risultati e, per impostazione predefinita, viene interpretato come "and not".Using searchMode=all increases the precision of queries by including fewer results, and by default - will be interpreted as "AND NOT".

Quando si decide di eseguire un' searchMode impostazione, prendere in considerazione i modelli di interazione utente per le query in varie applicazioni.When deciding on a searchMode setting, consider the user interaction patterns for queries in various applications. È più probabile che gli utenti che eseguono la ricerca di informazioni includano un operatore in una query, anziché i siti di e-commerce che dispongono di più strutture di navigazione predefinite.Users who are searching for information are more likely to include an operator in a query, as opposed to e-commerce sites that have more built-in navigation structures.

Query di prefissoPrefix queries

Per le query "inizia con", aggiungere un suffisso operator ( * ) come segnaposto per il resto di un termine.For "starts with" queries, add a suffix operator (*) as the placeholder for the remainder of a term. Una query di prefisso deve iniziare con almeno un carattere alfanumerico prima di poter aggiungere l'operatore del suffisso.A prefix query must begin with at least one alphanumeric character before you can add the suffix operator.

CarattereCharacter EsempioExample UsoUsage
* lingui* corrisponderà a "linguistico" o "linguinei"lingui* will match on "linguistic" or "linguini" L'asterisco ( * ) rappresenta uno o più caratteri di lunghezza arbitraria, ignorando la distinzione tra maiuscole e minuscole.The asterisk (*) represents one or more characters of arbitrary length, ignoring case.

Analogamente ai filtri, una query di prefisso cerca una corrispondenza esatta.Similar to filters, a prefix query looks for an exact match. Di conseguenza, non esiste alcun punteggio di pertinenza (tutti i risultati ricevono un punteggio di ricerca di 1,0).As such, there is no relevance scoring (all results receive a search score of 1.0). Tenere presente che le query di prefisso possono essere lente, soprattutto se l'indice è di grandi dimensioni e il prefisso è costituito da un numero limitato di caratteri.Be aware that prefix queries can be slow, especially if the index is large and the prefix consists of a small number of characters. Una metodologia alternativa, ad esempio la suddivisione in token n-grammi perimetrale, potrebbe risultare più rapida.An alternative methodology, such as edge n-gram tokenization, might perform faster.

La sintassi semplice supporta solo la corrispondenza con prefisso.Simple syntax supports prefix matching only. Per la corrispondenza tra suffissi o infissi rispetto alla fine o al centro di un termine, usare la sintassi Lucene completa per la ricerca con caratteri jolly.For suffix or infix matching against the end or middle of a term, use the full Lucene syntax for wildcard search.

Escape degli operatori di ricercaEscaping search operators

Nella sintassi semplice, gli operatori di ricerca includono i seguenti caratteri: + | " ( ) ' \In the simple syntax, search operators include these characters: + | " ( ) ' \

Se uno di questi caratteri fa parte di un token nell'indice, eseguirne l'escape anteponendo una singola barra rovesciata ( \ ) nella query.If any of these characters are part of a token in the index, escape it by prefixing it with a single backslash (\) in the query. Si supponga, ad esempio, di aver usato un analizzatore personalizzato per la suddivisione in token di termini interi e che l'indice contenga la stringa "Luxury + Hotel".For example, suppose you used a custom analyzer for whole term tokenization, and your index contains the string "Luxury+Hotel". Per ottenere una corrispondenza esatta in questo token, inserire un carattere di escape: search=luxury\+hotel .To get an exact match on this token, insert an escape character: search=luxury\+hotel.

Per semplificare le operazioni per i casi più comuni, esistono due eccezioni a questa regola in cui l'escape non è necessario:To make things simple for the more typical cases, there are two exceptions to this rule where escaping is not needed:

  • L'operatore NOT - deve essere preceduto da un carattere di escape solo se è il primo carattere dopo uno spazio vuoto.The NOT operator - only needs to be escaped if it's the first character after a whitespace. Se l'oggetto - viene visualizzato al centro (ad esempio, in 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD ), è possibile ignorare l'escape.If the - appears in the middle (for example, in 3352CDD0-EF30-4A2E-A512-3B30AF40F3FD), you can skip escaping.

  • L'operatore suffisso * deve essere preceduto da un carattere di escape solo se è l'ultimo carattere prima di uno spazio vuoto.The suffix operator * only needs to be escaped if it's the last character before a whitespace. Se l'oggetto * viene visualizzato al centro (ad esempio, in 4*4=16 ), non è necessario alcun escape.If the * appears in the middle (for example, in 4*4=16), no escaping is needed.

Nota

Per impostazione predefinita, l'analizzatore standard eliminerà e interromperà le parole su trattini, spazi vuoti, e commerciali e altri caratteri durante l' analisi lessicale.By default, the standard analyzer will delete and break words on hyphens, whitespace, ampersands, and other characters during lexical analysis. Se sono necessari caratteri speciali per restare nella stringa di query, potrebbe essere necessario un analizzatore che li mantiene nell'indice.If you require special characters to remain in the query string, you might need an analyzer that preserves them in the index. Alcune opzioni includono gli analizzatori del linguaggionaturale Microsoft, che conserva le parole con trattino o un analizzatore personalizzato per modelli più complessi.Some choices include Microsoft natural language analyzers, which preserves hyphenated words, or a custom analyzer for more complex patterns. Per ulteriori informazioni, vedere termini parziali, modelli e caratteri speciali.For more information, see Partial terms, patterns, and special characters.

Codifica dei caratteri riservati e non sicuri negli URLEncoding unsafe and reserved characters in URLs

Verificare che tutti i caratteri non sicuri e riservati siano codificati in un URL.Ensure all unsafe and reserved characters are encoded in a URL. Ad esempio,' #' è un carattere non sicuro perché è un identificatore di frammento/ancoraggio in un URL.For example, '#' is an unsafe character because it is a fragment/anchor identifier in a URL. Il carattere deve essere codificato al %23, se usato in un URL.The character must be encoded to %23 if used in a URL. ' &' è =' sono esempi di caratteri riservati in quanto delimitano i parametri e specificano i valori in Azure ricerca cognitiva.'&' and '=' are examples of reserved characters as they delimit parameters and specify values in Azure Cognitive Search. Per ulteriori informazioni, vedere RFC1738: Uniform Resource Locators (URL).For more information, see RFC1738: Uniform Resource Locators (URL).

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

Caratteri specialiSpecial characters

In alcuni casi, è possibile cercare un carattere speciale, ad esempio un'❤' emoji o il segno ' €'.In some circumstances, you may want to search for a special character, like an '❤' emoji or the '€' sign. In questi casi, assicurarsi che l'analizzatore usato non filtri tali caratteri. L'analizzatore standard ignora molti caratteri speciali, esclusi dall'indice.In such cases, make sure that the analyzer you use does not filter those characters out. The standard analyzer bypasses many special characters, excluding them from your index.

Gli analizzatori che tokenize i caratteri speciali includono l'analizzatore "spazio", che prende in considerazione le sequenze di caratteri separate da spazi vuoti come token (pertanto la stringa "❤" verrebbe considerata un token).Analyzers that will tokenize special characters include the "whitespace" analyzer, which takes into consideration any character sequences separated by whitespaces as tokens (so the "❤" string would be considered a token). Inoltre, un analizzatore del linguaggio come Microsoft English Analyzer ("en. Microsoft") accetta la stringa "€" come token.Also, a language analyzer like the Microsoft English analyzer ("en.microsoft"), would take the "€" string as a token. È possibile testare un analizzatore per visualizzare i token generati per una query specifica.You can test an analyzer to see what tokens it generates for a given query.

Quando si usano i caratteri Unicode, assicurarsi che i simboli siano preceduti da un carattere di escape nell'URL della query (ad esempio per "❤" utilizzerà la sequenza di escape %E2%9D%A4+ ).When using Unicode characters, make sure symbols are properly escaped in the query url (for instance for "❤" would use the escape sequence %E2%9D%A4+). Postazione esegue automaticamente questa conversione.Postman does this translation automatically.

Precedenza (raggruppamento)Precedence (grouping)

È possibile usare le parentesi per creare sottoquery, inclusi gli operatori nell'istruzione tra parentesi.You can use parentheses to create subqueries, including operators within the parenthetical statement. Ad esempio, motel+(wifi|luxury) cercherà i documenti contenenti i termini "motel" e "wifi" o "luxury" (oppure entrambi).For example, motel+(wifi|luxury) will search for documents containing the "motel" term and either "wifi" or "luxury" (or both).

Limiti delle dimensioni delle queryQuery size limits

Se l'applicazione genera query di ricerca a livello di codice, è consigliabile progettarla in modo che non generi query di dimensioni illimitate.If your application generates search queries programmatically, we recommend designing it in such a way that it does not generate queries of unbounded size.

  • Per GET, la lunghezza dell'URL non può superare 8 KB.For GET, the length of the URL cannot exceed 8 KB.

  • Per POST (e qualsiasi altra richiesta), in cui il corpo della richiesta include search e altri parametri, ad esempio filter e orderby , le dimensioni massime sono pari a 16 MB, dove il numero massimo di clausole in search (espressioni separate da and, or e così via) è 1024.For POST (and any other request), where the body of the request includes search and other parameters such as filter and orderby, the maximum size is 16 MB, where the maximum number of clauses in search (expressions separated by AND, OR, and so on) is 1024. È previsto anche un limite di circa 32 KB per la dimensione di ogni singolo termine di una query.There is also a limit of approximately 32 KB on the size of any individual term in a query. Per altre informazioni, vedere limiti delle richieste API.For more information, see API request limits.

Passaggi successiviNext steps

Se si intende costruire query a livello di codice, esaminare la ricerca full-text in Azure ricerca cognitiva per comprendere le fasi di elaborazione delle query e le implicazioni dell'analisi del testo.If you will be constructing queries programmatically, review Full text search in Azure Cognitive Search to understand the stages of query processing and the implications of text analysis.

Per ulteriori informazioni sulla creazione di query, vedere anche gli articoli seguenti:You can also review the following articles to learn more about query construction: