Condividi tramite

Esempi di sintassi di ricerca Lucene completa (query avanzate)

  • Articolo

Quando si costruiscono query per Azure AI Search, è possibile sostituire il parser di query semplice predefinito con il parser di query Lucene, che è più potente, così da poter formulare definizioni di query avanzate e specializzate.

Il parserLucene supporta formati di query complessi, ad esempio query con ambito campo, ricerche fuzzy, infissi e prefissi con caratteri jolly, ricerche di prossimità, aumento priorità termini e ricerche basate su 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 basate sulla 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 per i termini di una query parziale è la conversione in lettere minuscole.

Indice Hotels-sample

Le query seguenti sono basate su 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 incollarli ed eseguirli in un client REST. In alternativa, usare la visualizzazione JSON di Esplora ricerche nel portale di Azure. Nella visualizzazione JSON è possibile incollare gli esempi di query illustrati qui in questo articolo.

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, in modo analogo all'esempio seguente:

https://{{service-name}}.search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-01

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 una ricerca 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 è tutti i documenti nell'indice (50 nell'indice hotels-sample-index).

Gli ambiti di ricerca con campi singoli, espressioni di ricerca incorporate in un campo specifico. Questo esempio cerca 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 su cui eseguire la query si trovano nell'espressione di ricerca stessa. Se si include searchFields con la ricerca con campi, fieldName:searchExpression ha sempre la precedenza su searchFields.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "HotelName:(hotel NOT motel) AND Category:'Boutique'",
    "queryType": "full",
    "select": "HotelName, Category",
    "count": true
}

La risposta per questa query dovrebbe essere simile all'esempio seguente, filtrata in Boutique, restituendo hotel che includono hotel nel nome, escludendo i risultati che includono motel nel nome.

{
  "@odata.count": 5,
  "value": [
    {
      "@search.score": 2.2289815,
      "HotelName": "Stay-Kay City Hotel",
      "Category": "Boutique"
    },
    {
      "@search.score": 1.3862944,
      "HotelName": "City Skyline Antiquity Hotel",
      "Category": "Boutique"
    },
    {
      "@search.score": 1.355046,
      "HotelName": "Old Century Hotel",
      "Category": "Boutique"
    },
    {
      "@search.score": 1.355046,
      "HotelName": "Sublime Palace Hotel",
      "Category": "Boutique"
    },
    {
      "@search.score": 1.355046,
      "HotelName": "Red Tide Hotel",
      "Category": "Boutique"
    }
  ]
}

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 una singola entità, come in questo caso cercando due posizioni distinte nel Address/StateProvince campo. 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 su come vengono attribuite le definizioni dei campi, vedere Creare un indice (API REST).

La ricerca fuzzy corrisponde a termini simili, incluse le parole con errori di ortografia. 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=2024-07-01
{
    "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, tagliati per brevità:

{
  "@odata.count": 9,
  "value": [
    {
      "@search.score": 1.4947624,
      "HotelName": "Twin Vortex Hotel",
      "Category": "Luxury",
      "Tags": [
        "bar",
        "restaurant",
        "concierge"
      ]
    },
    {
      "@search.score": 1.1685618,
      "HotelName": "Stay-Kay City Hotel",
      "Category": "Boutique",
      "Tags": [
        "view",
        "air conditioning",
        "concierge"
      ]
    },
    {
      "@search.score": 1.1465473,
      "HotelName": "Old Century Hotel",
      "Category": "Boutique",
      "Tags": [
        "pool",
        "free wifi",
        "concierge"
      ]
    },
. . .
  ]
}

Le frasi non sono supportate direttamente, ma è possibile specificare una corrispondenza fuzzy per ogni termine di una frase in più parti, come in search=Tags:landy~ AND sevic~. Questa espressione di query trova 15 corrispondenze nel 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 è la combinazione di maiuscole e minuscole inferiori.

La ricerca di prossimità trova termini vicini tra loro in un documento. Inserire un simbolo 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 cinque parole l'uno dall'altro in un documento. Le virgolette sono precedute da un carattere di escape (\") per mantenere la frase:

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "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": 1,
  "value": [
    {
      "@search.score": 0.69167054,
      "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."
    }
  ]
}

Esempio 4: aumento priorità termine

L'aumento di priorità di un 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 la priorità di un termine, usare il carattere accento circonflesso, ^, con un fattore di aumento di priorità (un numero) alla fine del termine da cercare. Il valore predefinito del fattore di boost è 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 questo caso prima della query cercare l'accesso alla spiaggia e notare che sono presenti sei documenti che corrispondono a uno o entrambi i termini.

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

Infatti, solo due documenti corrispondono all'accesso. La prima istanza è in seconda posizione, anche se il documento manca il termine beach.

{
  "@odata.count": 6,
  "value": [
    {
      "@search.score": 1.068669,
      "HotelName": "Johnson's Family Resort",
      "Description": "Family oriented resort located in the heart of the northland. Operated since 1962 by the Smith family, we have grown into one of the largest family resorts in the state. The home of excellent Smallmouth Bass fishing with 10 small cabins, we're a home not only to fishermen but their families as well. Rebuilt in the early 2000's, all of our cabins have all the comforts of home. Sporting a huge **beach** with multiple water toys for those sunny summer days and a Lodge full of games for when you just can't swim anymore, there's always something for the family to do. A full marina offers watercraft rentals, boat launch, powered dock slips, canoes (free to use), & fish cleaning facility. Rent pontoons, 14' fishing boats, 16' fishing rigs or jet ski's for a fun day or week on the water. Pets are accepted in the lakeside cottages.",
      "Tags": [
        "24-hour front desk service",
        "pool",
        "coffee in lobby"
      ]
    },
    {
      "@search.score": 1.0162708,
      "HotelName": "Campus Commander Hotel",
      "Description": "Easy **access** to campus and steps away from the best shopping corridor in the city. From meetings in town or gameday, enjoy our prime location between the union and proximity to the university stadium.",
      "Tags": [
        "free parking",
        "coffee in lobby",
        "24-hour front desk service"
      ]
    },
    {
      "@search.score": 0.9050383,
      "HotelName": "Lakeside B & B",
      "Description": "Nature is Home on the **beach**. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "Tags": [
        "laundry service",
        "concierge",
        "free parking"
      ]
    },
    {
      "@search.score": 0.8955848,
      "HotelName": "Windy Ocean Motel",
      "Description": "Oceanfront hotel overlooking the **beach** features rooms with a private balcony and 2 indoor and outdoor pools. Inspired by the natural beauty of the island, each room includes an original painting of local scenes by the owner. Rooms include a mini fridge, Keurig coffee maker, and flatscreen TV. Various shops and art entertainment are on the boardwalk, just steps away.",
      "Tags": [
        "pool",
        "air conditioning",
        "bar"
      ]
    },
    {
      "@search.score": 0.83636594,
      "HotelName": "Happy Lake Resort & Restaurant",
      "Description": "The largest year-round resort in the area offering more of everything for your vacation – at the best value! What can you enjoy while at the resort, aside from the mile-long sandy **beaches** of the lake? Check out our activities sure to excite both young and young-at-heart guests. We have it all, including being named “Property of the Year” and a “Top Ten Resort” by top publications.",
      "Tags": [
        "pool",
        "bar",
        "restaurant"
      ]
    },
    {
      "@search.score": 0.7808502,
      "HotelName": "Swirling Currents Hotel",
      "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking **access** to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. ",
      "Tags": [
        "air conditioning",
        "laundry service",
        "24-hour front desk service"
      ]
    }
  ]
}

Nella query successiva ripetere la ricerca, questa volta aumentando i risultati con il termine beach sull'accesso a termine. Una versione leggibile della query è search=Description:beach^2 access. A seconda del client, potrebbe essere necessario esprimere ^2 come %5E2.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "Description:beach^2 access",
    "queryType": "full",
    "select": "HotelName, Description, Tags",
    "searchFields": "HotelName, Description, Tags",
    "count": true
}

Dopo aver incrementato il termine spiaggia, la partita su Campus Commander Hotel si sposta al quinto posto.

{
  "@odata.count": 6,
  "value": [
    {
      "@search.score": 2.137338,
      "HotelName": "Johnson's Family Resort",
      "Description": "Family oriented resort located in the heart of the northland. Operated since 1962 by the Smith family, we have grown into one of the largest family resorts in the state. The home of excellent Smallmouth Bass fishing with 10 small cabins, we're a home not only to fishermen but their families as well. Rebuilt in the early 2000's, all of our cabins have all the comforts of home. Sporting a huge beach with multiple water toys for those sunny summer days and a Lodge full of games for when you just can't swim anymore, there's always something for the family to do. A full marina offers watercraft rentals, boat launch, powered dock slips, canoes (free to use), & fish cleaning facility. Rent pontoons, 14' fishing boats, 16' fishing rigs or jet ski's for a fun day or week on the water. Pets are accepted in the lakeside cottages.",
      "Tags": [
        "24-hour front desk service",
        "pool",
        "coffee in lobby"
      ]
    },
    {
      "@search.score": 1.8100766,
      "HotelName": "Lakeside B & B",
      "Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "Tags": [
        "laundry service",
        "concierge",
        "free parking"
      ]
    },
    {
      "@search.score": 1.7911696,
      "HotelName": "Windy Ocean Motel",
      "Description": "Oceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Inspired by the natural beauty of the island, each room includes an original painting of local scenes by the owner. Rooms include a mini fridge, Keurig coffee maker, and flatscreen TV. Various shops and art entertainment are on the boardwalk, just steps away.",
      "Tags": [
        "pool",
        "air conditioning",
        "bar"
      ]
    },
    {
      "@search.score": 1.6727319,
      "HotelName": "Happy Lake Resort & Restaurant",
      "Description": "The largest year-round resort in the area offering more of everything for your vacation – at the best value! What can you enjoy while at the resort, aside from the mile-long sandy beaches of the lake? Check out our activities sure to excite both young and young-at-heart guests. We have it all, including being named “Property of the Year” and a “Top Ten Resort” by top publications.",
      "Tags": [
        "pool",
        "bar",
        "restaurant"
      ]
    },
    {
      "@search.score": 1.0162708,
      "HotelName": "Campus Commander Hotel",
      "Description": "Easy access to campus and steps away from the best shopping corridor in the city. From meetings in town or gameday, enjoy our prime location between the union and proximity to the university stadium.",
      "Tags": [
        "free parking",
        "coffee in lobby",
        "24-hour front desk service"
      ]
    },
    {
      "@search.score": 0.7808502,
      "HotelName": "Swirling Currents Hotel",
      "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. ",
      "Tags": [
        "air conditioning",
        "laundry service",
        "24-hour front desk service"
      ]
    }
  ]
}

Esempio 5: Regex

Una ricerca di espressioni regolari trova una corrispondenza in base al contenuto tra le /barre , come documentato nella classe RegExp.

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

La risposta per questa query dovrebbe essere simile all'esempio seguente (tagliato per brevità):

{
  "@odata.count": 25,
  "value": [
    {
      "@search.score": 1,
      "HotelName": "Country Residence Hotel"
    },
    {
      "@search.score": 1,
      "HotelName": "Downtown Mix Hotel"
    },
    {
      "@search.score": 1,
      "HotelName": "Gastronomic Landscape Hotel"
    },
    . . . 
    {
      "@search.score": 1,
      "HotelName": "Trails End Motel"
    },
    {
      "@search.score": 1,
      "HotelName": "Nordick's Valley Motel"
    },
    {
      "@search.score": 1,
      "HotelName": "King's Cellar Hotel"
    }
  ]
}

Nota

Le query Regex non vengono analizzate. L'unica trasformazione eseguita in termini di query parziali è la combinazione di maiuscole e minuscole inferiori.

È possibile usare una sintassi generalmente riconosciuta per ricerche con caratteri jolly per trovare più caratteri (*) o un singolo carattere (?). Il parser di query Lucene supporta l'uso di questi simboli con un singolo termine e non una frase.

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

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

La risposta per questa query dovrebbe essere simile all'esempio seguente:

{
  "@odata.count": 1,
  "value": [
    {
      "@search.score": 1,
      "HotelName": "Waterfront Scottish Inn"
    }
  ]
}

Nota

Le query con caratteri jolly non vengono analizzate. L'unica trasformazione eseguita in termini di query parziali è la combinazione di maiuscole e minuscole inferiori.

Contenuto correlato

Provare a specificare le query nel codice. Il collegamento seguente illustra come configurare le query di ricerca usando gli SDK di Azure.

Altri riferimenti alla sintassi, architettura di query ed esempi sono disponibili negli articoli seguenti: