ファセット ナビゲーションの例

このセクションでは、基本的な使用方法やその他のシナリオを示す例を使用して 、ファセット ナビゲーションの構成 を拡張します。

ファセット可能フィールドはインデックスで定義されますが、ファセット パラメーターと式はクエリ要求で定義されます。 ファセット可能なフィールドを持つインデックスがある場合は、既存のインデックスで ファセット階層 (プレビュー)、 ファセット集計 (プレビュー)、 ファセット フィルター (プレビュー) を試すことができます。

ファセット パラメーターと構文

API に応じて、ファセット クエリは通常、検索結果に適用されるファセット式の配列です。 各ファセット式にはファセット可能なフィールド名が含まれおり、場合によっては名前と値のペアがコンマで区切られたリストが続くことがあります。

• ファセット クエリ は、ファセット プロパティを含むクエリ要求です。
• facetable フィールド は、 facetable プロパティで属性付けされた検索インデックス内のフィールド定義です。
• count は、検索結果で見つかった各ファセットの一致数です。

次の表では、例で使用されるファセット パラメーターについて説明します。

count sortは同じファセット仕様で結合できますが、intervalやvaluesと組み合わせることはできません。

interval と values を組み合わせることはできません。

日付時刻の間隔ファセットは、 timeoffset が指定されていない場合、UTC 時刻に基づいて計算されます。 たとえば、 "facet=lastRenovationDate,interval:day"の場合、日の境界は UTC の 00:00:00 から始まります。

基本的なファセットの例

次のファセット クエリは 、hotels-sample インデックスに対して機能します。 検索エクスプローラーで JSON ビュー を使用して、JSON クエリに貼り付けることができます。 作業の開始に関するヘルプについては、「 検索結果にファセット ナビゲーションを追加する」を参照してください。

この最初のクエリでは、特定の範囲の baseRate 値を持つカテゴリ、評価、タグ、ルームのファセットを取得します。 最後のファセットが Rooms コレクションのサブフィールドにあることに注意してください。 ファセットは、中間サブドキュメント (Rooms) ではなく親ドキュメント (ホテル) をカウントするため、応答によって、各価格カテゴリに部屋がある ホテル の数が決まります。

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 
}  

この 2 番目の例では、フィルターを使用して、ユーザーが Rating 3 とカテゴリ "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  
} 

3 番目の例では、クエリで返される一意の用語の上限を設定します。 既定値は 10 ですが、ファセット属性の count パラメーターを使用して、この値を増減できます。 次の例では、値が 5 に制限される city のファセットを返します。

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

この例では、"Category"、"Tags"、"Rating" の 3 つのファセットを示し、"Tags" のカウント オーバーライドと "Rating" の範囲オーバーライドを示します。それ以外の場合は、インデックスに double として格納されます。

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
}

ファセット ナビゲーション ツリーごとに、クエリによって検出された上位 10 個のファセット インスタンスの既定の制限があります。 この既定値は、値リストを管理可能なサイズに保持するため、ナビゲーション構造に適しています。 値を "count" に割り当てることで、既定値をオーバーライドできます。 たとえば、 "Tags,count:5" では、[タグ] セクションのタグの数が上位 5 に減ります。

数値と DateTime の値の場合のみ、ファセット フィールド (たとえば、 facet=Rating,values:1|2|3|4|5) に値を明示的に設定して、結果を連続する範囲 (数値または期間に基づく範囲) に分割できます。 または、 facet=Rating,interval:1のように"interval"を追加することもできます。

各範囲は、開始点として 0 を使用し、一覧の値をエンドポイントとして使用し、前の範囲をトリミングして個別の間隔を作成します。

個別の値の例

ファセット可能なフィールドごとに一意の値の数を返すクエリを作成できます。 この例では、すべてのドキュメントに一致する空のクエリまたは非修飾クエリ ("search": "*") を作成しますが、 top を 0 に設定すると、結果なしでカウントだけが取得されます。

簡潔にするために、このクエリには、hotels-sample インデックスに facetable としてマークされた 2 つのフィールドだけが含まれます。

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

このクエリの結果は次のとおりです。

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

ファセット階層の例 (プレビュー)

latest preview REST API または Azure ポータルを使用して、> 演算子と ; 演算子を使用してファセット階層を構成できます。

ファセット階層を含むファセット式の操作の順序は次のとおりです。

• , のコンマなど、ファセット フィールドのファセット パラメーターを区切るオプション演算子 (コンマ Rooms/BaseRate,values)
• 丸括弧（たとえば、(Rooms/BaseRate,values:50 ; Rooms/Type)を囲むもの）。
• 入れ子演算子 (角かっこ >)
• このセクションの 2 番目の例の ; では、追加演算子 (セミコロン "Tags>(Rooms/BaseRate,values:50 ; Rooms/Type)") が使われており、2 つの子ファセットがタグ親の下で同位の位置にあります。

注意してください: 括弧は入れ子操作と追加操作の前に処理されます。A > B ; C は A > (B ; C)とは異なります。

ファセット階層にはいくつかの例があります。 最初の例は、いくつかのドキュメントのみを返すクエリであり、完全な応答を表示するのに役立ちます。 ファセットは親ドキュメント (Hotels) をカウントし、中間サブドキュメント (Rooms) はカウントしないため、応答によって、各ファセット バケットに部屋がある ホテル の数が決まります。

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 
}

このクエリの結果は次のとおりです。 どちらのホテルにもプールがあります。 その他のタグについては、アメニティを提供するホテルは 1 つだけです。

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

この 2 番目の例では、前の例を拡張し、複数の子を持つ複数の最上位ファセットを示します。 セミコロン (;) 演算子は各子を区切ります。

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 
}  

簡潔にするためにトリミングされた部分応答には、部屋の基本料金と種類の子ファセットを含むタグが表示されます。 ホテルサンプルインデックスでは、+ocean に一致する、両方のホテルには各種類の部屋とプールがあります。

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

この最後の例は、入れ子レベルに影響を与える括弧の優先順位の規則を示しています。 ファセット階層をこの順序で返したいとします。

Address/StateProvince
  Address/City
    Category
    Rating

この階層を返すには、カテゴリと評価がアドレス/シティの同階層にあるクエリを作成します。

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

最も内側のかっこを削除すると、優先順位ルールは > 演算子が ;前に評価されることを意味するため、Category と Rating は兄弟ではなくなります。

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

最上位の親は引き続き Address/StateProvince ですが、現在は Address/City と Rating が同じレベルになっています。

Address/StateProvince
  Rating
  Address/City
    Category

ファセット フィルタリングの例 (プレビュー)

最も新しいプレビュー REST API または Azure ポータルを使用して、ファセット フィルターを構成できます。

ファセット フィルターを使用すると、指定した正規表現に一致するファセット値に制限できます。 2 つの新しいパラメーターは、ファセット フィールドに適用される正規表現を受け入れます。

• includeTermFilter 正規表現に一致するものにファセット値をフィルター処理する
• excludeTermFilter は、正規表現と一致しないファセット値にフィルター処理します。

ファセット文字列が両方の条件を満たす場合は、バケット文字列のセットが最初に excludeTermFilter で評価され、次に includeTermFilter で除外されるため、excludeTermFilterが優先されます。

正規表現に一致するファセット値のみが返されます。 これらのパラメーターは、文字列フィールドの他のファセット オプション ( count、 sort、 階層ファセットなど) と組み合わせることができます。

正規表現は JSON 文字列値内で入れ子になっているため、二重引用符 (") 文字と円記号 (\) 文字の両方をエスケープする必要があります。 正規表現自体はスラッシュ (/) で区切られます。 エスケープ パターンの詳細については、「 正規表現の検索」を参照してください。

次の例は、バックスラッシュ、二重引用符、正規表現構文文字などの正規表現の特殊文字をエスケープする方法を示しています。

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

次の予算と長期滞在のホテルに一致するファセット フィルターの例では、評価が各ホテル カテゴリの子要素として含まれています。

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 
} 

次の例は、省略された応答です (簡潔にするためにホテルドキュメントは省略されています)。

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

ファセット集計の例 (プレビュー)

最新のプレビュー REST API または Azure ポータルを使用して、ファセットを集計できます。

ファセット集計を使用すると、ファセット値からメトリックを計算できます。 集計機能は、既存のファセット オプションと共に機能します。

カーディナリティ集計の精度しきい値の設定

カーディナリティ集計では、 precisionThreshold オプションを、正確度に近いカウントと、精度の低いカウントの間の境界として設定できます。 最大値は 40,000 です。 既定値は 3,000 です。

ファセットはメモリ内で実行されます。 precisionThresholdを増やすと、メモリ消費量が増えます (precisionThreshold値に 8 バイトを乗算)。

例: ファセット集計の合計

数値データ型のファセット可能フィールドを合計できます (ベクトルと地理座標を除く)。

hotels-sample インデックスの使用例を次に示します。 Rooms/SleepsCount フィールドはファセット可能で数値であるため、このフィールドを選択して合計を示します。 そのフィールドを合計すると、ホテル全体の睡眠数が取得されます。 ファセットは、中間サブドキュメント (Rooms) ではなく親ドキュメント (ホテル) をカウントするので、応答はホテル全体のすべての部屋の SleepsCount を合計することを思い出してください。 このクエリでは、1 つのホテルの SleepsCount を合計するフィルターを追加します。

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
}

クエリの応答は、次の例のようになります。 ウィンディオーシャンモデルは合計40名のゲストを収容できます。

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

例: すべての集計の複合

各集計の構文を示す架空の "ファセット" インデックスを使用する例を次に示します。 この例では、カーディナリティに追加の precisionThreshold オプション (既定値は 3,000) が 40,000 に設定されていることに注意してください。

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

クエリの応答は、次の例のようになります。

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

例: 欠損値の代わりに既定値を指定する

ドキュメントに値が含まれていない場合、すべてのメトリックで既定値の指定がサポートされます。

• 文字列以外の型 (数値、datetime、ブール値) の場合は、 default パラメーターを特定の値 ( "default: 42" ) に設定します。

• 文字列型の場合は、 default パラメーターを文字列に設定し、単一のアポストロフィ区切り記号 ( "default: 'mystringhere'") を使用して区切ります。

ドキュメントにそのフィールドの null が含まれている場合に使用する既定値を追加できます: "facets": [ "Rooms/SleepsCount, metric: sum, default:2"]。 ルームに Rooms/SleepsCount フィールドに null 値がある場合、既定値は欠損値に置き換われます。

各フィールド型の既定の仕様を示す要求を次に示します。

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

文字列フィールドの場合、既定値は単一引用符文字を使用して区切られます。 文字をエスケープするには、先頭にバックスラッシュ "'" を付けます。 すべての文字は、文字列区切り記号内で有効です。 終了文字をバックスラッシュにすることはできません。

例: 同じフィールド上の複数のメトリック

基になるデータがユース ケースをサポートしている場合は、同じフィールドに複数のメトリックを指定できます。

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

クエリの応答は、次の例のようになります。

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

次の手順

ツールと API の ファセット ナビゲーション構成 を見直し、コードでファセットを操作するための ベスト プラクティス を確認します。

C#: プレゼンテーション レイヤーのコードを含むファセット ナビゲーションの例については、 Web アプリに検索を追加 することをお勧めします。 サンプルには、フィルター、提案、オートコンプリートも含まれています。 プレゼンテーション レイヤーには JavaScript と React が使用されます。