Fasetterade navigeringsexempel

Det här avsnittet utökar fasetterad navigeringskonfiguration med exempel som visar grundläggande användning och andra scenarier.

Fasettfält definieras i ett index, men fasettparametrar och uttryck definieras i frågebegäranden. Om du har ett index med fasettfält kan du prova fasetthierarkier (förhandsversion), fasettaggregeringar (förhandsversion)och fasettfilter (förhandsversion) på befintliga index.

Fasetteringsparametrar och syntax

Beroende på API:et är en fasetteringsfråga vanligtvis en matris med fasetteringsuttryck som tillämpas på sökresultat. Varje fasettuttryck innehåller ett facetable-fältnamn, eventuellt följt av en kommaavgränsad lista över namn/värde-par.

• fasetteringsfråga är en frågebegäran som innehåller en aspektegenskap.
• facetable-fältet är en fältdefinition i sökindexet som tillskrivs egenskapen facetable .
• count är antalet matchningar för varje aspekt som hittas i sökresultaten.

I följande tabell beskrivs fasetteringsparametrar som används i exemplen.

count och sort kan kombineras i samma aspektspecifikation, men de kan inte kombineras med interval eller values.

interval och values kan inte kombineras tillsammans.

Intervallfasetter på datum och tid beräknas baserat på UTC-tid om timeoffset inte har angetts. För exempel "facet=lastRenovationDate,interval:day" börjar daggränsen vid 00:00:00 UTC.

Exempel på grundläggande fasett

Följande fasetteringsfrågor fungerar mot hotels-sample-indexet. Du kan använda JSON-vyn i Sökutforskaren för att klistra in JSON-frågan. Hjälp med att komma igång finns i Lägga till fasetterad navigering i sökresultat.

Den här första frågan hämtar fasetter för kategorier, klassificeringar, taggar och rum med baseRate-värden i specifika intervall. Observera att den sista fasetten finns på ett delområde av samlingen Rooms. Fasetter räknar det överordnade dokumentet (Hotell) och inte mellanliggande underdokument (Rum), så svaret avgör antalet hotell som har några rum i varje priskategori.

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

Det andra exemplet använder ett filter för att begränsa det tidigare fasetterade frågeresultatet när användaren har valt Omdöme 3 och kategorin "Motel".

POST /indexes/hotels-sample/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  
} 

Det tredje exemplet anger en övre gräns för unika termer som returneras i en fråga. Standardvärdet är 10, men du kan öka eller minska det här värdet med hjälp av parametern count i aspektattributet. Det här exemplet returnerar fasetter för stad, begränsat till 5.

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

I det här exemplet visas tre fasetter för "Kategori", "Taggar" och "Klassificering", med en antalöverskridning för "Taggar" och en intervalöverskridning för "Klassificering", vilket annars lagras som ett flyttal i indexet.

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

För varje fasetterad navigeringsträd finns en standardgräns för de 10 främsta fasettinstanser som identifieras av frågan. Den här standardinställningen är lämplig för navigeringsstrukturer eftersom den håller värdelistan till en hanterbar storlek. Du kan åsidosätta standardvärdet genom att tilldela ett värde till "count". Till "Tags,count:5" exempel minskar antalet taggar under avsnittet Taggar till de fem översta.

Endast för numeriska värden och DateTime-värden kan du uttryckligen ange värden i fasetteringsfältet (till exempel facet=Rating,values:1|2|3|4|5) för att separera resultat i sammanhängande intervall (antingen intervall baserade på numeriska värden eller tidsperioder). Du kan också lägga till "intervall", som i facet=Rating,interval:1.

Varje intervall skapas med 0 som utgångspunkt, ett värde från listan som en slutpunkt och trimmas sedan av föregående intervall för att skapa diskreta intervall.

Exempel på distinkta värden

Du kan formulera en fråga som returnerar ett distinkt värdeantal för varje fasettbart fält. I det här exemplet formuleras en tom eller okvalificerad fråga ("search": "*") som matchar alla dokument, men genom att ange top noll får du bara antalet utan resultat.

För korthet innehåller den här frågan bara två fält som markerats som facetable i hotels-sample-indexet.

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

Resultatet från den här frågan är följande:

{
  "@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": []
}

Exempel på fasetteringshierarki (förhandsversion)

Med den senaste förhandsvisningen av REST API:et eller via Azure-portalen kan du konfigurera en facetthierarki med operatorerna och .

Ordningen för operationerna i ett facetuttryck som innehåller facetthierarkier är:

• Alternativoperatorn (kommatecken ,) som separerar fasetteringsparametrar för fasetteringsfältet, till exempel kommatecknet i Rooms/BaseRate,values
• Parenteserna, till exempel de som omger (Rooms/BaseRate,values:50 ; Rooms/Type).
• Kapslingsoperatorn (vinkelparentes >)
• Tilläggsoperatorn (semikolon ;), som visas i ett andra exempel "Tags>(Rooms/BaseRate,values:50 ; Rooms/Type)" i det här avsnittet, där två underordnade fasetter är peer-datorer under överordnad Taggar.

Observera att parenteser bearbetas före kapslings- och tilläggsåtgärder: A > B ; C skulle vara annorlunda än A > (B ; C).

Det finns flera exempel på fasetteringshierarkier. Det första exemplet är en fråga som bara returnerar några dokument, vilket är användbart för att visa ett fullständigt svar. Fasetterna räknar det överordnade dokumentet (Hotell) och inte mellanliggande underdokument (Rum), så svaret bestämmer antalet hotell som har rum i varje fasettkategori.

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

Resultatet från den här frågan är följande. Båda hotellen har pooler. För andra taggar erbjuder endast ett hotell bekvämligheterna.

{
  "@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"
      }
    }
  ]
}

Det andra exemplet utökar det föregående, vilket visar flera fasetter på den översta nivån med flera underordnade objekt. Observera att semikolonoperatorn (;) separerar varje underordnat element.

POST /indexes/hotels-sample/docs/search?api-version=2026-08-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 
}  

Ett partiellt svar, trimmat för korthet, visar Taggar med underordnade fasetter för rummens basfrekvens och typ. I hotell-exempelindexet matchar båda hotellen +ocean och har rum av varje typ samt en pool.

{
  "@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
            }
          ]
        }}]},
  ...
}

Det sista exemplet visar prioritetsregler för parenteser som påverkar kapslingsnivåer. Anta att du vill returnera en fasethierarki i den här ordningen.

Address/StateProvince
  Address/City
    Category
    Rating

Om du vill returnera den här hierarkin skapar du en fråga där Kategori och Klassificering är syskon under Adress/Ort.

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

Om du tar bort de innersta parenteserna är Kategori och Klassificering inte längre syskon eftersom prioritetsreglerna innebär att operatorn > utvärderas före ;.

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

Den överordnade nivån är fortfarande Adress/Län, men nu är Adress/Stad och Omdöme på samma nivå.

Address/StateProvince
  Rating
  Address/City
    Category

Exempel på fasetteringsfiltrering (förhandsversion)

Med det senaste förhandsgransknings-REST API:et eller genom Azure-portalen kan du konfigurera fasetfilter.

Med fasetteringsfiltrering kan du begränsa de fasetterade värden som returneras till dem som matchar ett angivet reguljärt uttryck. Två nya parametrar accepterar ett reguljärt uttryck som tillämpas på fasetteringsfältet:

• includeTermFilter filtrerar facetvärdena som matchar det reguljära uttrycket
• excludeTermFilter filtrerar facettvärdena till dem som inte matchar det reguljära uttrycket

Om en fasetteringssträng uppfyller båda villkoren excludeTermFilter har den företräde eftersom uppsättningen bucketsträngar först utvärderas med includeTermFilter och sedan exkluderas med excludeTermFilter.

Endast de fasetteringsvärden som matchar det reguljära uttrycket returneras. Du kan kombinera dessa parametrar med andra fasetteringsalternativ (till exempel count, sortoch hierarkisk fasettering) i strängfält.

Eftersom det reguljära uttrycket är kapslat i ett JSON-strängvärde måste du undvika både de dubbla citattecknen (") och omvänt snedstreck (\). Det reguljära uttrycket avgränsas av snedstrecket (/). Mer information om escape-mönster finns i Sök efter reguljära uttryck.

I följande exempel visas hur du undfly specialtecken i ditt reguljära uttryck, till exempel omvänt snedstreck, dubbla citattecken eller syntaxtecken för reguljära uttryck.

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

Här är ett exempel på ett fasettfilter som matchar på budget- och Extended-Stay-hotell, med Betyg som en underkategori i varje hotellkategori.

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

Följande exempel är ett förkortat svar (hotelldokument utelämnas för korthet).

{
  "@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 ]
}

Exempel på fasetteringsaggregering (förhandsversion)

Med rest-API:et latest preview eller Azure-portalen kan du aggregera fasetter.

Med fasetteringsaggregeringar kan du beräkna mått från fasetteringsvärden. Aggregeringsfunktionen fungerar tillsammans med befintliga fasetteringsalternativ.

Ange precisionströsklar för kardinalitetsaggregering

I en kardinalitetsaggregering kan du ange ett precisionThreshold alternativ som en avgränsning mellan antal som förväntas vara nära korrekta och antal som kan vara mindre exakta. Det maximala värdet är 40 000. Standardvärdet är 3 000.

Fasettering utförs i minnet. Om du ökar precisionThreshold blir minnesförbrukningen större (värdet precisionThreshold multiplicerat med 8 byte).

Exempel: Summa fasettsaggregering

Du kan summera valfritt fält med en numerisk datatyp (förutom vektorer och geografiska koordinater).

Här är ett exempel med hjälp av hotels-sample-indexet. Fältet Rooms/SleepsCount är fasettbart och numeriskt, så vi väljer det här fältet för att visa summa. Om vi summerar fältet får vi sömnantalet för hela hotellet. Kom ihåg att facetter räknar huvuddokumentet (Hotell) och inte mellanliggande underdokument (Rum), vilket innebär att svaret summerar SleepsCount för alla rum för hela hotellet. I den här frågan lägger vi till ett filter för att summera SleepsCount för bara ett hotell.

POST /indexes/hotels-sample/docs/search?api-version=2026-08-01-preview

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

Ett svar för frågan kan se ut som i följande exempel. Windy Ocean Model rymmer totalt 40 gäster.

{
  "@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
        }
      ]
    }
  ]
}

Exempel: En sammansättning av alla sammansättningar

Här är ett exempel med hjälp av ett hypotetiskt "fasetter"-index som visar syntaxen för varje aggregering. Observera att kardinaliteten har ett extra precisionThreshold alternativ (standardvärdet är 3 000) inställt på 40 000 i det här exemplet.

POST https://search-service.search.windows.net/indexes/facets/docs/search?api-version=2026-08-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" 
    ] 
}

Ett svar för frågan kan se ut som i följande exempel.

{ 
    "@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 
            } 
        ] 
    } 
}

Exempel: Ange ett standardvärde för att ersätta saknade värden

Alla mått har stöd för att ange ett standardvärde när ett dokument inte innehåller något värde.

• För icke-strängtyper (numeriska, datetime, booleska) anger du parametern default till ett specifikt värde: "default: 42" .

• För strängtyper anger du parametern default till en sträng, avgränsad med hjälp av den enda apostroheavgränsaren: "default: 'mystringhere'".

Du kan lägga till ett standardvärde som ska användas om ett dokument innehåller en null för fältet: "facets": [ "Rooms/SleepsCount, metric: sum, default:2"]. Om ett rum har ett null-värde för fältet Rum/SleepsCount ersätter standardvärdet för det saknade värdet.

Här är en begäran som illustrerar standardspecifikationen för varje fälttyp.

POST https://search-service.search.windows.net/indexes/facets/docs/search?api-version=2026-08-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" 
    ] 
} 

För strängfält avgränsas ett standardvärde med det enkla citattecknet. Undvik tecknet genom att prefixa det med omvänt snedstreck. Alla tecken är giltiga inom strängavgränsarna. Det avslutande tecknet kan inte vara en backslash.

Exempel: Flera mått i samma fält

Om underliggande data stöder användningsfallet kan du ange flera mått i samma fält.

POST https://search-service.search.windows.net/indexes/facets/docs/search?api-version=2026-08-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" 
    ] 
}

Ett svar för frågan kan se ut som i följande exempel.

{ 
    "@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 
            } 
        ] 
    } 
}

Nästa steg

Gå tillbaka till aspektnavigeringskonfigurationen för verktyg och API:er och granska metodtipsen för att arbeta med fasetter i kod.

Vi rekommenderar C#: Lägg till sökning i webbappar för ett exempel på fasetterad navigering som innehåller kod för presentationsskiktet. Exemplet innehåller även filter, förslag och automatisk komplettering. Den använder JavaScript och React för presentationsskiktet.