Usare la sintassi di ricerca Lucene "completa" (query avanzate in Azure ricerca cognitiva)Use the "full" Lucene search syntax (advanced queries in Azure Cognitive Search)

Quando si creano query per Azure ricerca cognitiva, è possibile sostituire il parser di query semplice predefinito con il parser di query Lucene più potente per formulare espressioni di query specializzate e avanzate.When constructing queries for Azure Cognitive Search, you can replace the default simple query parser with the more powerful Lucene query parser to formulate specialized and advanced query expressions.

Il parser Lucene supporta formati di query complessi, ad esempio query con ambito campo, ricerca fuzzy, infissi e ricerca con caratteri jolly suffisso, ricerca di prossimità, boosting dei termini e ricerca di espressioni regolari.The Lucene parser supports complex query formats, such as field-scoped queries, fuzzy search, infix and suffix wildcard search, proximity search, term boosting, and regular expression search. Il livello più avanzato comporta requisiti di elaborazione aggiuntivi. È pertanto opportuno prevedere un tempo di esecuzione leggermente superiore.The additional power comes with additional processing requirements so you should expect a slightly longer execution time. In questo articolo è possibile esaminare gli esempi che illustrano le operazioni di query in base alla sintassi completa.In this article, you can step through examples demonstrating query operations based on full syntax.

Nota

Molte delle costruzioni di query specializzate possibili attraverso la sintassi di query Lucene completa non vengono analizzate dal punto di vista del testo, fatto che può sembrare sorprendente se ci si aspetta lo stemming o la lemmatizzazione.Many of the specialized query constructions enabled through the full Lucene query syntax are not text-analyzed, which can be surprising if you expect stemming or lemmatization. L'analisi lessicale viene eseguita solo su termini completi, la query di un termine o di una locuzione.Lexical analysis is only performed on complete terms (a term query or phrase query). I tipi di query con termini incompleti, ad esempio query di prefisso, di caratteri jolly, di espressioni regolari, fuzzy, vengono aggiunte direttamente alla struttura della query, ignorando la fase di analisi.Query types with incomplete terms (prefix query, wildcard query, regex query, fuzzy query) are added directly to the query tree, bypassing the analysis stage. L'unica trasformazione eseguita su termini di query parziali è minuscole.The only transformation performed on partial query terms is lowercasing.

Indice di esempio degli hotelHotels sample index

Le query seguenti sono basate su Hotels-sample-index, che è possibile creare seguendo le istruzioni riportate in questa Guida introduttiva.The following queries are based on the hotels-sample-index, which you can create by following the instructions in this quickstart.

Le query di esempio sono articolate usando l'API REST e le richieste POST.Example queries are articulated using the REST API and POST requests. È possibile incollare ed eseguire tali elementi in un post o in Visual Studio Code con l'estensione ricerca cognitiva.You can paste and run them in Postman or in Visual Studio Code with the Cognitive Search extension.

Le intestazioni della richiesta devono contenere i valori seguenti:Request headers must have the following values:

ChiaveKey valoreValue
Content-TypeContent-Type application/jsonapplication/json
api-keyapi-key <your-search-service-api-key>, una query o una chiave amministratore<your-search-service-api-key>, either query or admin key

I parametri URI devono includere l'endpoint del servizio di ricerca con il nome dell'indice, le raccolte docs, il comando di ricerca e la versione dell'API, in modo simile all'esempio seguente:URI parameters must include your search service endpoint with the index name, docs collections, search command, and API version, similar to the following example:

https://{{service-name}}.search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2020-06-30

Il corpo della richiesta deve essere formato come JSON valido:Request body should be formed as valid JSON:

{
    "search": "*",
    "queryType": "full",
    "select": "HotelId, HotelName, Category, Tags, Description",
    "count": true
}
  • "Search" impostato su * è una query non specificata, equivalente a null o a una ricerca vuota."search" set to * is an unspecified query, equivalent to null or empty search. Non è particolarmente utile, ma è la ricerca più semplice che è possibile eseguire e Mostra tutti i campi recuperabili nell'indice, con tutti i valori.It's not especially useful, but it is the simplest search you can do, and it shows all retrievable fields in the index, with all values.

  • "queryType" impostato su "full" richiama il parser di query Lucene completo ed è necessario per questa sintassi."queryType" set to "full" invokes the full Lucene query parser and it's required for this syntax.

  • "Select" impostato su un elenco delimitato da virgole di campi viene usato per la composizione dei risultati della ricerca, inclusi solo i campi che risultano utili nel contesto dei risultati della ricerca."select" set to a comma-delimited list of fields is used for search result composition, including just those fields that are useful in the context of search results.

  • "count" restituisce il numero di documenti corrispondenti ai criteri di ricerca."count" returns the number of documents matching the search criteria. In una stringa di ricerca vuota, il conteggio sarà costituito da tutti i documenti nell'indice (50 nel caso di Hotels-sample-index).On an empty search string, the count will be all documents in the index (50 in the case of hotels-sample-index).

Ambito di ricerca in campo, singole espressioni di ricerca incorporate in un campo specifico.Fielded search scope individual, embedded search expressions to a specific field. Questo esempio cerca i nomi degli alberghi con il termine "Hotel", ma non con "Motel".This example searches for hotel names with the term "hotel" in them, but not "motel". È possibile specificare più campi utilizzando e.You can specify multiple fields using AND.

Quando si usa questa sintassi di query, è possibile omettere il parametro "searchFields" quando i campi di cui si vuole eseguire una query si trovano nell'espressione di ricerca stessa.When you use this query syntax, you can omit the "searchFields" parameter when the fields you want to query are in the search expression itself. Se si include "searchFields" con la ricerca in campo, ha fieldName:searchExpression sempre la precedenza su "searchFields".If you include "searchFields" with fielded search, the fieldName:searchExpression always takes precedence over "searchFields".

POST /indexes/hotel-samples-index/docs/search?api-version=2020-06-30
{
    "search": "HotelName:(hotel NOT motel) AND Category:'Resort and Spa'",
    "queryType": "full",
    "select": "HotelName, Category",
    "count": true
}

La risposta per questa query dovrebbe essere simile all'esempio seguente, filtrato in "Resort and Spa", restituendo gli hotel che includono "Hotel" o "Motel" nel nome.Response for this query should look similar to the following example, filtered on "Resort and Spa", returning hotels that include "hotel" or "motel" in the name.

"@odata.count": 4,
"value": [
    {
        "@search.score": 4.481559,
        "HotelName": "Nova Hotel & Spa",
        "Category": "Resort and Spa"
    },
    {
        "@search.score": 2.4524608,
        "HotelName": "King's Palace Hotel",
        "Category": "Resort and Spa"
    },
    {
        "@search.score": 2.3970203,
        "HotelName": "Triple Landscape Hotel",
        "Category": "Resort and Spa"
    },
    {
        "@search.score": 2.2953436,
        "HotelName": "Peaceful Market Hotel & Spa",
        "Category": "Resort and Spa"
    }
]

L'espressione di ricerca può essere costituita da un solo termine o una frase o da un'espressione più complessa tra parentesi, facoltativamente con operatori booleani.The search expression can be a single term or a phrase, or a more complex expression in parentheses, optionally with Boolean operators. Ecco alcuni esempi:Some examples include the following:

  • HotelName:(hotel NOT motel)
  • Address/StateProvince:("WA" OR "CA")
  • Tags:("free wifi" NOT "free parking") AND "coffee in lobby"

Assicurarsi di inserire una frase tra virgolette se si desidera che entrambe le stringhe vengano valutate come una singola entità, come in questo caso la ricerca di due posizioni distinte nel campo Address/StateProvince.Be sure to put a phrase within quotation marks if you want both strings to be evaluated as a single entity, as in this case searching for two distinct locations in the Address/StateProvince field. A seconda del client, potrebbe essere necessario utilizzare caratteri di escape ( \ ) per le virgolette.Depending on the client, you might need to escape (\) the quotation marks.

Il campo specificato in fieldName:searchExpression deve essere un campo ricercabile.The field specified in fieldName:searchExpression must be a searchable field. Per informazioni dettagliate sul modo in cui vengono attribuiti le definizioni dei campi, vedere create index (API REST) .See Create Index (REST API) for details on how field definitions are attributed.

La ricerca fuzzy corrisponde a termini simili, incluse le parole errate.Fuzzy search matches on terms that are similar, including misspelled words. Per eseguire una ricerca fuzzy, aggiungere il simbolo tilde ~ alla fine di una parola con un parametro facoltativo, un valore compreso tra 0 e 2, che specifica la distanza di edit.To do a fuzzy search, append the tilde ~ symbol at the end of a single word with an optional parameter, a value between 0 and 2, that specifies the edit distance. Ad esempio, blue~ o blue~1 restituirà blue, blues e glue.For example, blue~ or blue~1 would return blue, blues, and glue.

POST /indexes/hotel-samples-index/docs/search?api-version=2020-06-30
{
    "search": "Tags:conserge~",
    "queryType": "full",
    "select": "HotelName, Category, Tags",
    "searchFields": "HotelName, Category, Tags",
    "count": true
}

La risposta per questa query viene risolta in "concierge" nei documenti corrispondenti, tagliata per brevità:Response for this query resolves to "concierge" in the matching documents, trimmed for brevity:

"@odata.count": 12,
"value": [
    {
        "@search.score": 1.1832147,
        "HotelName": "Secret Point Motel",
        "Category": "Boutique",
        "Tags": [
            "pool",
            "air conditioning",
            "concierge"
        ]
    },
    {
        "@search.score": 1.1819803,
        "HotelName": "Twin Dome Motel",
        "Category": "Boutique",
        "Tags": [
            "pool",
            "free wifi",
            "concierge"
        ]
    },
    {
        "@search.score": 1.1773309,
        "HotelName": "Smile Hotel",
        "Category": "Suite",
        "Tags": [
            "view",
            "concierge",
            "laundry service"
        ]
    },

Le frasi non sono supportate direttamente, ma è possibile specificare una corrispondenza fuzzy per ogni termine di una frase in più parti, ad esempio search=Tags:landy~ AND sevic~ .Phrases aren't supported directly but you can specify a fuzzy match on each term of a multi-part phrase, such as search=Tags:landy~ AND sevic~. Questa espressione di query trova 15 corrispondenze in "servizio di lavanderia".This query expression finds 15 matches on "laundry service".

Nota

Le query fuzzy non vengono analizzate.Fuzzy queries are not analyzed. I tipi di query con termini incompleti, ad esempio query di prefisso, di caratteri jolly, di espressioni regolari, fuzzy, vengono aggiunte direttamente alla struttura della query, ignorando la fase di analisi.Query types with incomplete terms (prefix query, wildcard query, regex query, fuzzy query) are added directly to the query tree, bypassing the analysis stage. L'unica trasformazione eseguita su termini di query parziali è la maiuscola e minuscola.The only transformation performed on partial query terms is lower casing.

La ricerca per prossimità trova termini vicini tra loro in un documento.Proximity search finds terms that are near each other in a document. Inserire un carattere tilde "~" alla fine di una frase seguito dal numero di parole che creano il limite di prossimità.Insert a tilde "~" symbol at the end of a phrase followed by the number of words that create the proximity boundary.

Questa query cerca i termini "Hotel" e "Airport" entro 5 parole l'uno dall'altro in un documento.This query searches for the terms "hotel" and "airport" within 5 words of each other in a document. Le virgolette sono precedute da un carattere di escape ( \" ) per mantenere la frase:The quotation marks are escaped (\") to preserve the phrase:

POST /indexes/hotel-samples-index/docs/search?api-version=2020-06-30
{
    "search": "Description: \"hotel airport\"~5",
    "queryType": "full",
    "select": "HotelName, Description",
    "searchFields": "HotelName, Description",
    "count": true
}

La risposta per questa query dovrebbe essere simile all'esempio seguente:Response for this query should look similar to the following example:

"@odata.count": 2,
"value": [
    {
        "@search.score": 0.6331726,
        "HotelName": "Trails End Motel",
        "Description": "Only 8 miles from Downtown.  On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, All non-smoking hotel. Only 15 miles from airport."
    },
    {
        "@search.score": 0.43032226,
        "HotelName": "Catfish Creek Fishing Cabins",
        "Description": "Brand new mattresses and pillows.  Free airport shuttle. Great hotel for your business needs. Comp WIFI, atrium lounge & restaurant, 1 mile from light rail."
    }
]

Esempio 4: incremento del termineExample 4: Term boosting

Questa definizione si riferisce alla termine si riferisce alla classificazione più alta di un documento se contiene il termine con aumento di priorità, rispetto a documenti che non contengono il termine.Term boosting refers to ranking a document higher if it contains the boosted term, relative to documents that do not contain the term. Per incrementare un termine, usare il punto di inserimento, ^ , simbolo con un fattore di incremento (un numero) alla fine del periodo di ricerca.To boost a term, use the caret, ^, symbol with a boost factor (a number) at the end of the term you are searching. Il valore predefinito del fattore di incremento è 1, anche se deve essere positivo, può essere minore di 1 (ad esempio, 0,2).The boost factor default is 1, and although it must be positive, it can be less than 1 (for example, 0.2). L'aumento priorità dei termini si differenzia dai profili di punteggio per il fatto che questi ultimi aumentano la priorità di alcuni campi e non di termini specifici.Term boosting differs from scoring profiles in that scoring profiles boost certain fields, rather than specific terms.

In questa query "before" cercare "accesso alla spiaggia" e notare che sono presenti sette documenti corrispondenti in uno o entrambi i termini.In this "before" query, search for "beach access" and notice that there are seven documents that match on one or both terms.

POST /indexes/hotel-samples-index/docs/search?api-version=2020-06-30
{
    "search": "beach access",
    "queryType": "full",
    "select": "HotelName, Description, Tags",
    "searchFields": "HotelName, Description, Tags",
    "count": true
}

In realtà, esiste un solo documento che corrisponde a "accesso" e poiché è l'unica corrispondenza, la posizione è alta (seconda posizione) anche se nel documento manca il termine "spiaggia".In fact, there is only one document that matches on "access", and because it is the only match, it's placement is high (second position) even though the document is missing the term "beach".

"@odata.count": 7,
"value": [
    {
        "@search.score": 2.2723424,
        "HotelName": "Nova Hotel & Spa",
        "Description": "1 Mile from the airport.  Free WiFi, Outdoor Pool, Complimentary Airport Shuttle, 6 miles from the beach & 10 miles from downtown."
    },
    {
        "@search.score": 1.5507699,
        "HotelName": "Old Carrabelle Hotel",
        "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center."
    },
    {
        "@search.score": 1.5358944,
        "HotelName": "Whitefish Lodge & Suites",
        "Description": "Located on in the heart of the forest. Enjoy Warm Weather, Beach Club Services, Natural Hot Springs, Airport Shuttle."
    },
    {
        "@search.score": 1.3433652,
        "HotelName": "Ocean Air Motel",
        "Description": "Oceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Various shops and art entertainment are on the boardwalk, just steps away."
    },

Nella query "After" (dopo) ripetere la ricerca, in questo caso l'incremento dei risultati con il termine "Beach" sul termine "Access".In the "after" query, repeat the search, this time boosting results with the term "beach" over the term "access". Una versione leggibile della query è search=Description:beach^2 access .A human readable version of the query is search=Description:beach^2 access. A seconda del client, potrebbe essere necessario esprimere ^2 come %5E2 .Depending on your client, you might need to express ^2 as %5E2.

Dopo aver incrementato il termine "spiaggia", la corrispondenza nell'hotel Carrabelle precedente si sposta al sesto posto.After boosting the term "beach", the match on Old Carrabelle Hotel moves down to sixth place.

Esempio 5: RegexExample 5: Regex

Una ricerca con espressione regolare trova una corrispondenza in base al contenuto incluso tra le barre "/", come indicato nella classe RegExp.A regular expression search finds a match based on the contents between forward slashes "/", as documented in the RegExp class.

POST /indexes/hotel-samples-index/docs/search?api-version=2020-06-30
{
    "search": "HotelName:/(Mo|Ho)tel/",
    "queryType": "full",
    "select": "HotelName",
    "count": true
}

La risposta per questa query dovrebbe essere simile all'esempio seguente:Response for this query should look similar to the following example:

    "@odata.count": 22,
    "value": [
        {
            "@search.score": 1.0,
            "HotelName": "Days Hotel"
        },
        {
            "@search.score": 1.0,
            "HotelName": "Triple Landscape Hotel"
        },
        {
            "@search.score": 1.0,
            "HotelName": "Smile Hotel"
        },
        {
            "@search.score": 1.0,
            "HotelName": "Pelham Hotel"
        },
        {
            "@search.score": 1.0,
            "HotelName": "Sublime Cliff Hotel"
        },
        {
            "@search.score": 1.0,
            "HotelName": "Twin Dome Motel"
        },
        {
            "@search.score": 1.0,
            "HotelName": "Nova Hotel & Spa"
        },
        {
            "@search.score": 1.0,
            "HotelName": "Scarlet Harbor Hotel"
        },

Nota

Le query Regex non vengono analizzate.Regex queries are not analyzed. L'unica trasformazione eseguita su termini di query parziali è la maiuscola e minuscola.The only transformation performed on partial query terms is lower casing.

È possibile utilizzare la sintassi generalmente riconosciuta per più * ricerche con caratteri jolly () o Single ( ? ).You can use generally recognized syntax for multiple (*) or single (?) character wildcard searches. Si noti che il parser di query Lucene supporta l'utilizzo di questi simboli con un singolo termine, non una frase.Note the Lucene query parser supports the use of these symbols with a single term, and not a phrase.

In questa query cercare i nomi degli hotel che contengono il prefisso "SC".In this query, search for hotel names that contain the prefix 'sc'. Non è possibile usare * un ? simbolo o come primo carattere di una ricerca.You cannot use a * or ? symbol as the first character of a search.

POST /indexes/hotel-samples-index/docs/search?api-version=2020-06-30
{
    "search": "HotelName:sc*",
    "queryType": "full",
    "select": "HotelName",
    "count": true
}

La risposta per questa query dovrebbe essere simile all'esempio seguente:Response for this query should look similar to the following example:

    "@odata.count": 2,
    "value": [
        {
            "@search.score": 1.0,
            "HotelName": "Scarlet Harbor Hotel"
        },
        {
            "@search.score": 1.0,
            "HotelName": "Scottish Inn"
        }
    ]

Nota

Le query con caratteri jolly non vengono analizzate.Wildcard queries are not analyzed. L'unica trasformazione eseguita su termini di query parziali è la maiuscola e minuscola.The only transformation performed on partial query terms is lower casing.

Passaggi successiviNext steps

Provare a specificare le query nel codice.Try specifying queries in code. I collegamenti seguenti illustrano come configurare le query di ricerca usando gli Azure SDK.The following links explain how to set up search queries using the Azure SDKs.

Un riferimento alla sintassi aggiuntivo, l'architettura di query ed esempi sono disponibili nei collegamenti seguenti:Additional syntax reference, query architecture, and examples can be found in the following links: