Documenten zoeken (Azure Cognitive Search REST API)

Artikel
01/10/2023
20 minuten om te lezen

Een queryaanvraag is gericht op de documentenverzameling van één index in een zoekservice. Het bevat parameters die de overeenkomende criteria definiëren en parameters die het antwoord vormgeven. Vanaf de API-versie 2021-04-30-Preview kunt u ook een indexalias gebruiken om een bepaalde index te targeten in plaats van de indexnaam zelf te gebruiken.

U kunt GET of POST gebruiken. Queryparameters worden opgegeven in de queryreeks in het geval van GET-aanvragen en in de aanvraagbody in het geval van POST-aanvragen.

GET https://[service name].search.windows.net/indexes/[index name]/docs?[query parameters] 
  Content-Type: application/json   
  api-key: [admin or query key]

Als u POST gebruikt, voegt u de actie 'zoeken' toe als een URI-parameter.

POST https://[service name].search.windows.net/indexes/[index name]/docs/search?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin or query key]

Wanneer aangeroepen met GET, mag de lengte van de aanvraag-URL niet groter zijn dan 8 kB. Deze lengte is meestal voldoende voor de meeste toepassingen. Sommige toepassingen produceren echter zeer grote query's, met name wanneer OData-filterexpressies worden gebruikt. Voor deze toepassingen is HTTP POST een betere keuze omdat het grotere filters dan GET toestaat.

Met POST is het aantal componenten in een filter de beperkende factor, niet de grootte van de onbewerkte filtertekenreeks, omdat de limiet voor de aanvraaggrootte voor POST ongeveer 16 MB is. Hoewel de maximale grootte van de POST-aanvraag erg groot is, kunnen filterexpressies niet willekeurig complex zijn. Zie Syntaxis voor OData-expressies voor Azure Cognitive Search voor meer informatie over beperkingen van filtercomplexiteit.

URI-parameters

Parameter	Beschrijving
[servicenaam]	Vereist. Stel deze in op de unieke, door de gebruiker gedefinieerde naam van uw zoekservice.
[indexnaam]/docs	Vereist. Hiermee geeft u de documentenverzameling van een benoemde index op.
[queryparameters]	Queryparameters worden opgegeven in de URI voor GET-aanvragen en in de aanvraagbody voor POST-aanvragen.
api-versie	Vereist. De huidige stabiele versie is `api-version=2020-06-30`. Zie API-versies voor meer versies. Voor query's wordt de API-versie altijd opgegeven als een URI-parameter voor zowel GET als POST.

Aanbevelingen voor URL-codering

Vergeet niet om specifieke queryparameters met URL's te coderen wanneer u de GET REST API rechtstreeks aanroept. Voor een bewerking Documenten zoeken kan URL-codering nodig zijn voor de volgende queryparameters:

zoeken
$filter
Facet
highlightPreTag
highlightPostTag

URL-codering wordt alleen aanbevolen voor afzonderlijke parameters. Als u per ongeluk de hele queryreeks (alles na de ?) url-codering uitvoert, worden aanvragen verbroken.

URL-codering is ook alleen nodig wanneer u de REST API rechtstreeks aanroept met behulp van GET. Er is geen URL-codering nodig wanneer u POST gebruikt of wanneer u de Azure Cognitive Search .NET-clientbibliotheek gebruikt, die de codering voor u afhandelt.

Aanvraagheaders

In de volgende tabel worden de vereiste en optionele aanvraagheaders beschreven.

Velden	Description
Content-Type	Vereist. Stel dit in op 'application/json'
api-key	Vereist. Een unieke, door het systeem gegenereerde tekenreeks die de aanvraag verifieert bij uw zoekservice. Queryaanvragen voor de documentenverzameling kunnen een beheerderssleutel of querysleutel opgeven als de API-sleutel. De querysleutel wordt gebruikt voor alleen-lezenbewerkingen voor de documentenverzameling. U vindt de API-sleutel in uw zoekservicedashboard in de Azure Portal.

Aanvraagbody

Voor GET: Geen.

Voor POST:

{  
     "count": true | false (default),  
     "facets": [ "facet_expression_1", "facet_expression_2", ... ],  
     "filter": "odata_filter_expression",  
     "highlight": "highlight_field_1, highlight_field_2, ...",  
     "highlightPreTag": "pre_tag",  
     "highlightPostTag": "post_tag",  
     "minimumCoverage": # (% of index that must be covered to declare query successful; default 100),  
     "orderby": "orderby_expression",  
     "queryType": "simple" (default) | "full",
     "scoringParameters": [ "scoring_parameter_1", "scoring_parameter_2", ... ],  
     "scoringProfile": "scoring_profile_name",  
     "scoringStatistics" : "local" | "global",
     "search": "simple_query_expression",  
     "searchFields": "field_name_1, field_name_2, ...",  
     "searchMode": "any" (default) | "all",  
     "select": "field_name_1, field_name_2, ...",  
     "sessionId" : "session_id",
     "skip": # (default 0),  
     "top": #  
   }

Vervolg van antwoorden op gedeeltelijke zoekopdrachten

Soms kan Azure Cognitive Search niet alle aangevraagde resultaten in één zoekantwoord retourneren. Dit kan verschillende oorzaken hebben, bijvoorbeeld wanneer de query te veel documenten aanvraagt door geen $top op te geven of een waarde op te geven voor $top die te groot is. In dergelijke gevallen bevat Azure Cognitive Search de @odata.nextLink aantekening in de antwoordtekst en ook @search.nextPageParameters als het een POST-aanvraag was. U kunt de waarden van deze aantekeningen gebruiken om een andere zoekaanvraag te formuleren om het volgende deel van het zoekantwoord op te halen. Dit wordt een voortzetting van de oorspronkelijke zoekaanvraag genoemd en de aantekeningen worden doorgaans vervolgtokens genoemd. Zie het voorbeeld in Antwoord hieronder voor meer informatie over de syntaxis van deze aantekeningen en waar ze worden weergegeven in de hoofdtekst van het antwoord.

De redenen waarom Azure Cognitive Search vervolgtokens kunnen retourneren, zijn implementatiespecifiek en kunnen worden gewijzigd. Robuuste clients moeten altijd klaar zijn voor het afhandelen van gevallen waarin minder documenten worden geretourneerd dan verwacht en een vervolgtoken is opgenomen om door te gaan met het ophalen van documenten. Houd er ook rekening mee dat u dezelfde HTTP-methode moet gebruiken als de oorspronkelijke aanvraag om door te gaan. Als u bijvoorbeeld een GET-aanvraag hebt verzonden, moeten alle vervolgaanvragen die u verzendt ook GET gebruiken (en op dezelfde manier voor POST).

Notitie

Het doel van @odata.nextLink en @search.nextPageParameters is om de service te beschermen tegen query's die te veel resultaten aanvragen, niet om een algemeen mechanisme voor paging te bieden. Als u door de resultaten wilt bladeren, gebruikt u $top en $skip samen. Als u bijvoorbeeld pagina's met de grootte 10 wilt, moet uw eerste aanvraag $top=10 en $skip=0 hebben, de tweede aanvraag moet $top=10 en $skip=10 hebben, de derde aanvraag moet $top=10 en $skip=20 hebben, enzovoort.

Queryparameters

Een query accepteert verschillende parameters op de URL wanneer deze wordt aangeroepen met GET en als JSON-eigenschappen in de aanvraagbody wanneer aangeroepen met POST. De syntaxis voor sommige parameters verschilt enigszins tussen GET en POST. Deze verschillen worden hieronder vermeld, zoals van toepassing.

Naam	Type	Description
api-versie	tekenreeks	Vereist. Versie van de REST API die wordt gebruikt voor de aanvraag. Zie API-versies voor een lijst met ondersteunde versies. Voor deze bewerking wordt de API-versie opgegeven als een URI-parameter, ongeacht of u Search Documents met GET of POST aanroept.
$count	booleaans	Optioneel. Geldige waarden zijn 'true' of 'false'. De standaardinstelling is 'false'. Wanneer deze parameter wordt aangeroepen met POST, krijgt deze parameter de naam count in plaats van $count. Hiermee geeft u op of het totale aantal resultaten moet worden opgehaald. Dit is het aantal documenten dat overeenkomt met de zoek- en $filter parameters, waarbij $top en $skip worden genegeerd. Als u deze waarde instelt op 'true' kunnen de prestaties afnemen. Het aantal is nauwkeurig als de index stabiel is, maar documenten die actief worden toegevoegd, bijgewerkt of verwijderd, worden onder- of overrapport. Als u alleen het aantal zonder documenten wilt ophalen, kunt u $top=0 gebruiken.
Facet	tekenreeks	Optioneel. Een veld om mee te facetten. De tekenreeks kan parameters bevatten om de faceting aan te passen, uitgedrukt in door komma's gescheiden naam-waardeparen. Wanneer deze parameter wordt aangeroepen met POST, krijgt deze parameter de naam facetten in plaats van facet. Geldig zijn 'count', 'sort', 'values', 'interval' en 'timeoffset'. "aantal" is het maximum aantal facettermen; de standaardwaarde is 10. Er is geen bovengrens voor het aantal termen, maar hogere waarden verslechteren de prestaties, vooral als het facetveld een groot aantal unieke termen bevat. Met 'facet=category,count:5' worden bijvoorbeeld de vijf belangrijkste categorieën in facetresultaten opgehaald. Als de parameter count kleiner is dan het aantal unieke termen, zijn de resultaten mogelijk niet nauwkeurig. Dit komt door de manier waarop facetquery's worden verdeeld over shards. U kunt aantal instellen op nul of op een waarde die groter is dan of gelijk is aan het aantal unieke waarden in het facetable-veld om een nauwkeurige telling voor alle shards te krijgen. De afweging is een hogere latentie. "sort" kan worden ingesteld op "count", "-count", "value", "-value". Gebruik aantal om aflopend te sorteren op aantal. Gebruik -count om oplopend te sorteren op aantal. Gebruik waarde om oplopend op waarde te sorteren. Gebruik -value om aflopend te sorteren op waarde (bijvoorbeeld'facet=category,count:3,sort:count' krijgt de drie belangrijkste categorieën in facetresultaten in aflopende volgorde op het aantal documenten met elke plaatsnaam). Als de drie belangrijkste categorieën Budget, Motel en Luxe zijn en Budget 5 treffers heeft, Motel heeft er 6 en Luxe 4, worden de buckets weergegeven in de volgorde Motel, Budget, Luxe. Voor -value produceert "facet=rating,sort:-value" buckets voor alle mogelijke classificaties, in aflopende volgorde op waarde (als de classificaties bijvoorbeeld van 1 tot 5 zijn, worden de buckets gerangschikt op 5, 4, 3, 2, 1, ongeacht hoeveel documenten overeenkomen met elke classificatie). 'waarden' kunnen worden ingesteld op door pijpen gescheiden numerieke of Edm.DateTimeOffset-waarden die een dynamische set facetinvoerwaarden opgeven (bijvoorbeeld 'facet=baseRate,values:10 \| 20" produceert drie buckets: één voor basistarief 0 tot maar niet inclusief 10, één voor 10 tot maar niet inclusief 20, en één voor 20 en hoger). Een tekenreeks "facet=lastRenovationDate,values:2010-02-01T00:00:00Z" produceert twee buckets: één voor hotels die zijn gerenoveerd vóór februari 2010 en één voor hotels die op 1 februari 2010 of later zijn gerenoveerd. De waarden moeten in oplopende volgorde worden weergegeven om de verwachte resultaten te krijgen. 'interval' is een geheel getal dat groter is dan 0 voor getallen, of minuut, uur, dag, week, maand, kwartaal, jaar voor datum/tijdwaarden. "facet=baseRate,interval:100" produceert bijvoorbeeld buckets op basis van basisfrequentiebereiken van grootte 100. Als de basistarieven allemaal tussen $ 60 en $ 600 liggen, zijn er buckets voor 0-100, 100-200, 200-300, 300-400, 400-500 en 500-600. De tekenreeks 'facet=lastRenovationDate,interval:year' produceert één bucket voor elk jaar waarin hotels zijn gerenoveerd. 'timeoffset' kan worden ingesteld op ([+-]hh:mm, [+-]hhmm of [+-]hh). Als u de parameter timeoffset gebruikt, moet deze worden gecombineerd met de intervaloptie en alleen wanneer deze wordt toegepast op een veld van het type Edm.DateTimeOffset. De waarde geeft de UTC-tijdsverschil aan waarmee rekening moet worden gehouden bij het instellen van tijdsgrenzen. Bijvoorbeeld: "facet=lastRenovationDate,interval:day,timeoffset:-01:00" gebruikt de daggrens die begint om 01:00:00 UTC (middernacht in de doeltijdzone). aantal en sortering kunnen worden gecombineerd in dezelfde facetspecificatie, maar ze kunnen niet worden gecombineerd met interval of waarden, en interval en waarden kunnen niet samen worden gecombineerd. Interval-facetten op datum/tijd worden berekend op basis van de UTC-tijd als timeoffset niet is opgegeven. Bijvoorbeeld: voor 'facet=lastRenovationDate,interval:day' begint de daggrens om 00:00:00 UTC.
$filter	tekenreeks	Optioneel. Een gestructureerde zoekexpressie in de standaard-OData-syntaxis. Alleen filterbare velden kunnen worden gebruikt in een filter. Bij het aanroepen met POST krijgt deze parameter de naam filter in plaats van $filter. Zie Syntaxis van OData-expressie voor Azure Cognitive Search voor meer informatie over de subset van de OData-expressie grammatica die Azure Cognitive Search ondersteunt.
Markeren	tekenreeks	Optioneel. Een reeks door komma's gescheiden veldnamen die worden gebruikt voor hit-highlights. Alleen doorzoekbare velden kunnen worden gebruikt voor het markeren van treffers. Standaard retourneert Azure Cognitive Search maximaal 5 markeringen per veld. De limiet kan per veld worden geconfigureerd door '-<max aantal markeringen>' toe te voegen na de veldnaam. 'highlight=title-3,description-10' retourneert bijvoorbeeld maximaal 3 gemarkeerde treffers uit het titelveld en maximaal 10 treffers uit het beschrijvingsveld. Het maximum aantal markeringen moet een geheel getal tussen 1 en 1000 zijn.
highlightPostTag	tekenreeks	Optioneel. De standaardwaarde is `"</em>"`. Een tekenreekstag die wordt toegevoegd aan de gemarkeerde term.. Moet worden ingesteld met highlightPreTag. Gereserveerde tekens in DE URL moeten procent zijn gecodeerd (bijvoorbeeld %23 in plaats van #).
highlightPreTag	tekenreeks	Optioneel. De standaardwaarde is `"</em>"`. Een tekenreekstag die vooraf gaat aan de gemarkeerde term. Moet worden ingesteld met highlightPostTag. Gereserveerde tekens in DE URL moeten procent zijn gecodeerd (bijvoorbeeld %23 in plaats van #).
minimumCoverage	geheel getal	Optioneel. Geldige waarden zijn een getal tussen 0 en 100, waarmee het percentage van de index wordt aangegeven dat beschikbaar moet zijn voor het uitvoeren van de query voordat deze als geslaagd kan worden gerapporteerd. De standaardwaarde is '100'. Honderd procent dekking betekent dat alle shards op de aanvraag hebben gereageerd (noch problemen met de servicestatus of onderhoudsactiviteiten hebben de dekking verminderd). Onder de standaardinstelling retourneert minder dan volledige dekking HTTP-statuscode 503. Het verlagen van minimumCoverage kan handig zijn als er 503-fouten optreden en u de kans op een geslaagde query wilt vergroten, met name voor services die zijn geconfigureerd voor één replica. Als u minimumCoverage instelt en Search slaagt, wordt HTTP 200 geretourneerd en wordt in het antwoord een @search.coverage waarde opgenomen die het percentage van de index aangeeft dat is opgenomen in de query. In dit scenario zijn niet alle overeenkomende documenten gegarandeerd aanwezig in de zoekresultaten, maar als de beschikbaarheid van zoekopdrachten belangrijker is dan intrekken, kan het verminderen van de dekking een haalbare oplossing zijn.
$orderby	tekenreeks	Optioneel. Een lijst met door komma's gescheiden expressies om de resultaten op te sorteren. Wanneer deze parameter wordt aangeroepen met POST, krijgt deze parameter de naam orderby in plaats van $orderby. Elke expressie kan een veldnaam of een aanroep van de functie geo.distance() zijn. Elke expressie kan worden gevolgd door 'asc' om oplopend aan te geven en 'desc' om aflopend aan te geven. Als het sorteerveld null-waarden bevat, worden null-waarden eerst weergegeven in oplopende volgorde en de laatste in aflopende volgorde. De standaardwaarde is oplopende volgorde. Bindingen worden verbroken door de matchscores van documenten. Als er geen $orderby is opgegeven, is de standaardsorteervolgorde aflopend op documentmatchscore. Er is een limiet van 32 componenten voor $orderby.
Querytype	tekenreeks	Optioneel. Geldige waarden zijn 'eenvoudig' of 'volledig'. De standaardwaarde is 'eenvoudig'. 'simple' interpreteert queryreeksen met behulp van de eenvoudige querysyntaxis die symbolen zoals `+`en `""*` toestaat. Query's worden standaard geëvalueerd in alle doorzoekbare velden (of velden die worden aangegeven in searchFields) in elk document. 'volledig' interpreteert queryreeksen met behulp van de volledige Lucene-querysyntaxis , waarmee veldspecifieke en gewogen zoekopdrachten mogelijk zijn. Zoeken naar bereiken in de Lucene-querytaal wordt niet ondersteund ten gunste van $filter die vergelijkbare functionaliteit biedt.
scoringParameter	tekenreeks	Optioneel. Geeft de waarden aan voor elke parameter die is gedefinieerd in een scorefunctie (zoals referencePointParameter) met behulp van de notatie 'name-value1,value2,...' Wanneer deze parameter wordt aangeroepen met POST, heeft deze parameter de naam scoringParameters in plaats van scoringParameter. U geeft deze ook op als een JSON-matrix met tekenreeksen waarbij elke tekenreeks een afzonderlijk naam-waardenpaar is. Voor scoreprofielen die een functie bevatten, scheidt u de functie van de invoerlijst met een `-` teken. Een functie met de naam `"mylocation"` zou bijvoorbeeld '&scoringParameter=mylocation-122.2,44,8' zijn. Het eerste streepje scheidt de functienaam van de lijst met waarden, terwijl het tweede streepje deel uitmaakt van de eerste waarde (lengtegraad in dit voorbeeld). Voor scoreparameters, zoals voor tagverbetering die komma's kunnen bevatten, kunt u dergelijke waarden in de lijst escapen met enkele aanhalingstekens. Als de waarden zelf enkele aanhalingstekens bevatten, kunt u deze escapen door ze te verdubbelen. Stel dat u een parameter voor tagverbetering hebt met de naam `"mytag"` en u de tagwaarden 'Hallo, O'Brien' en 'Smith' wilt verhogen, is de querytekenreeksoptie '&scoringParameter=mytag-'Hello, O''Brien',Smith'. Aanhalingstekens zijn alleen vereist voor waarden die komma's bevatten.
scoringProfile	tekenreeks	Optioneel. De naam van een scoreprofiel voor het evalueren van matchscores voor overeenkomende documenten om de resultaten te sorteren.
scoringStatistics	tekenreeks	Optioneel. Geldige waarden zijn 'lokaal' of 'globaal'. De standaardinstelling is 'lokaal'. Geef op of scorestatistieken, zoals de documentfrequentie, globaal (voor alle shards) moeten worden berekend voor een consistentere score of lokaal (op de huidige shard) voor een lagere latentie. Zie Scorestatistieken in Azure Cognitive Search. Scorestatistieken worden altijd lokaal berekend voor termen die fuzzy zoeken ('~') gebruiken.
zoeken	tekenreeks	Optioneel. De tekst die u wilt zoeken. Alle doorzoekbare velden worden standaard doorzocht, tenzij searchFields is opgegeven. In de index wordt tekst in een doorzoekbaar veld tokenized, zodat meerdere termen kunnen worden gescheiden door witruimte (bijvoorbeeld: 'search=hello world'). `` Gebruik (dit kan handig zijn voor booleaanse filterquery's). Het weglaten van deze parameter heeft hetzelfde effect als het instellen op ``. Zie Eenvoudige querysyntaxis voor details over de zoeksyntaxis. Resultaten kunnen soms verrassend zijn bij het uitvoeren van query's op doorzoekbare velden. De tokenizer bevat logica voor het afhandelen van cases die veel voorkomen in Engelse tekst, zoals apostrofs, komma's in getallen, enzovoort. 'search=123.456' komt bijvoorbeeld overeen met één term '123.456' in plaats van de afzonderlijke termen '123' en '456', omdat komma's worden gebruikt als scheidingstekens voor duizendtallen voor grote getallen in het Engels. Daarom raden we u aan witruimte te gebruiken in plaats van interpunctie om termen in de zoekparameter van elkaar te scheiden.
searchMode	tekenreeks	Optioneel. Geldige waarden zijn 'any' of 'all' Standaardwaarden op 'any'. Hiermee geeft u op of een of alle zoektermen moeten worden vergeleken om het document als een overeenkomst te tellen.
searchFields	tekenreeks	Optioneel. De lijst met door komma's gescheiden veldnamen om te zoeken naar de opgegeven tekst. Doelvelden moeten worden gemarkeerd als doorzoekbaar in het indexschema.
$select	tekenreeks	Optioneel. Een lijst met door komma's gescheiden velden die moeten worden opgenomen in de resultatenset. Alleen velden die zijn gemarkeerd als ophaalbaar, kunnen in deze component worden opgenomen. Als dit niet is opgegeven of is ingesteld op `*`, worden alle velden die zijn gemarkeerd als ophaalbaar in het schema opgenomen in de projectie. Wanneer deze parameter wordt aangeroepen met POST, krijgt deze parameter de naam select in plaats van $select.
Sessionid	tekenreeks	Optioneel. Met behulp van sessionId kunt u de consistentie van de relevantiescore verbeteren voor zoekservices met meerdere replica's. In configuraties met meerdere replica's kunnen er kleine verschillen zijn tussen relevantiescores van afzonderlijke documenten voor dezelfde query. Wanneer een sessie-id wordt opgegeven, doet de service er alles aan om een bepaalde aanvraag naar dezelfde replica voor die sessie te routeren. Wees voorzichtig dat het herhaaldelijk opnieuw gebruiken van dezelfde sessie-id-waarden de taakverdeling van de aanvragen in verschillende replica's kan verstoren en de prestaties van de zoekservice nadelig kan beïnvloeden. De waarde die als sessionId wordt gebruikt, mag niet beginnen met een _-teken. Als een service geen replica's heeft, heeft deze parameter geen invloed op de prestaties of scoreconsistentie.
$skip	geheel getal	Optioneel. Het aantal zoekresultaten dat moet worden overgeslagen. Wanneer deze parameter wordt aangeroepen met POST, krijgt deze parameter de naam skip in plaats van $skip. Deze waarde mag niet groter zijn dan 100.000. Als u documenten op volgorde wilt scannen, maar $skip vanwege deze beperking niet kunt gebruiken, kunt u overwegen om $orderby te gebruiken voor een veld met unieke waarden voor elk document in de index (zoals de documentsleutel bijvoorbeeld) en $filter met een bereikquery.
$top	geheel getal	Optioneel. Het aantal zoekresultaten dat moet worden opgehaald. De standaardwaarde is 50. Wanneer deze parameter wordt aangeroepen met POST, krijgt deze parameter de naam bovenaan in plaats van $top. Als u een waarde opgeeft die groter is dan 1000 en er meer dan 1000 resultaten zijn, worden alleen de eerste 1000 resultaten geretourneerd, samen met een koppeling naar de volgende pagina met resultaten (zie @odata.nextLink het onderstaande voorbeeld). Azure Cognitive Search maakt gebruik van paging aan de serverzijde om te voorkomen dat query's te veel documenten tegelijk ophalen. Het standaardpaginaformaat is 50, terwijl het maximale paginaformaat 1000 is. Dit betekent dat standaard Zoekdocumenten maximaal 50 resultaten retourneert als u geen $top opgeeft. Als er meer dan 50 resultaten zijn, bevat het antwoord informatie om de volgende pagina van maximaal 50 resultaten op te halen (zie '@odata.nextLink' en '@search.nextPageParameters' in de onderstaande voorbeelden . Als u een waarde opgeeft die groter is dan 1000 voor $top en er meer dan 1000 resultaten zijn, worden alleen de eerste 1000 resultaten geretourneerd, samen met informatie om de volgende pagina van maximaal 1000 resultaten op te halen.

Antwoord

Statuscode: 200 OK wordt geretourneerd voor een geslaagd antwoord.

  {
    "@odata.count": # (if $count=true was provided in the query),
    "@search.coverage": # (if minimumCoverage was provided in the query),
    "@search.facets": { (if faceting was specified in the query)
      "facet_field": [
        {
          "value": facet_entry_value (for non-range facets),
          "from": facet_entry_value (for range facets),
          "to": facet_entry_value (for range facets),
          "count": number_of_documents
        }
      ],
      ...
    },
    "@search.nextPageParameters": { (request body to fetch the next page of results if not all results could be returned in this response and Search was called with POST)
      "count": ... (value from request body if present),
      "facets": ... (value from request body if present),
      "filter": ... (value from request body if present),
      "highlight": ... (value from request body if present),
      "highlightPreTag": ... (value from request body if present),
      "highlightPostTag": ... (value from request body if present),
      "minimumCoverage": ... (value from request body if present),
      "orderby": ... (value from request body if present),
      "scoringParameters": ... (value from request body if present),
      "scoringProfile": ... (value from request body if present),
      "scoringStatistics": ... (value from request body if present),
      "search": ... (value from request body if present),
      "searchFields": ... (value from request body if present),
      "searchMode": ... (value from request body if present),
      "select": ... (value from request body if present),
      "sessionId" : ... (value from request body if present),
      "skip": ... (page size plus value from request body if present),
      "top": ... (value from request body if present minus page size),
    },
    "value": [
      {
        "@search.score": document_score (if a text query was provided),
        "@search.highlights": {
          field_name: [ subset of text, ... ],
          ...
        },
        "@search.features": {
          "field_name": {
            "uniqueTokenMatches": feature_score,
            "similarityScore": feature_score,
            "termFrequency": feature_score,
          },
          ...
        },
        key_field_name: document_key,
        field_name: field_value (retrievable fields or specified projection),
        ...
      },
      ...
    ],
    "@odata.nextLink": (URL to fetch the next page of results if not all results could be returned in this response; Applies to both GET and POST)
  }

Voorbeelden

U vindt aanvullende voorbeelden in de syntaxis van OData-expressies voor Azure Cognitive Search.

Zoek in de index aflopend gesorteerd op datum:

GET /indexes/hotels/docs?search=*&$orderby=LastRenovationDate desc&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "orderby": "LastRenovationDate desc"
    }

Zoek in een facetzoekactie in de index en haal facetten op voor categorieën, classificaties, tags en items met baseRate in specifieke bereiken.
```
GET /indexes/hotels/docs?search=*&facet=Category&facet=Rating&facet=Tags&facet=Rooms/BaseRate,values:80|150|220&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ]  
    }  
```
U ziet dat het laatste facet zich in een subveld bevindt. Facetten tellen het bovenliggende document (Hotels) en niet tussenliggende subdocumenten (Kamers), dus het antwoord bepaalt het aantal hotels dat kamers in elke prijsbucket heeft.

Gebruik een filter om het resultaat van de vorige facetquery te verfijnen nadat de gebruiker Beoordeling 3 en categorie 'Motel' heeft geselecteerd.

GET /indexes/hotels/docs?search=*&facet=tags&facet=Rooms/BaseRate,values:80|150|220&$filter=Rating eq 3 and Category eq 'Motel'&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "tags", "Rooms/BaseRate,values:80|150|220" ],  
      "filter": "Rating eq 3 and Category eq 'Motel'"  
    }

In een facetzoekopdracht stelt u een bovengrens in voor unieke termen die in een query worden geretourneerd. De standaardwaarde is 10, maar u kunt deze waarde verhogen of verlagen met behulp van de parameter count op het facet-kenmerk. In dit voorbeeld worden facetten geretourneerd voor plaats, beperkt tot 5.
```
GET /indexes/hotels/docs?search=*&facet=Address/City,count:5&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "test",  
      "facets": [ "Address/City,count:5" ]  
    }  
```

Zoeken in de index binnen specifieke velden (bijvoorbeeld een taalveld):

GET /indexes/hotels/docs?search=hôtel&searchFields=Description_fr&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hôtel",  
      "searchFields": "Description_fr"
    }

Zoek in de Index in meerdere velden. U kunt bijvoorbeeld doorzoekbare velden opslaan en er query's op uitvoeren in meerdere talen, allemaal binnen dezelfde index. Als Engelse en Franse beschrijvingen naast elkaar voorkomen in hetzelfde document, kunt u een of meer in de queryresultaten retourneren:
```
GET /indexes/hotels/docs?search=hotel&searchFields=Description,Description_fr&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "searchFields": "Description, Description_fr"
    }  
```
U kunt alleen een query uitvoeren op de index tegelijk. Maak niet meerdere indexen voor elke taal, tenzij u van plan bent om een query voor één uit te voeren.

Paging: de eerste pagina met items ophalen (paginaformaat is 10):

GET /indexes/hotels/docs?search=*&$skip=0&$top=10&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 0,  
      "top": 10  
    }

Paging: de tweede pagina met items ophalen (paginaformaat is 10):

GET /indexes/hotels/docs?search=*&$skip=10&$top=10&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "skip": 10,  
      "top": 10  
    }

Een specifieke set velden ophalen:

GET /indexes/hotels/docs?search=*&$select=HotelName,Description&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "*",  
      "select": "HotelName, Description"
    }

Documenten ophalen die overeenkomen met een specifieke filterexpressie:

GET /indexes/hotels/docs?$filter=(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "filter": "(Rooms/BaseRate ge 60 and Rooms/BaseRate lt 300) or HotelName eq 'Fancy Stay'"  
    }

Zoek in de index en retourneer fragmenten met hit-highlights:

GET /indexes/hotels/docs?search=something&highlight=Description&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "highlight": "Description"  
    }

Zoek in de index en retourneer documenten die van dichterbij tot ver weg van een referentielocatie zijn gesorteerd:

GET /indexes/hotels/docs?search=something&$orderby=geo.distance(Location, geography'POINT(-122.12315 47.88121)')&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "orderby": "geo.distance(Location, geography'POINT(-122.12315 47.88121)')"
    }

Zoek in de index, ervan uitgaande dat er een scoreprofiel met de naam 'geo' is met twee functies voor scoren op afstand, één die een parameter met de naam 'currentLocation' definieert en één die een parameter met de naam 'lastLocation' definieert:

GET /indexes/hotels/docs?search=something&scoringProfile=geo&scoringParameter=currentLocation--122.123,44.77233&scoringParameter=lastLocation--121.499,44.2113&api-version=2020-06-30

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "something",  
      "scoringProfile": "geo",  
      "scoringParameters": [ "currentLocation--122.123,44.77233", "lastLocation--121.499,44.2113" ]  
    }

Documenten zoeken in de index met behulp van eenvoudige querysyntaxis. Deze query retourneert hotels waar doorzoekbare velden de termen 'comfort' en 'location' bevatten, maar niet 'motel':
```
Get /indexes/hotels/docs?search=comfort +location –motel&searchMode=all&api-version=22020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "comfort +location -motel",  
      "searchMode": "all"  
    }  
```
Tip

Het gebruik van overschrijft searchMode=all de standaardwaarde van searchMode=any, zodat ' -motel EN NIET' betekent in plaats van 'OR NIET'. Zonder searchMode=allkrijgt u 'OR NOT' waardoor zoekresultaten worden uitgebreid in plaats van beperkt. Dit kan voor sommige gebruikers contra-intuïtief zijn.

Documenten zoeken in de index met behulp van Lucene-querysyntaxis). Deze query retourneert hotels waar het categorieveld de term 'budget' bevat en alle doorzoekbare velden met de woordgroep 'onlangs gerenoveerd'. Documenten met de zin 'onlangs gerenoveerd' worden hoger gerangschikt als gevolg van de term boostwaarde (3)

GET /indexes/hotels/docs?search=Category:budget AND \"recently renovated\"^3&searchMode=all&api-version=2020-06-30&querytype=full`

POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
     "search": "Category:budget AND \"recently renovated\"^3",  
      "queryType": "full",  
      "searchMode": "all"  
}

Zoek documenten in de index en geef de voorkeur aan consistent scoren boven lagere latentie. Met deze query worden de documentfrequenties voor de hele index berekend en wordt er alles aan gedaan om dezelfde replica te gebruiken voor alle query's binnen dezelfde 'sessie', wat helpt bij het genereren van een stabiele en reproduceerbare rangschikking.
```
GET /indexes/hotels/docs?search=hotel&sessionId=mySessionId&scoringStatistics=global&api-version=2020-06-30
```
```
POST /indexes/hotels/docs/search?api-version=2020-06-30
    {  
      "search": "hotel",  
      "sessionId": "mySessionId",
      "scoringStatistics" :"global"
    }  
```