Delen via

Voorbeelden van gefacetteerde navigatie

In deze sectie wordt de facetnavigatieconfiguratie uitgebreid met voorbeelden die basisgebruik en andere scenario's demonstreren.

Facetable-velden worden gedefinieerd in een index, maar facetparameters en expressies worden gedefinieerd in queryaanvragen. Als u een index met facetable-velden hebt, kunt u nieuwe preview-functies proberen, zoals facethiërarchieën, facetaggregaties en facetfilters voor bestaande indexen.

Facetparameters en syntaxis

Afhankelijk van de API is een facetquery meestal een matrix van facetexpressies die worden toegepast op zoekresultaten. Elke facetexpressie bevat een facetveldnaam, eventueel gevolgd door een door komma's gescheiden lijst met naam-waardeparen.

  • facetquery is een queryaanvraag die een faceteigenschap bevat.
  • facetable field is een velddefinitie in de zoekindex die is toegeschreven aan de facetable eigenschap.
  • aantal is het aantal overeenkomsten voor elk facet dat in de zoekresultaten wordt gevonden.

In de volgende tabel worden facetparameters beschreven die in de voorbeelden worden gebruikt.

Facet-parameter Beschrijving Gebruik Voorbeeld
count Maximum aantal facettermen per structuur. Geheel getal. De standaardwaarde is 10. Er is geen bovengrens, maar hogere waarden verminderen de prestaties, vooral als het facetveld een groot aantal unieke termen bevat. Dit komt doordat facetquery's worden verdeeld over shards. U kunt instellen count op nul of op een waarde die groter is dan of gelijk is aan het aantal unieke waarden in het facetable-veld om een nauwkeurig aantal te krijgen voor alle shards. De afweging is een hogere latentie. Tags,count:5 beperkt de reactietijd van de facetnavigatie tot vijf facetbuckets die de meeste facetaantallen hebben, maar ze kunnen in willekeurige volgorde zijn.
sort Bepaalt de volgorde van facetbucktten. Geldige waarden zijn count, -count, value, -value. Gebruik count deze functie om facetten weer te geven van de grootste naar de kleinste. Gebruik -count deze indeling om in oplopende volgorde (kleinste naar grootste) te sorteren. Hiermee value kunt u alfanumerisch sorteren op facetwaarde in oplopende volgorde. Gebruik -value dit om aflopend te sorteren op waarde. "facet=Category,count:3,sort:count" haalt de top drie facet buckets op in zoekresultaten, weergegeven in aflopende volgorde op het aantal overeenkomsten in elke categorie. Als de drie belangrijkste categorieën Budget, Extended-Stay en Luxe zijn en Budget 5 treffers heeft, heeft Extended-Stay 6 en Luxe heeft 4, dan worden de facet buckets besteld als Extended-Stay, Budget, Luxe. Een ander voorbeeld is"facet=Rating,sort:-value". Het produceert facetten voor alle mogelijke classificaties, in aflopende volgorde op waarde. Als classificaties tussen 1 en 5 liggen, worden de facetten gerangschikt op 5, 4, 3, 2, 1, ongeacht het aantal documenten dat overeenkomt met elke classificatie.
values Biedt waarden voor facetlabels. Ingesteld op door sluistekens gescheiden numerieke waarden of Edm.DateTimeOffset waarden die een dynamische set facetinvoerwaarden opgeven. De waarden moeten in opeenvolgende volgorde worden weergegeven, oplopend om de verwachte resultaten te verkrijgen. "facet=baseRate,values:10 | 20" produceert drie facet 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 reeks "facet=lastRenovationDate,values:2024-02-01T00:00:00Z" produceert twee facet buckets: één voor hotels gerenoveerd vóór februari 2024 en één voor hotels gerenoveerd op 1 februari 2024 of later.
interval Biedt een intervalreeks voor facetten die in intervallen kunnen worden gegroepeerd. Een geheel getalinterval dat groter is dan nul voor getallen of minuten, uur, dag, week, maand, kwartaal, jaar voor datum/tijd-waarden. "facet=baseRate,interval:100" produceert facet buckets op basis van basissnelheidsbereiken van grootte 100. Als de basistarieven allemaal tussen $60 en $600 liggen, zijn er facetgroepen voor 0-100, 100-200, 200-300, 300-400, 400-500 en 500-600. De tekenreeks "facet=lastRenovationDate,interval:year" produceert één facet bucket voor elk jaar dat een hotel is gerenoveerd.
timeoffset Hiermee geeft u de UTC-tijdverschil op waarmee rekening moet worden gehouden bij het instellen van tijdsgrenzen. Ingesteld op ([+-]hh:mm, [+-]hhmm, or [+-]hh). Indien gebruikt, moet de timeoffset parameter worden gecombineerd met de intervaloptie en alleen wanneer deze wordt toegepast op een veld van het type Edm.DateTimeOffset. "facet=lastRenovationDate,interval:day,timeoffset:-01:00" gebruikt de daggrens die begint om 01:00:00 UTC (middernacht in de doeltijdzone).

count en sort kan worden gecombineerd in dezelfde facetspecificatie, maar ze kunnen niet worden gecombineerd met interval of values.

interval en values kan niet samen worden gecombineerd.

Intervalfacetten op datum-tijd worden berekend op basis van UTC als timeoffset niet opgegeven is. Bijvoorbeeld, voor "facet=lastRenovationDate,interval:day" begint de daggrens om 00:00:00 UTC.

Eenvoudig facetvoorbeeld

De volgende facetquery's werken met de voorbeeldindex van hotels. U kunt de JSON-weergave in Search Explorer gebruiken om de JSON-query te plakken. Zie Facetnavigatie toevoegen aan zoekresultaten voor hulp bij het aan de slag gaan.

Met deze eerste query worden facetten opgehaald voor categorieën, classificaties, tags en ruimten met baseRate-waarden in specifieke bereiken. U ziet dat het laatste facet zich op een subveld van de collectie Ruimten bevindt. Facetten tellen het bovenliggende document (Hotels) en niet tussenliggende subdocumenten (Kamers), dus het antwoord bepaalt het aantal hotels met kamers in elke prijscategorie.

POST /indexes/hotels-sample-index/docs/search?api-version={{api_version}}
{  
  "search": "ocean view",  
  "facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ],
  "count": true 
}

In dit tweede voorbeeld wordt een filter gebruikt om het vorige facetqueryresultaat te verfijnen nadat de gebruiker Beoordeling 3 en categorie Motel heeft geselecteerd.

POST /indexes/hotels-sample-index/docs/search?api-version={{api_version}}
{  
  "search": "water view",  
  "facets": [ "Tags", "Rooms/BaseRate,values:80|150|220" ],
  "filter": "Rating eq 3 and Category eq 'Motel'",
  "count": true  
}

In het derde voorbeeld wordt een bovengrens ingesteld 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 tellingsparameter voor het facetkenmerk. Bijvoorbeeld worden in dit voorbeeld facetten van de stad geretourneerd, beperkt tot 5.

POST /indexes/hotels-sample-index/docs/search?api-version={{api_version}}
{  
  "search": "view",  
  "facets": [ "Address/City,count:5" ],
  "count": true
}

In dit voorbeeld ziet u drie facetten voor 'Categorie', 'Tags' en 'Waardering', met een overschrijving van de telling op 'Tags' en een bereikoverschrijving voor 'Waardering', die anders wordt opgeslagen als een double in de index.

POST https://{{service_name}}.search.windows.net/indexes/hotels/docs/search?api-version={{api_version}}
{
    "search": "*",
    "facets": [ 
        "Category", 
        "Tags,count:5", 
        "Rating,values:1|2|3|4|5"
    ],
    "count": true
}

Voor elke facetnavigatiestructuur is er een standaardlimiet van de top 10 facetexemplaren die door de query worden gevonden. Deze standaardinstelling is logisch voor navigatiestructuren, omdat de lijst met waarden wordt opgeslagen in een beheersbare grootte. U kunt de standaardwaarde overschrijven door een waarde toe te wijzen aan 'count'. Vermindert bijvoorbeeld "Tags,count:5" het aantal tags onder de sectie Tags tot de top vijf.

Alleen voor numerieke en datum/tijd-waarden kunt u expliciet waarden instellen in het facetveld (bijvoorbeeld facet=Rating,values:1|2|3|4|5) om de resultaten op te splitsen in aaneengesloten reeksen (reeksen op basis van numerieke waarden of tijdsperioden). U kunt ook 'interval' toevoegen, zoals in facet=Rating,interval:1.

Elk bereik wordt gebouwd met behulp van 0 als uitgangspunt, een waarde uit de lijst als eindpunt en vervolgens ingekort van het vorige bereik om discrete intervallen te maken.

Voorbeeld van afzonderlijke waarden

U kunt een query formuleren die een uniek aantal waarden retourneert voor elk facetable-veld. In dit voorbeeld wordt een lege of niet-gekwalificeerde query ("search": "*") geformuleerd die overeenkomt met alle documenten, maar door in te stellen top op nul, krijgt u alleen de aantallen, zonder resultaten.

Deze query bevat slechts twee velden die zijn gemarkeerd als facetable in de voorbeeldindex hotels.

POST https://{{service_name}}.search.windows.net/indexes/hotels/docs/search?api-version={{api_version}}
{
    "search": "*",
    "count": true,
    "top": 0,
    "facets": [ 
        "Category", "Address/StateProvince""
    ]
}

De resultaten van deze query zijn als volgt:

{
  "@odata.count": 50,
  "@search.facets": {
    "Address/StateProvince": [
      {
        "count": 9,
        "value": "WA"
      },
      {
        "count": 6,
        "value": "CA "
      },
      {
        "count": 4,
        "value": "FL"
      },
      {
        "count": 3,
        "value": "NY"
      },
      {
        "count": 3,
        "value": "OR"
      },
      {
        "count": 3,
        "value": "TX"
      },
      {
        "count": 2,
        "value": "GA"
      },
      {
        "count": 2,
        "value": "MA"
      },
      {
        "count": 2,
        "value": "TN"
      },
      {
        "count": 1,
        "value": "AZ"
      }
    ],
    "Category": [
      {
        "count": 13,
        "value": "Budget"
      },
      {
        "count": 12,
        "value": "Suite"
      },
      {
        "count": 7,
        "value": "Boutique"
      },
      {
        "count": 7,
        "value": "Resort and Spa"
      },
      {
        "count": 6,
        "value": "Extended-Stay"
      },
      {
        "count": 5,
        "value": "Luxury"
      }
    ]
  },
  "value": []
}

Voorbeeld van facethiërarchie

Opmerking

Deze functie is momenteel beschikbaar als openbare preview-versie. Deze preview wordt geleverd zonder service level agreement en wordt niet aanbevolen voor productieworkloads. Bepaalde functies worden mogelijk niet ondersteund of hebben mogelijk beperkte mogelijkheden. Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure Previewsvoor meer informatie.

Met behulp van de nieuwste preview-REST API of Azure Portal kunt u een facethiërarchie configureren met behulp van de > en ; operators.

Operator Beschrijving
> De nestingsoperator (hiërarchisch) geeft een bovenliggende-onderliggende relatie aan.
; De operator puntkomma geeft meerdere velden op hetzelfde nestniveau aan, die allemaal kinderen van hetzelfde bovenliggende element zijn. Het ouder moet slechts één veld bevatten. Zowel de ouder- als kindvelden moeten zijn facetable.

De volgorde van bewerkingen in een facetexpressie die facethiërarchieën bevat, zijn:

  • De optie-operator (komma) die de facetparameters voor het facetveld scheiden, zoals de komma , in Rooms/BaseRate,values.
  • De haakjes, zoals de haakjes die insluiten (Rooms/BaseRate,values:50 ; Rooms/Type).
  • De nestoperator (haakje >)
  • De operator voor toevoegen (puntkomma ;) wordt gedemonstreerd in een tweede voorbeeld "Tags>(Rooms/BaseRate,values:50 ; Rooms/Type)" van deze sectie, waarbij twee onderliggende facetten gelijken zijn onder de Tags-ouder.

Merk op dat ronde haakjes worden verwerkt voordat u bewerkingen nestelt en toevoegt: A > B ; C zou anders zijn dan A > (B ; C).

Er zijn verschillende voorbeelden voor facethiërarchieën. Het eerste voorbeeld is een query die slechts een paar documenten retourneert, wat handig is voor het weergeven van een volledig antwoord. Facetten tellen het bovenliggende document (Hotels) en niet tussenliggende subdocumenten (Kamers), dus het antwoord bepaalt het aantal hotels met kamers in elke facetgroep.

POST /indexes/hotels-sample-index/docs/search?api-version=2025-11-01-Preview
{
  "search": "ocean",  
  "facets": ["Address/StateProvince>Address/City", "Tags>Rooms/BaseRate,values:50"],
  "select": "HotelName, Description, Tags, Address/StateProvince, Address/City",
  "count": true 
}

De resultaten van deze query zijn als volgt. Beide hotels hebben zwembaden. Voor andere tags biedt slechts één hotel de voorzieningen.

{
  "@odata.count": 2,
  "@search.facets": {
    "Tags": [
      {
        "value": "pool",
        "count": 2,
        "@search.facets": {
          "Rooms/BaseRate": [
            {
              "to": 50,
              "count": 0
            },
            {
              "from": 50,
              "count": 2
            }
          ]
        }
      },
      {
        "value": "air conditioning",
        "count": 1,
        "@search.facets": {
          "Rooms/BaseRate": [
            {
              "to": 50,
              "count": 0
            },
            {
              "from": 50,
              "count": 1
            }
          ]
        }
      },
      {
        "value": "bar",
        "count": 1,
        "@search.facets": {
          "Rooms/BaseRate": [
            {
              "to": 50,
              "count": 0
            },
            {
              "from": 50,
              "count": 1
            }
          ]
        }
      },
      {
        "value": "restaurant",
        "count": 1,
        "@search.facets": {
          "Rooms/BaseRate": [
            {
              "to": 50,
              "count": 0
            },
            {
              "from": 50,
              "count": 1
            }
          ]
        }
      },
      {
        "value": "view",
        "count": 1,
        "@search.facets": {
          "Rooms/BaseRate": [
            {
              "to": 50,
              "count": 0
            },
            {
              "from": 50,
              "count": 1
            }
          ]
        }
      }
    ],
    "Address/StateProvince": [
      {
        "value": "FL",
        "count": 1,
        "@search.facets": {
          "Address/City": [
            {
              "value": "Tampa",
              "count": 1
            }
          ]
        }
      },
      {
        "value": "HI",
        "count": 1,
        "@search.facets": {
          "Address/City": [
            {
              "value": "Honolulu",
              "count": 1
            }
          ]
        }
      }
    ]
  },
  "value": [
    {
      "@search.score": 1.6076145,
      "HotelName": "Ocean Water Resort & Spa",
      "Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
      "Tags": [
        "view",
        "pool",
        "restaurant"
      ],
      "Address": {
        "City": "Tampa",
        "StateProvince": "FL"
      }
    },
    {
      "@search.score": 1.0594962,
      "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"
      ],
      "Address": {
        "City": "Honolulu",
        "StateProvince": "HI"
      }
    }
  ]
}

Dit tweede voorbeeld breidt het vorige uit en demonstreert meerdere facetten op het hoogste niveau met meerdere kinderen. Let op: de puntkomma-operator (;) scheidt elk kindelement.

POST /indexes/hotels-sample-index/docs/search?api-version=2025-11-01-Preview
{  
  "search": "+ocean",  
  "facets": ["Address/StateProvince > Address/City", "Tags > (Rooms/BaseRate,values:50 ; Rooms/Type)"],
  "select": "HotelName, Description, Tags, Address/StateProvince, Address/City",
  "count": true 
}

Een gedeeltelijke reactie, ingekort omwille van de beknoptheid, toont tags met onderliggende facetten voor het basistarief en het type van de kamers. In de voorbeeldindex van hotels hebben beide hotels die overeenkomen met +ocean kamers van elk type en een zwembad.

{
  "@odata.count": 2,
  "@search.facets": {
    "Tags": [
      {
        "value": "pool",
        "count": 2,
        "@search.facets": {
          "Rooms/BaseRate": [
            {
              "to": 50,
              "count": 0
            },
            {
              "from": 50,
              "count": 2
            }
          ],
          "Rooms/Type": [
            {
              "value": "Budget Room",
              "count": 2
            },
            {
              "value": "Deluxe Room",
              "count": 2
            },
            {
              "value": "Standard Room",
              "count": 2
            },
            {
              "value": "Suite",
              "count": 2
            }
          ]
        }}]},
  ...
}

In dit laatste voorbeeld ziet u prioriteitsregels voor haakjes die van invloed zijn op nestniveaus. Stel dat u een facethiërarchie in deze volgorde wilt retourneren.

Address/StateProvince
  Address/City
    Category
    Rating

Als u deze hiërarchie wilt retourneren, maakt u een query waarbij categorie en classificatie op hetzelfde niveau staan onder Adres/Plaats.

  { 
    "search": "beach",  
    "facets": [
        "Address/StateProvince > (Address/City > (Category ; Rating))"
        ],
    "select": "HotelName, Description, Tags, Address/StateProvince, Address/City",
    "count": true 
  }

Als u de binnenste haakjes verwijdert, zijn categorie en classificatie niet langer broers en zussen, omdat de prioriteitsregels betekenen dat de > operator eerder ;wordt geëvalueerd.

  { 
    "search": "beach",  
    "facets": [
        "Address/StateProvince > (Address/City > Category ; Rating)"
        ],
    "select": "HotelName, Description, Tags, Address/StateProvince, Address/City",
    "count": true 
  }

De bovenliggende categorie op het hoogste niveau is nog steeds Adres/ProvincieStaat, maar nu staan Adres/Stad en Waardering op hetzelfde niveau.

Address/StateProvince
  Rating
  Address/City
    Category

Voorbeeld van facetfiltering

Opmerking

Deze functie is momenteel beschikbaar als openbare preview-versie. Deze preview wordt geleverd zonder service level agreement en wordt niet aanbevolen voor productieworkloads. Bepaalde functies worden mogelijk niet ondersteund of hebben mogelijk beperkte mogelijkheden. Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure Previewsvoor meer informatie.

Met behulp van de nieuwste preview-REST API of Azure Portal kunt u facetfilters configureren.

Met facetfiltering kunt u de facetwaarden beperken die worden geretourneerd aan de waarden die overeenkomen met een opgegeven reguliere expressie. Twee nieuwe parameters accepteren een reguliere expressie die wordt toegepast op het facetveld:

  • includeTermFilter filtert de facetwaarden op de waarden die overeenkomen met de reguliere expressie
  • excludeTermFilter hiermee worden de facetwaarden gefilterd op de waarden die niet overeenkomen met de reguliere expressie

Als een facettekenreeks aan beide voorwaarden voldoet, heeft de excludeTermFilter prioriteit omdat de set buckettekenreeksen eerst wordt geëvalueerd met includeTermFilter en vervolgens wordt uitgesloten met excludeTermFilter.

Alleen de facetwaarden die overeenkomen met de reguliere expressie worden geretourneerd. U kunt deze parameters combineren met andere facetopties (bijvoorbeeld count, sorten hiërarchische facetten) voor tekenreeksvelden.

Omdat de reguliere expressie is genest binnen een JSON-tekenreekswaarde, moet u zowel de dubbele aanhalingstekens (") als de backslashtekens (\) escapen. De reguliere expressie zelf wordt begrensd door de schuine streep (/). Zie Reguliere expressiezoekopdrachten voor meer informatie over escape-patronen.

In het volgende voorbeeld ziet u hoe u speciale tekens in uw reguliere expressie kunt escapen, zoals backslash, dubbele aanhalingstekens of syntaxis van reguliere expressies.

{
    "search": "*", 
    "facets": ["name,includeTermFilter:/EscapeBackslash\\\OrDoubleQuote\\"OrRegexCharacter\\(/"] 
}

Hier volgt een voorbeeld van een facetfilter dat van toepassing is op budget- en Extended-Stay-hotels, waarbij Waardering als subcategorie binnen elke hotelcategorie geldt.

POST /indexes/hotels-sample-index/docs/search?api-version=2025-11-01-Preview
{ 
    "search": "*", 
    "facets": ["(Category,includeTermFilter:/(Budget|Extended-Stay)/)>Rating,values:1|2|3|4|5"],
    "select": "HotelName, Category, Rating",
    "count": true 
}

Het volgende voorbeeld is een verkort antwoord (hoteldocumenten worden weggelaten voor beknoptheid).

{
  "@odata.count": 50,
  "@search.facets": {
    "Category": [
      {
        "value": "Budget",
        "count": 13,
        "@search.facets": {
          "Rating": [
            {
              "to": 1,
              "count": 0
            },
            {
              "from": 1,
              "to": 2,
              "count": 0
            },
            {
              "from": 2,
              "to": 3,
              "count": 4
            },
            {
              "from": 3,
              "to": 4,
              "count": 5
            },
            {
              "from": 4,
              "to": 5,
              "count": 4
            },
            {
              "from": 5,
              "count": 0
            }
          ]
        }
      },
      {
        "value": "Extended-Stay",
        "count": 6,
        "@search.facets": {
          "Rating": [
            {
              "to": 1,
              "count": 0
            },
            {
              "from": 1,
              "to": 2,
              "count": 0
            },
            {
              "from": 2,
              "to": 3,
              "count": 4
            },
            {
              "from": 3,
              "to": 4,
              "count": 1
            },
            {
              "from": 4,
              "to": 5,
              "count": 1
            },
            {
              "from": 5,
              "count": 0
            }
          ]
        }
      }
    ]
  }, 
  "value": [  ALL 50 HOTELS APPEAR HERE ]
}

Voorbeeld van facetaggregatie

Opmerking

Deze functie is momenteel beschikbaar als openbare preview-versie. Deze preview wordt geleverd zonder service level agreement en wordt niet aanbevolen voor productieworkloads. Bepaalde functies worden mogelijk niet ondersteund of hebben mogelijk beperkte mogelijkheden. Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure Previewsvoor meer informatie.

Met behulp van de nieuwste preview-REST API of Azure Portal kunt u facetten aggregeren.

Met Facetaggregaties kunt u metrische gegevens berekenen op basis van facetwaarden. De aggregatiemogelijkheid werkt naast de bestaande facetteringsopties.

Verzamelaar Beschrijving
Som Retourneert de totale samengevoegde waarde uit het veld in alle documenten. Alleen van toepassing op numerieke typen. Ondersteund in eerdere preview-versies.
Minuut Retourneert de minimumwaarde van het veld in alle documenten. Alleen van toepassing op numerieke typen.
Max Retourneert de maximumwaarde van het veld in alle documenten. Alleen van toepassing op numerieke typen.
Gemiddelde Retourneert de gemiddelde waarde uit het veld in alle documenten. Alleen van toepassing op numerieke typen.
Kardinaliteit Retourneert het geschatte aantal afzonderlijke waarden uit het veld in alle documenten met behulp van het HyperLogLog-algoritme. U kunt cardinality aanvragen voor facetable-velden, waaronder tekenreeks- en datum/tijd-velden (samen met de bijbehorende verzamelvormen).

Precisiedrempels instellen voor kardinaliteitsaggregatie

In een kardinaliteitsaggregatie kunt u een precisionThreshold optie instellen als een afbakening tussen aantallen die naar verwachting dicht bij nauwkeurig zijn en aantallen die minder nauwkeurig kunnen zijn. De maximumwaarde is 40.000. De standaardwaarde is 3000.

Faceting wordt uitgevoerd in het geheugen. Het verhogen van precisionThreshold resulteert in meer geheugenverbruik (de precisionThreshold waarde vermenigvuldigd met 8 bytes).

Voorbeeld: Facetsomaggregatie

U kunt elk facetable veld van een numeriek gegevenstype optellen (behalve vectoren en geografische coördinaten).

Hier volgt een voorbeeld met behulp van de hotels-sample-index. Het veld Rooms/SleepsCount is facetable en numeriek, dus we kiezen dit veld om het totaal te berekenen. Als we dat veld optellen, krijgen we het aantal slaapstanden voor het hele hotel. Zoals u weet, tellen facetten het bovenliggende document (Hotels) en niet tussenliggende subdocumenten (Kamers), dus het antwoord telt de SleepsCount van alle kamers voor het hele hotel op. In deze query voegen we een filter toe om de SleepsCount voor slechts één hotel op te tellen.

POST /indexes/hotels-sample-index/docs/search?api-version=2025-11-01-Preview

{ 
      "search": "*",
      "filter": "HotelId eq '41'",
      "facets": [ "Rooms/SleepsCount, metric: sum"],
      "select": "HotelId, HotelName, Rooms/Type, Rooms/SleepsCount",
      "count": true
}

Een antwoord voor de query kan eruitzien als in het volgende voorbeeld. Windy Ocean Model is geschikt voor in totaal 40 gasten.

{
  "@odata.count": 1,
  "@search.facets": {
    "Rooms/SleepsCount": [
      {
        "sum": 40.0
      }
    ]
  },
  "value": [
    {
      "@search.score": 1.0,
      "HotelId": "41",
      "HotelName": "Windy Ocean Motel",
      "Rooms": [
        {
          "Type": "Suite",
          "SleepsCount": 4
        },
        {
          "Type": "Deluxe Room",
          "SleepsCount": 2
        },
        {
          "Type": "Budget Room",
          "SleepsCount": 2
        },
        {
          "Type": "Budget Room",
          "SleepsCount": 2
        },
        {
          "Type": "Suite",
          "SleepsCount": 2
        },
        {
          "Type": "Standard Room",
          "SleepsCount": 2
        },
        {
          "Type": "Deluxe Room",
          "SleepsCount": 2
        },
        {
          "Type": "Suite",
          "SleepsCount": 2
        },
        {
          "Type": "Suite",
          "SleepsCount": 4
        },
        {
          "Type": "Standard Room",
          "SleepsCount": 4
        },
        {
          "Type": "Standard Room",
          "SleepsCount": 2
        },
        {
          "Type": "Deluxe Room",
          "SleepsCount": 2
        },
        {
          "Type": "Suite",
          "SleepsCount": 2
        },
        {
          "Type": "Standard Room",
          "SleepsCount": 2
        },
        {
          "Type": "Deluxe Room",
          "SleepsCount": 2
        },
        {
          "Type": "Deluxe Room",
          "SleepsCount": 2
        },
        {
          "Type": "Standard Room",
          "SleepsCount": 2
        }
      ]
    }
  ]
}

Voorbeeld: Een samengestelde verzameling van alle aggregaties

Hier volgt een voorbeeld met behulp van een hypothetische facetindex die de syntaxis voor elke aggregatie weergeeft. U ziet dat kardinaliteit een extra precisionThreshold optie heeft (standaard is 3.000) ingesteld op 40.000 in dit voorbeeld.

POST https://search-service.search.windows.net/indexes/facets/docs/search?api-version=2025-11-01-Preview 
Authorization: Bearer {{token}}
Content-Type: application/json

{
    "search": "*",
    "facets": [// field names are named <something>Value in this example 
        "cardinalityValue, metric: cardinality,precisionThreshold: 40000", 
        "sumValue,metric: sum", 
        "avgValue,metric: avg", 
        "minValue,metric: min", 
        "maxValue,metric: max" 
    ] 
}

Een antwoord voor de query kan eruitzien als in het volgende voorbeeld.

{ 
    "@search.facets": { 
        "cardinalityValue": [ 
            { 
                "cardinality": 24000 // Number of distinct values in "cardinalityValue" field 
            } 
        ], 
        "sumValue": [ 
            { 
                "sum": 1200000 // Sum of all values in "sumValue" field 
            } 
        ], 
        "avgValue": [ 
            { 
                "avg": 50 // Average of all values in "avgValue" field 
            } 
        ], 
        "minValue": [ 
            { 
                "min": 1 // Minimum value in "minValue" field 
            } 
        ], 
        "maxValue": [ 
            { 
                "max": 100 // Maximum value in "maxValue" field 
            } 
        ] 
    } 
}

Voorbeeld: Geef een standaardwaarde op die moet worden vervangen door ontbrekende waarden

Alle metrische gegevens ondersteunen het opgeven van een standaardwaarde wanneer een document geen waarde bevat.

  • Voor niet-tekenreekstypen (numeriek, datum/tijd, booleaanse waarde) stelt u de default parameter in op een specifieke waarde: "default: 42" .

  • Voor tekenreekstypen stelt u de default parameter in op een tekenreeks, gescheiden met behulp van het enkele apostrofscheidingsteken: "default: 'mystringhere'".

U kunt een standaardwaarde toevoegen die moet worden gebruikt als een document een null voor dat veld bevat: "facets": [ "Rooms/SleepsCount, metric: sum, default:2"] Als een ruimte een null-waarde heeft voor het veld Rooms/SleepsCount, wordt de standaardwaarde vervangen door de ontbrekende waarde.

Hier volgt een aanvraag die de standaardspecificatie voor elk veldtype illustreert.

POST https://search-service.search.windows.net/indexes/facets/docs/search?api-version=2025-11-01-Preview 
Authorization: Bearer {{token}} 
Content-Type: application/json 

{ 
    "search": "*", 
    "facets": [// field names are named <datatype>Value in this example 
        "stringfield, metric: cardinality, default: 'my string goes here'", 
        "doubleField,metric: sum, default: 5.0", 
        "intField,metric: sum, default: 5", 
        "longField,metric: sum, default: 5" 
    ] 
}

Voor tekenreeksvelden wordt een standaardwaarde afgebakend door het enkele aanhalingsteken. Als u het teken wilt ontsnappen, moet u het voorvoegsel met de backslash ''' gebruiken. Alle tekens zijn geldig binnen de insluittekens. Het eindteken mag geen backslash zijn.

Voorbeeld: Meerdere metrische gegevens in hetzelfde veld

Als de onderliggende gegevens ondersteuning bieden voor de use-case, kunt u meerdere metrische gegevens voor hetzelfde veld opgeven.

POST https://search-service.search.windows.net/indexes/facets/docs/search?api-version=2025-11-01-Preview 
Authorization: Bearer {{token}} 
Content-Type: application/json 

{ 
    "search": "*", 
    "facets": [ 
        "fieldA, metric: cardinality, precisionThreshold: 40000", 
        "fieldA, metric: sum", 
        "fieldA, metric: avg", 
        "fieldA, metric: min", 
        "fieldA, metric: max" 
    ] 
}

Een antwoord voor de query kan eruitzien als in het volgende voorbeeld.

{ 
    "@search.facets": { 
        "fieldA": [ 
            { 
                "cardinality": 24000 // Number of distinct values in "fieldA" field 
            }, 
            { 
                "sum": 1200000 // Sum of all values in " fieldA " field 
            }, 
            { 
                "avg": 5 // Avg of all values in " fieldA " field
            }, 
            { 
                "min": 0 // Min of all values in " fieldA " field 
            }, 
            { 
                "max": 1200 // Max of all values in " fieldA " field 
            } 
        ] 
    } 
}

Volgende stappen

Ga opnieuw naar de facetnavigatieconfiguratie voor hulpprogramma's en API's en bekijk de aanbevolen procedures voor het werken met facetten in code.

Wij raden aan de C#: Zoekfunctie toe te voegen aan web-apps als een voorbeeld van facetnavigatie, inclusief code voor de presentatielaag. Het voorbeeld bevat ook filters, suggesties en automatisch aanvullen. Het maakt gebruik van JavaScript en React voor de presentatielaag.

  • Last updated on