Delen via

Voorbeelden van eenvoudige zoekquery's in Azure AI Search

  • Artikel

In Azure AI Search roept de eenvoudige querysyntaxis de standaardqueryparser aan voor zoeken in volledige tekst. De parser is snel en verwerkt veelvoorkomende scenario's, waaronder zoeken in volledige tekst, gefilterde en facetzoekopdrachten en voorvoegselzoekopdrachten. In dit artikel worden voorbeelden gebruikt om eenvoudig syntaxisgebruik te illustreren in een REST API-aanvraag (Search Documents).

Notitie

Een alternatieve querysyntaxis is Lucene, die complexere querystructuren ondersteunt, zoals fuzzy en jokertekens zoeken. Zie Voorbeelden van de volledige Lucene-zoeksyntaxis voor meer informatie.

Voorbeeldindex hotels

De volgende query's zijn gebaseerd op de hotels-sample-index, die u kunt maken door de instructies in Quickstart te volgen: Een zoekindex maken in Azure Portal.

Voorbeeldquery's worden geformuleerd met behulp van de REST API en POST-aanvragen. U kunt deze plakken en uitvoeren in een REST-client. Of gebruik de JSON-weergave van Search Explorer in Azure Portal. In de JSON-weergave kunt u de queryvoorbeelden plakken die hier in dit artikel worden weergegeven.

Aanvraagheaders moeten de volgende waarden hebben:

Sleutel Weergegeven als
Content-Type application/json
api-key <your-search-service-api-key>, query of beheersleutel

URI-parameters moeten uw eindpunt voor de zoekservice bevatten met de indexnaam, docs-verzamelingen, zoekopdracht en API-versie, vergelijkbaar met het volgende voorbeeld:

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

De aanvraagbody moet worden gevormd als geldige JSON:

{
    "search": "*",
    "queryType": "simple",
    "select": "HotelId, HotelName, Category, Tags, Description",
    "count": true
}

  • search ingesteld op * is een niet-opgegeven query, gelijk aan null of lege zoekopdracht. Het is niet bijzonder nuttig, maar het is de eenvoudigste zoekopdracht die u kunt uitvoeren en toont alle opvraagbare velden in de index, met alle waarden.

  • queryType ingesteld op eenvoudig is de standaardinstelling en kan worden weggelaten, maar het wordt opgenomen om te benadrukken dat de queryvoorbeelden in dit artikel worden uitgedrukt in de eenvoudige syntaxis.

  • select ingesteld op een door komma's gescheiden lijst met velden wordt gebruikt voor de samenstelling van zoekresultaten, inclusief alleen de velden die nuttig zijn in de context van zoekresultaten.

  • count retourneert het aantal documenten dat overeenkomt met de zoekcriteria. In een lege zoekreeks zijn alle documenten in de index (50 in de hotels-sample-index).

Voorbeeld 1: Zoeken in volledige tekst

Zoeken in volledige tekst kan een willekeurig aantal zelfstandige termen of tussen aanhalingstekens zijn, met of zonder Booleaanse operatoren.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "pool spa +airport",
    "searchMode": "any",
    "queryType": "simple",
    "select": "HotelId, HotelName, Category, Description",
    "count": true
}

Een trefwoordzoekopdracht die uit belangrijke termen of woordgroepen bestaat, werkt meestal het beste. Tekenreeksvelden ondergaan tekstanalyse tijdens het indexeren en opvragen, het verwijderen van niet-essentiële woorden zoals de, en. Als u wilt zien hoe een querytekenreeks wordt getokeniseerd in de index, geeft u de tekenreeks door in een aanroep Tekst analyseren naar de index.

De searchMode parameter bepaalt precisie en relevante overeenkomsten. Als u meer relevante overeenkomsten wilt, gebruikt u de standaardwaarde, die een resultaat retourneert als een deel van de querytekenreeks overeenkomt. Als u de voorkeur geeft aan precisie, waarbij alle onderdelen van de tekenreeks moeten worden vergeleken, wijzigt searchMode u deze in alle onderdelen. Probeer de voorgaande query op beide manieren om te zien hoe searchMode het resultaat wijzigt.

Het antwoord voor de pool spa +airport-query moet er ongeveer uitzien als in het volgende voorbeeld.

"@odata.count": 4,
"value": [
{
    "@search.score": 6.090657,
    "HotelId": "12",
    "HotelName": "Winter Panorama Resort",
    "Description": "Plenty of great skiing, outdoor ice skating, sleigh rides, tubing and snow biking. Yoga, group exercise classes and outdoor hockey are available year-round, plus numerous options for shopping as well as great spa services. Newly-renovated with large rooms, free 24-hr airport shuttle & a new restaurant. Rooms/suites offer mini-fridges & 49-inch HDTVs.",
    "Category": "Resort and Spa"
},
{
    "@search.score": 4.314683,
    "HotelId": "21",
    "HotelName": "Good Business Hotel",
    "Description": "1 Mile from the airport. Free WiFi, Outdoor Pool, Complimentary Airport Shuttle, 6 miles from Lake Lanier & 10 miles from downtown. Our business center includes printers, a copy machine, fax, and a work area.",
    "Category": "Suite"
},
{
    "@search.score": 3.575948,
    "HotelId": "27",
    "HotelName": "Starlight Suites",
    "Description": "Complimentary Airport Shuttle & WiFi. Book Now and save - Spacious All Suite Hotel, Indoor Outdoor Pool, Fitness Center, Florida Green certified, Complimentary Coffee, HDTV",
    "Category": "Suite"
},
{
    "@search.score": 2.6926985,
    "HotelId": "25",
    "HotelName": "Waterfront Scottish Inn",
    "Description": "Newly Redesigned Rooms & airport shuttle. Minutes from the airport, enjoy lakeside amenities, a resort-style pool & stylish new guestrooms with Internet TVs.",
    "Category": "Suite"
}
]

Let op de zoekscore in het antwoord. Dit is de relevantiescore van de wedstrijd. Standaard retourneert een zoekservice de top 50 overeenkomsten op basis van deze score.

Uniforme scores van 1,0 treden op wanneer er geen rangschikking is, ofwel omdat de zoekopdracht geen zoekopdracht in volledige tekst was of omdat er geen criteria zijn opgegeven. In een lege zoekopdracht (search=*) komen rijen bijvoorbeeld in willekeurige volgorde terug. Wanneer u werkelijke criteria opneemt, ziet u dat zoekscores zich ontwikkelen tot zinvolle waarden.

Voorbeeld 2: Opzoeken op id

Nadat zoekresultaten zijn geretourneerd, is een logische volgende stap het opgeven van een detailpagina met meer velden uit het document. In dit voorbeeld ziet u hoe u één document retourneert met behulp van Document ophalen door de document-id door te geven.

GET /indexes/hotels-sample-index/docs/41?api-version=2024-07-01

Alle documenten hebben een unieke id. Als u de portal gebruikt, selecteert u de index op het tabblad Indexen en bekijkt u vervolgens de velddefinities om te bepalen welk veld de sleutel is. In de REST API retourneert de AANroep GET-index de indexdefinitie in de hoofdtekst van het antwoord.

Het antwoord voor de voorgaande query bestaat uit het document waarvan de sleutel 41 is. Elk veld dat is gemarkeerd als ophaalbaar in de indexdefinitie, kan worden geretourneerd in zoekresultaten en weergegeven in uw app.

{
    "HotelId": "41",
    "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.",
    "Description_fr": "Cet hôtel en bord de mer donnant sur la plage propose des chambres dotées d'un balcon privé et de 2 piscines intérieure et extérieure. Inspiré par la beauté naturelle de l'île, chaque chambre comprend une peinture originale de scènes locales par le propriétaire. Les chambres comprennent un mini-réfrigérateur, une cafetière Keurig et une télévision à écran plat. Divers magasins et divertissements artistiques se trouvent sur la promenade, à quelques pas.",
    "Category": "Suite",
    "Tags": [
    "pool",
    "air conditioning",
    "bar"
    ],
    "ParkingIncluded": true,
    "LastRenovationDate": "2021-05-10T00:00:00Z",
    "Rating": 3.5,
    "Location": {
    "type": "Point",
    "coordinates": [
        -157.846817,
        21.295841
    ],
    "crs": {
        "type": "name",
        "properties": {
        "name": "EPSG:4326"
        }
    }
    },
    "Address": {
    "StreetAddress": "1450 Ala Moana Blvd 2238 Ala Moana Ctr",
    "City": "Honolulu",
    "StateProvince": "HI",
    "PostalCode": "96814",
    "Country": "USA"
    }
}

Voorbeeld 3: Filteren op tekst

Filtersyntaxis is een OData-expressie die u zelf of met search. Wanneer u samen in dezelfde aanvraag wordt gebruikt, filter wordt deze eerst toegepast op de hele index en wordt de search bewerking uitgevoerd op de resultaten van het filter. Filters zijn dus nuttig om de resultaten van de zoekopdracht te verbeteren, doordat het aantal documenten dat moet worden doorzocht, wordt verminderd.

Filters kunnen worden gedefinieerd voor elk veld dat is gemarkeerd als filterable in de indexdefinitie. Voor hotels-sample-index zijn filterbare velden onder andere Categorie, Tags, ParkingIncluded, Rating en de meeste adresvelden .

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "art tours",
    "queryType": "simple",
    "filter": "Category eq 'Boutique'",
    "searchFields": "HotelName,Description,Category",
    "select": "HotelId,HotelName,Description,Category",
    "count": true
}

Het antwoord voor de voorgaande query is gericht op alleen die hotels die zijn gecategoriseerd als Boutique en die de termen kunst of rondleidingen bevatten. In dit geval is er maar één overeenkomst.

"value": [
{
    "@search.score": 1.2814453,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.",
    "Category": "Boutique"
}
]

Voorbeeld 4: Filterfuncties

Filterexpressies kunnen search.ismatch en search.ismatchscoring-functies bevatten, zodat u een zoekquery binnen het filter kunt maken. Deze filterexpressie maakt gebruik van een jokerteken op gratis om voorzieningen te selecteren, waaronder gratis wifi, gratis parkeren, enzovoort.

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
  {
    "search": "",
    "filter": "search.ismatch('free*', 'Tags', 'full', 'any')",
    "select": "HotelName, Tags, Description",
    "count": true
  }

Het antwoord voor de voorgaande query komt overeen met 27 hotels die gratis voorzieningen bieden. U ziet dat de zoekscore een uniforme score is van 1 in de resultaten. Dit komt doordat de zoekexpressie null of leeg is, wat resulteert in exacte filterovereenkomsten, maar geen zoekopdracht in volledige tekst. Relevantiescores worden alleen geretourneerd bij zoeken in volledige tekst. Als u filters zonder searchgebruikt, moet u ervoor zorgen dat u voldoende sorteerbare velden hebt, zodat u de zoekpositie kunt beheren.

  "@odata.count": 27,
  "value": [
    {
      "@search.score": 1,
      "HotelName": "Country Residence Hotel",
      "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door.",
      "Tags": [
        "laundry service",
        "restaurant",
        "free parking"
      ]
    },
    {
      "@search.score": 1,
      "HotelName": "Downtown Mix Hotel",
      "Description": "Mix and mingle in the heart of the city. Shop and dine, mix and mingle in the heart of downtown, where fab lake views unite with a cheeky design.",
      "Tags": [
        "air conditioning",
        "laundry service",
        "free wifi"
      ]
    },
    {
      "@search.score": 1,
      "HotelName": "Starlight Suites",
      "Description": "Complimentary Airport Shuttle & WiFi. Book Now and save - Spacious All Suite Hotel, Indoor Outdoor Pool, Fitness Center, Florida Green certified, Complimentary Coffee, HDTV",
      "Tags": [
        "pool",
        "coffee in lobby",
        "free wifi"
      ]
    },
. . .

Voorbeeld 5: Bereikfilters

Bereikfiltering wordt ondersteund via filterexpressies voor elk gegevenstype. In de volgende voorbeelden ziet u numerieke en tekenreeksbereiken. Gegevenstypen zijn belangrijk in bereikfilters en werken het beste wanneer numerieke gegevens zich in numerieke velden bevinden en tekenreeksgegevens in tekenreeksvelden. Numerieke gegevens in tekenreeksvelden zijn niet geschikt voor bereiken omdat numerieke tekenreeksen niet vergelijkbaar zijn.

De volgende query is een numeriek bereik. In hotels-sample-index is Ratinghet enige filterbare numerieke veld.

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Rating ge 2 and Rating lt 4",
    "select": "HotelId, HotelName, Rating",
    "orderby": "Rating desc",
    "count": true
}

Het antwoord voor deze query moet er ongeveer uitzien als in het volgende voorbeeld, ingekort voor beknoptheid.

"@odata.count": 27,
"value": [
{
    "@search.score": 1,
    "HotelId": "22",
    "HotelName": "Lion's Den Inn",
    "Rating": 3.9
},
{
    "@search.score": 1,
    "HotelId": "25",
    "HotelName": "Waterfront Scottish Inn",
    "Rating": 3.8
},
{
    "@search.score": 1,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Rating": 3.6
},
...

De volgende query is een bereikfilter boven een tekenreeksveld (Address/StateProvince):

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Address/StateProvince ge 'A*' and Address/StateProvince lt 'D*'",
    "select": "HotelId, HotelName, Address/StateProvince",
    "count": true
}

Het antwoord voor deze query moet er ongeveer uitzien als in het volgende voorbeeld, ingekort voor beknoptheid. In dit voorbeeld is het niet mogelijk om op te sorteren StateProvince omdat het veld niet is toegeschreven aan sorteerbaar in de indexdefinitie.

{
  "@odata.count": 9,
  "value": [
    {
      "@search.score": 1,
      "HotelId": "39",
      "HotelName": "White Mountain Lodge & Suites",
      "Address": {
        "StateProvince": "CO"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "9",
      "HotelName": "Smile Up Hotel",
      "Address": {
        "StateProvince": "CA "
      }
    },
    {
      "@search.score": 1,
      "HotelId": "7",
      "HotelName": "Roach Motel",
      "Address": {
        "StateProvince": "CA "
      }
    },
    {
      "@search.score": 1,
      "HotelId": "34",
      "HotelName": "Lakefront Captain Inn",
      "Address": {
        "StateProvince": "CT"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "37",
      "HotelName": "Campus Commander Hotel",
      "Address": {
        "StateProvince": "CA "
      }
    },
. . .

De hotels-sample-index bevat een locatieveld met breedte- en lengtegraadcoördinaten. In dit voorbeeld wordt de functie geo.distance gebruikt die filtert op documenten binnen de omtrek van een beginpunt, naar een willekeurige afstand (in kilometers) die u opgeeft. U kunt de laatste waarde in de query (10) aanpassen om het oppervlak van de query te verkleinen of te vergroten.

POST /indexes/v/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "geo.distance(Location, geography'POINT(-122.335114 47.612839)') le 10",
    "select": "HotelId, HotelName, Address/City, Address/StateProvince",
    "count": true
}

Het antwoord voor deze query retourneert alle hotels binnen een afstand van 10 kilometer van de opgegeven coördinaten:

{
  "@odata.count": 3,
  "value": [
    {
      "@search.score": 1,
      "HotelId": "45",
      "HotelName": "Happy Lake Resort & Restaurant",
      "Address": {
        "City": "Seattle",
        "StateProvince": "WA"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel",
      "Address": {
        "City": "Seattle",
        "StateProvince": "WA"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "16",
      "HotelName": "Double Sanctuary Resort",
      "Address": {
        "City": "Seattle",
        "StateProvince": "WA"
      }
    }
  ]
}

Voorbeeld 7: Booleaanse waarden met searchMode

Eenvoudige syntaxis ondersteunt Booleaanse operatoren in de vorm van tekens (+, -, |) ter ondersteuning van EN, OF en NOT-querylogica. Booleaanse zoekopdracht gedraagt zich zoals u zou verwachten, met een paar opmerkelijke uitzonderingen.

Overweeg in een Booleaanse zoekopdracht de searchMode parameter toe te voegen als mechanisme voor het beïnvloeden van precisie en relevante overeenkomsten. Geldige waarden zijn "searchMode": "any" relevante overeenkomsten (een document dat voldoet aan een van de criteria wordt beschouwd als een overeenkomst) en "searchMode": "all" een voorkeur voor precisie (alle criteria moeten worden vergeleken in een document).

In de context van een Booleaanse zoekopdracht kan de standaardinstelling "searchMode": "any" verwarrend zijn als u een query met meerdere operators stapelt en breder wordt in plaats van smallere resultaten. Dit geldt met name voor NOT, waarbij de resultaten alle documenten bevatten die geen specifieke term of woordgroep bevatten .

In het volgende voorbeeld ziet u een afbeelding. De query zoekt naar overeenkomsten in het restaurant dat de woordgroep airconditioning uitsluit. Als u de volgende query uitvoert met searchMode (any), worden er 43 documenten geretourneerd: documenten die het termrestaurant bevatten, plus alle documenten die niet de woordgroep *airconditioning hebben.

U ziet dat er geen ruimte is tussen de booleaanse operator (-) en de airconditioning van de woordgroep. De aanhalingstekens zijn ontsnapt (\").

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "restaurant -\"air conditioning\"",
    "searchMode": "any",
    "searchFields": "Tags",
    "select": "HotelId, HotelName, Tags",
    "count": true
}

"searchMode": "all" Als u een cumulatief effect op criteria afdwingt en een kleinere resultatenset (zeven overeenkomsten) retourneert die bestaan uit documenten met het term restaurant, minus de documenten met de woordgroep airconditioning.

Het antwoord voor deze query ziet er nu uit zoals in het volgende voorbeeld, ingekort voor beknoptheid.

{
  "@odata.count": 14,
  "value": [
    {
      "@search.score": 3.1383743,
      "HotelId": "18",
      "HotelName": "Ocean Water Resort & Spa",
      "Tags": [
        "view",
        "pool",
        "restaurant"
      ]
    },
    {
      "@search.score": 2.028083,
      "HotelId": "22",
      "HotelName": "Lion's Den Inn",
      "Tags": [
        "laundry service",
        "free wifi",
        "restaurant"
      ]
    },
    {
      "@search.score": 2.028083,
      "HotelId": "34",
      "HotelName": "Lakefront Captain Inn",
      "Tags": [
        "restaurant",
        "laundry service",
        "coffee in lobby"
      ]
    },
...

Voorbeeld 8: Pagingresultaten

In eerdere voorbeelden hebt u geleerd over parameters die van invloed zijn op de samenstelling van zoekresultaten, waaronder select die bepaalt welke velden zich in een resultaat bevinden, sorteervolgordes en hoe u een telling van alle overeenkomsten opneemt. Dit voorbeeld is een vervolg van de samenstelling van zoekresultaten in de vorm van pagingparameters waarmee u het aantal resultaten dat op een bepaalde pagina wordt weergegeven, in batches kunt verwerken.

Standaard retourneert een zoekservice de top 50 overeenkomsten. Als u het aantal overeenkomsten op elke pagina wilt beheren, gebruikt top u deze om de grootte van de batch te definiëren en gebruikt skip u vervolgens om volgende batches op te halen.

In het volgende voorbeeld wordt een filter- en sorteervolgorde voor het Rating veld gebruikt (Classificatie is zowel filterbaar als sorteerbaar), omdat het gemakkelijker is om de effecten van paging op gesorteerde resultaten te zien. In een reguliere volledige zoekquery worden de belangrijkste overeenkomsten gerangschikt en gepaginad op @search.score.

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Rating gt 4",
    "select": "HotelName, Rating",
    "orderby": "Rating desc",
    "top": 5,
    "count": true
}

De query vindt 21 overeenkomende documenten, maar omdat u hebt opgegeven top, retourneert het antwoord alleen de top vijf overeenkomsten, met classificaties vanaf 4,9 en eindigend bij 4,7 met Lakeside B & B.

Als u de volgende vijf wilt ophalen, slaat u de eerste batch over:

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Rating gt 4",
    "select": "HotelName, Rating",
    "orderby": "Rating desc",
    "top": 5,
    "skip": 5,
    "count": true
}

Het antwoord voor de tweede batch slaat de eerste vijf wedstrijden over en retourneert de volgende vijf, beginnend met Pull'r Inn Motel. Als u wilt doorgaan met meer batches, houdt top u vijf bij en vervolgens met skip vijf op elke nieuwe aanvraag (skip=5, skip=10, skip=15, enzovoort).

{
  "@odata.count": 21,
  "value": [
    {
      "@search.score": 1,
      "HotelName": "Head Wind Resort",
      "Rating": 4.7
    },
    {
      "@search.score": 1,
      "HotelName": "Sublime Palace Hotel",
      "Rating": 4.6
    },
    {
      "@search.score": 1,
      "HotelName": "City Skyline Antiquity Hotel",
      "Rating": 4.5
    },
    {
      "@search.score": 1,
      "HotelName": "Nordick's Valley Motel",
      "Rating": 4.5
    },
    {
      "@search.score": 1,
      "HotelName": "Winter Panorama Resort",
      "Rating": 4.5
    }
  ]
}

Gerelateerde inhoud

Nu u enige oefening hebt met de basisquerysyntaxis, kunt u query's in code opgeven. In de volgende koppeling wordt beschreven hoe u zoekquery's instelt met behulp van de Azure SDK's.

Meer syntaxisreferenties, queryarchitectuur en voorbeelden vindt u in de volgende koppelingen: