Esecuzione di query in Azure ricerca cognitivaQuerying in Azure Cognitive Search

Azure ricerca cognitiva offre un linguaggio di query avanzato per supportare un'ampia gamma di scenari, dalla ricerca di testo disponibile, ai modelli di query altamente specificati.Azure Cognitive Search offers a rich query language to support a broad range of scenarios, from free text search, to highly-specified query patterns. Questo articolo descrive le richieste di query e i tipi di query che è possibile creare.This article describes query requests, and what kinds of queries you can create.

In ricerca cognitiva, una query è una specifica completa di un'operazione di round trip search , con parametri che comunicano l'esecuzione delle query e formano la risposta che viene restituita.In Cognitive Search, a query is a full specification of a round-trip search operation, with parameters that both inform query execution and shape the response coming back. I parametri e i parser determinano il tipo di richiesta di query.Parameters and parsers determine the type of query request. L'esempio di query seguente è una query di testo in formato libero con un operatore booleano che usa i documenti di ricerca (API REST), destinando la raccolta di documenti Hotels-sample-index .The following query example is a free text query with a boolean operator, using the Search Documents (REST API), targeting the hotels-sample-index documents collection.

POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2020-06-30
{
    "queryType": "simple"
    "search": "`New York` +restaurant",
    "searchFields": "Description, Address/City, Tags",
    "select": "HotelId, HotelName, Description, Rating, Address/City, Tags",
    "top": "10",
    "count": "true",
    "orderby": "Rating desc"
}

I parametri utilizzati durante l'esecuzione della query includono:Parameters used during query execution include:

  • queryType imposta il parser, che è il parser di query semplice predefinito (ottimale per la ricerca full-text) o il parser di query Lucene completo usato per i costrutti di query avanzati, come le espressioni regolari, la ricerca di prossimità, la ricerca fuzzy e il carattere jolly, per citarne alcuni.queryType sets the parser, which is either the default simple query parser (optimal for full text search), or the full Lucene query parser used for advanced query constructs like regular expressions, proximity search, fuzzy and wildcard search, to name a few.

  • search fornisce i criteri di corrispondenza, in genere termini interi o frasi, con o senza operatori.search provides the match criteria, usually whole terms or phrases, with or without operators. Qualsiasi campo attribuito come ricercabile nello schema dell'indice è un candidato per questo parametro.Any field that is attributed as searchable in the index schema is a candidate for this parameter.

  • searchFields vincola l'esecuzione di query a campi ricercabili specifici.searchFields constrains query execution to specific searchable fields.

Parametri usati per la modellazione della risposta:Parameters used to shape the response:

  • select Specifica i campi da restituire nella risposta.select specifies which fields to return in the response. In un'istruzione SELECT è possibile utilizzare solo i campi contrassegnati come recuperabili nell'indice.Only fields marked as retrievable in the index can be used in a select statement.

  • top Restituisce il numero specificato di documenti con la migliore corrispondenza.top returns the specified number of best-matching documents. In questo esempio vengono restituiti solo 10 riscontri.In this example, only 10 hits are returned. Per eseguire la pagina dei risultati, è possibile usare top e Skip (non mostrati).You can use top and skip (not shown) to page the results.

  • count indica il numero totale di documenti nell'intero indice corrispondenti, che possono essere maggiori di quelli restituiti.count tells you how many documents in the entire index match overall, which can be more than what are returned.

  • orderby viene utilizzato se si desidera ordinare i risultati in base a un valore, ad esempio una classificazione o una località.orderby is used if you want to sort results by a value, such as a rating or location. In caso contrario, per impostazione predefinita viene usato il Punteggio di pertinenza per classificare i risultati.Otherwise, the default is to use the relevance score to rank results. Un campo deve essere attribuito come ordinabile come candidato per questo parametro.A field must be attributed as sortable to be a candidate for this parameter.

L'elenco precedente è rappresentativo ma non esaustivo.The above list is representative but not exhaustive. Per l'elenco completo dei parametri in una richiesta di query, vedere cercare documenti (API REST).For the full list of parameters on a query request, see Search Documents (REST API).

Tipi di queryTypes of queries

Con alcune eccezioni significative, una richiesta di query esegue l'iterazione sugli indici invertiti strutturati per le analisi veloci, in cui è possibile trovare una corrispondenza in qualsiasi campo, all'interno di un numero qualsiasi di documenti di ricerca.With a few notable exceptions, a query request iterates over inverted indexes that are structured for fast scans, where a match can be found in potentially any field, within any number of search documents. In ricerca cognitiva la metodologia principale per individuare le corrispondenze è la ricerca full-text o i filtri, ma è anche possibile implementare altre esperienze di ricerca note, come il completamento automatico o la ricerca geografica.In Cognitive Search, the primary methodology for finding matches is either full text search or filters, but you can also implement other well-known search experiences like autocomplete, or geo-location search. Nella parte restante di questo articolo vengono riepilogate le query in ricerca cognitiva e vengono forniti collegamenti ad altre informazioni ed esempi.The rest of this article summarizes queries in Cognitive Search and provides links to more information and examples.

Se l'app di ricerca include una casella di ricerca che raccoglie gli input dei termini, la ricerca full-text è probabilmente l'operazione di query che esegue il backup dell'esperienza.If your search app includes a search box that collects term inputs, then full text search is probably the query operation backing that experience. La ricerca full-text accetta i termini o le frasi passati in un search parametro in tutti i campi disponibili per la ricerca nell'indice.Full text search accepts terms or phrases passed in a search parameter in all searchable fields in your index. Gli operatori booleani facoltativi nella stringa di query possono specificare criteri di inclusione o di esclusione.Optional boolean operators in the query string can specify inclusion or exclusion criteria. Il parser semplice e il parser completo supportano la ricerca full-text.Both the simple parser and full parser support full text search.

In ricerca cognitiva, la ricerca full-text è basata sul motore di query di Apache Lucene.In Cognitive Search, full text search is built on the Apache Lucene query engine. Le stringhe di query nella ricerca full-text vengono sottoposte ad analisi lessicali per rendere più efficienti le analisiQuery strings in full text search undergo lexical analysis to make scans more efficient. L'analisi include la combinazione di maiuscole e minuscole per tutti i termini, la rimozione di parole non significative e la riduzione dei termini nei form radice primitivi.Analysis includes lower-casing all terms, removing stop words like "the", and reducing terms to primitive root forms. L'analizzatore predefinito è Lucene standard.The default analyzer is Standard Lucene.

Quando vengono rilevati termini corrispondenti, il motore di query ricostruisce un documento di ricerca contenente la corrispondenza usando la chiave o l'ID del documento per assemblare i valori dei campi, classifica i documenti in ordine di pertinenza e restituisce i primi 50 (per impostazione predefinita) nella risposta o un numero diverso se è stato specificato top .When matching terms are found, the query engine reconstitutes a search document containing the match using the document key or ID to assemble field values, ranks the documents in order of relevance, and returns the top 50 (by default) in the response or a different number if you specified top.

Se si sta implementando una ricerca full-text, è possibile comprendere il modo in cui il contenuto viene suddiviso in token e consentire il debug di eventuali anomalieIf you're implementing full text search, understanding how your content is tokenized will help you debug any query anomalies. Le query su stringhe con trattini o caratteri speciali potrebbero richiedere l'uso di un analizzatore diverso dal Lucene standard predefinito per assicurarsi che l'indice contenga i token corretti.Queries over hyphenated strings or special characters could necessitate using an analyzer other than the default standard Lucene to ensure the index contains the right tokens. È possibile eseguire l'override dell'impostazione predefinita con gli analizzatori di linguaggio o gli analizzatori specializzati che modificano l'analisi lessicale.You can override the default with language analyzers or specialized analyzers that modify lexical analysis. Un esempio è la parola chiave che tratta l'intero contenuto di un campo come singolo token.One example is keyword that treats the entire contents of a field as a single token. Ciò è utile per i dati come i codici postali, gli ID e alcuni nomi di prodotto.This is useful for data like zip codes, IDs, and some product names. Per altre informazioni, vedere ricerca a termini parziali e modelli con caratteri speciali.For more information, see Partial term search and patterns with special characters.

Se si prevede un uso intensivo di operatori booleani, che è più probabile negli indici che contengono blocchi di testo di grandi dimensioni (un campo di contenuto o descrizioni lunghe), assicurarsi di testare le query con il searchMode=Any|All parametro per valutare l'effetto di tale impostazione sulla ricerca booleana.If you anticipate heavy use of Boolean operators, which is more likely in indexes that contain large text blocks (a content field or long descriptions), be sure to test queries with the searchMode=Any|All parameter to evaluate the impact of that setting on boolean search.

Completamento automatico e query suggeriteAutocomplete and suggested queries

I risultati di completamento automatico o suggerito sono alternative a search che attivano richieste di query successive basate su input di stringa parziali (dopo ogni carattere) in un'esperienza di ricerca in base al tipo.Autocomplete or suggested results are alternatives to search that fire successive query requests based on partial string inputs (after each character) in a search-as-you-type experience. È possibile usare autocomplete il suggestions parametro e insieme o separatamente, come descritto in questa esercitazione, ma non è possibile usarli con search .You can use autocomplete and suggestions parameter together or separately, as described in this tutorial, but you cannot use them with search. I termini completati e le query suggerite sono derivati dai contenuti degli indici.Both completed terms and suggested queries are derived from index contents. Il motore non restituirà mai una stringa o un suggerimento inesistente nell'indice.The engine will never return a string or suggestion that is non-existent in your index. Per altre informazioni, vedere completamento automatico (API REST) e Suggerimenti (API REST).For more information, see Autocomplete (REST API) and Suggestions (REST API).

I filtri sono ampiamente usati nelle app che includono ricerca cognitiva.Filters are widely used in apps that include Cognitive Search. Nelle pagine dell'applicazione i filtri vengono spesso visualizzati come facet nelle strutture di navigazione dei collegamenti per i filtri indirizzati dall'utente.On application pages, filters are often visualized as facets in link navigation structures for user-directed filtering. I filtri vengono usati anche internamente per esporre sezioni di contenuto indicizzato.Filters are also used internally to expose slices of indexed content. È possibile, ad esempio, inizializzare una pagina di ricerca utilizzando un filtro per una categoria di prodotti o una lingua se un indice contiene campi sia in inglese che in francese.For example, you might initialize a search page using a filter on a product category, or a language if an index contains fields in both English and French.

Potrebbero inoltre essere necessari filtri per richiamare un modulo di query specializzato, come descritto nella tabella seguente.You might also need filters to invoke a specialized query form, as described in the following table. È possibile usare un filtro con una ricerca non specificata ( search=* ) o con una stringa di query che include termini, frasi, operatori e modelli.You can use a filter with an unspecified search (search=*) or with a query string that includes terms, phrases, operators, and patterns.

Scenario di filtroFilter scenario DescrizioneDescription
Filtri di intervalloRange filters In ricerca cognitiva di Azure, le query di intervallo vengono compilate utilizzando il parametro Filter.In Azure Cognitive Search, range queries are built using the filter parameter. Per ulteriori informazioni ed esempi, vedere esempio di filtro di intervallo.For more information and examples, see Range filter example.
Ricerca geograficaGeo-location search Se un campo ricercabile è di tipo EDM. GeographyPoint, è possibile creare un'espressione di filtro per i controlli di ricerca "trova nelle vicinanze" o per la ricerca basata su mapping.If a searchable field is of Edm.GeographyPoint type, you can create a filter expression for "find near me" or map-based search controls. I campi che guidano la ricerca geografica contengono le coordinate.Fields that drive geo-search contain coordinates. Per altre informazioni e un esempio, vedere esempio di ricerca geografica.For more information and an example, see Geo-search example.
Esplorazione in base a facetFaceted navigation Una struttura di esplorazione basata su facet diventa strumentale nell'esplorazione indirizzata dall'utente quando si richiama un filtro in risposta a un onclick evento in un facet.A facet navigation structure becomes instrumental in user-directed navigation when you invoke a filter in response to an onclick event on a facet. Di conseguenza, i facet e i filtri vengono usati in modo manuale.As such, facets and filters go hand-in-hand. Se si aggiunge l'esplorazione facet, sarà necessario disporre di filtri per completare l'esperienza.If you add facet navigation, you will need filters to complete the experience. Per ulteriori informazioni, vedere la pagina relativa alla modalità di compilazione di un filtro facet.For more information, see How to build a facet filter.

Nota

Il testo utilizzato in un'espressione di filtro non viene analizzato durante l'elaborazione della query.Text that's used in a filter expression is not analyzed during query processing. Si presuppone che l'input di testo sia un modello di carattere Verbatim con distinzione tra maiuscole e minuscole che ha esito positivo o negativo sulla corrispondenza.The text input is presumed to be a verbatim case-sensitive character pattern that either succeeds or fails on the match. Le espressioni di filtro vengono costruite usando la sintassi OData e passate un filter parametro in tutti i campi filtrabili nell'indice.Filter expressions are constructed using OData syntax and passed in a filter parameter in all filterable fields in your index. Per altre informazioni, vedere filtri in ricerca cognitiva di Azure.For more information, see Filters in Azure Cognitive Search.

Ricerca di documentiDocument look-up

A differenza dei moduli di query descritti in precedenza, questo recupera un singolo documento di ricerca in base all'ID, senza ricerca o analisi dell'indice corrispondente.In contrast with the previously described query forms, this one retrieves a single search document by ID, with no corresponding index search or scan. Viene richiesto e restituito solo un documento.Only the one document is requested and returned. Quando un utente seleziona un elemento nei risultati della ricerca, il recupero del documento e il popolamento di una pagina di dettagli con i campi è una risposta tipica e la ricerca di un documento è l'operazione che la supporta.When a user selects an item in search results, retrieving the document and populating a details page with fields is a typical response, and a document look-up is the operation that supports it.

Ricerca avanzata: fuzzy, wildcard, prossimità, RegexAdvanced search: fuzzy, wildcard, proximity, regex

Un modulo di query avanzato dipende dal parser Lucene completo e dagli operatori che attivano un comportamento di query specifico.An advanced query form depends on the Full Lucene parser and operators that trigger a specific query behavior.

Tipo di queryQuery type UtilizzoUsage Altre informazioni ed esempiExamples and more information
Ricerca nel campoFielded search search parametro queryType=fullsearch parameter, queryType=full Compilare un'espressione di query composta destinata a un singolo campo.Build a composite query expression targeting a single field.
Esempio di ricerca nel campoFielded search example
Ricerca fuzzyfuzzy search search parametro queryType=fullsearch parameter, queryType=full Corrispondenze in base alle esigenze di ortografia o di costruzione simile.Matches on terms having a similar construction or spelling.
Esempio di ricerca fuzzyFuzzy search example
ricerca per prossimitàproximity search search parametro queryType=fullsearch parameter, queryType=full Trova i termini vicini tra loro in un documento.Finds terms that are near each other in a document.
Esempio di ricerca per prossimitàProximity search example
incremento del termineterm boosting search parametro queryType=fullsearch parameter, queryType=full Classifica un documento superiore se contiene il termine con boosting, rispetto alle altre che non lo contengono.Ranks a document higher if it contains the boosted term, relative to others that don't.
Esempio di aumento della priorità dei terminiTerm boosting example
ricerca di espressioni regolariregular expression search search parametro queryType=fullsearch parameter, queryType=full Corrispondenze in base al contenuto di un'espressione regolare.Matches based on the contents of a regular expression.
Esempio di espressione regolareRegular expression example
ricerca con caratteri jolly o prefissowildcard or prefix search search con * ~ o ? , queryType=fullsearch parameter with *~ or ?, queryType=full Corrispondenze basate su un prefisso e una tilde (~) o un singolo carattere (?).Matches based on a prefix and tilde (~) or single character (?).
Esempio di ricerca con caratteri jollyWildcard search example

Passaggi successiviNext steps

Per un'analisi più approfondita dell'implementazione di query, vedere gli esempi per ogni sintassi.For a closer look at query implementation, review the examples for each syntax. Se non si ha familiarità con la ricerca full-text, un'occhiata più approfondita del motore di query potrebbe essere una scelta altrettanto adatta.If you are new to full text search, a closer look at what the query engine does might be an equally good choice.