Usare la sintassi di ricerca lucene "completa" (query avanzate in Ricerca cognitiva di Azure)

Quando si costruiscono query per Ricerca cognitiva di Azure, è possibile sostituire il parser di query semplice predefinito con il parser di query Lucene più potente per formulare espressioni di query specializzate e avanzate.

Il parser Lucene supporta formati di query complessi, ad esempio query con ambito campo, ricerca fuzzy, prefisso e ricerca con caratteri jolly suffisso, ricerca di prossimità, aumento del termine e ricerca di espressioni regolari. Il livello più avanzato comporta requisiti di elaborazione aggiuntivi. È pertanto opportuno prevedere un tempo di esecuzione leggermente superiore. In questo articolo è possibile esaminare esempi che illustrano le operazioni di query in base alla sintassi completa.

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. L'analisi lessicale viene eseguita solo su termini completi, la query di un termine o di una locuzione. 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. L'unica trasformazione eseguita in termini di query parziali è inferiore.

Indice di esempio degli alberghi

Le query seguenti si basano sull'indice hotels-sample-index, che è possibile creare seguendo le istruzioni riportate in questa guida introduttiva.

Le query di esempio sono articolate usando l'API REST e le richieste POST. È possibile incollare ed eseguirli in Postman o in un altro client Web.

Le intestazioni della richiesta devono avere i valori seguenti:

Chiave valore
Content-Type application/json
api-key <your-search-service-api-key>, query o chiave di amministrazione

I parametri URI devono includere l'endpoint del servizio di ricerca con il nome dell'indice, le raccolte di documenti, il comando di ricerca e la versione dell'API, analogamente all'esempio seguente:

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:

{
    "search": "*",
    "queryType": "full",
    "select": "HotelId, HotelName, Category, Tags, Description",
    "count": true
}
  • "search" impostato su * è una query non specificata, equivalente a null o vuota. Non è particolarmente utile, ma è la ricerca più semplice che è possibile eseguire e mostra tutti i campi recuperabili nell'indice, con tutti i valori.

  • "queryType" impostato su "full" richiama il parser di query Lucene completo ed è necessario per questa sintassi.

  • "select" impostato su un elenco delimitato da virgole di campi viene usato per la composizione dei risultati della ricerca, inclusi solo i campi utili nel contesto dei risultati della ricerca.

  • "count" restituisce il numero di documenti corrispondenti ai criteri di ricerca. In una stringa di ricerca vuota, il conteggio sarà tutti i documenti nell'indice (50 nel caso di hotels-sample-index).

Ambito di ricerca con campi singoli, espressioni di ricerca incorporate in un campo specifico. In questo esempio vengono cercati nomi di hotel con il termine "hotel" in essi, ma non "motel". È possibile specificare più campi usando AND.

Quando si usa questa sintassi di query, è possibile omettere il parametro "searchFields" quando i campi da eseguire query si trovano nell'espressione di ricerca stessa. Se si include "searchFields" con la ricerca in campo, la fieldName:searchExpression precedenza è sempre "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, filtrata su "Resort and Spa", che restituisce hotel che includono "hotel" nel nome, mentre eslcudendo i risultati che includono "motel" nel nome.

"@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 un singolo termine o una frase o un'espressione più complessa tra parentesi, facoltativamente con operatori booleani. Ecco alcuni esempi:

  • 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 singola entità, come in questo caso cercando due posizioni distinte nel campo Address/StateProvince. A seconda del client, potrebbe essere necessario eseguire l'escape (\) delle virgolette.

Il campo specificato in fieldName:searchExpression deve essere un campo ricercabile. Per informazioni dettagliate su come vengono attributi le definizioni dei campi, vedere Creare indice (API REST).

La ricerca fuzzy corrisponde a termini simili, incluse parole non scritte. 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. Ad esempio, blue~ o blue~1 restituirà blue, blues e 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, troncato per brevità:

"@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 in ogni termine di una frase a più parti, ad esempio search=Tags:landy~ AND sevic~. Questa espressione di query trova 15 corrispondenze su "servizio di lavanderia".

Nota

Le query fuzzy non vengono analizzate. 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. L'unica trasformazione eseguita in termini di query parziali è inferiore.

La ricerca di prossimità trova i termini vicini tra loro in un documento. Inserire un carattere tilde "~" alla fine di una frase seguito dal numero di parole che creano il limite di prossimità.

Questa query cerca i termini "hotel" e "aeroporto" entro 5 parole tra loro in un documento. Le virgolette vengono escape (\") per mantenere la frase:

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:

"@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: Aumento del termine

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. Per aumentare un termine, usare il caret, , ^simbolo con un fattore di aumento (un numero) alla fine del termine che stai cercando. Il valore predefinito del fattore di aumento è 1 e, anche se deve essere positivo, può essere minore di 1 (ad esempio, 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.

In questa query "prima" cercare "accesso alla spiaggia" e notare che sono presenti sette documenti corrispondenti a uno o entrambi i termini.

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
}

Infatti, c'è solo un documento che corrisponde a "accesso" e perché è l'unica corrispondenza, il posizionamento è elevato (seconda posizione) anche se il documento manca il termine "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" ripetere la ricerca, questa volta aumenta i risultati con il termine "beach" sul termine "access". Una versione leggibile della query è search=Description:beach^2 access. A seconda del client, potrebbe essere necessario esprimere ^2 come %5E2.

Dopo aver incrementato il termine "spiaggia", la partita su Old Carrabelle Hotel si sposta verso il sesto posto.

Esempio 5: Regex

Una ricerca con espressione regolare trova una corrispondenza in base al contenuto incluso tra le barre "/", come indicato nella classe RegExp.

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:

    "@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. L'unica trasformazione eseguita in termini di query parziali è inferiore.

È possibile usare la sintassi generalmente riconosciuta per ricerche con caratteri jolly multipli () o singoli (*?). Si noti che il parser di query Lucene supporta l'utilizzo di questi simboli con un singolo termine, non una frase.

In questa query cercare nomi di hotel contenenti il prefisso 'sc'. Non è possibile usare un * simbolo o ? come primo carattere di una ricerca.

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:

    "@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. L'unica trasformazione eseguita in termini di query parziali è inferiore.

Passaggi successivi

Provare a specificare le query nel codice. I collegamenti seguenti illustrano come configurare le query di ricerca usando gli SDK di Azure.

Un riferimento alla sintassi aggiuntivo, l'architettura di query ed esempi sono disponibili nei collegamenti seguenti: