Примеры фасетной навигации

В этом разделе расширена фасетная конфигурация навигации с примерами, демонстрирующими базовое использование и другие сценарии.

Фасетные поля определяются в индексе, но параметры фасетов и выражения определяются в запросах. Если у вас есть индекс с полями, поддерживающими фасетирование, вы можете попробовать иерархии фасетов (предварительная версия), агрегации по фасетам (предварительная версия) и фильтры фасетов (предварительная версия) в существующих индексах.

Параметры аспектов и синтаксис

В зависимости от API, запрос аспектов обычно представляет собой массив выражений аспектов, применяемых к результатам поиска. Каждое выражение аспектов содержит имя поля аспектов, за которым при необходимости следует разделенный запятыми список пар "имя-значение".

• faceted query — это запрос, который включает свойство аспекта.
• Поле facetable — это определение поля в индексе поиска, атрибутируемое свойством facetable .
• число совпадений для каждого аспекта, найденного в результатах поиска.

В следующей таблице описаны параметры аспектов, используемые в примерах.

count и sort может сочетаться в одной спецификации аспектов, но они не могут быть объединены с interval или values.

interval и values не может объединяться вместе.

Аспекты интервала в дате вычисляются на основе времени UTC, если timeoffset не указано. Например, для "facet=lastRenovationDate,interval:day", граница дня начинается в 00:00:00 UTC.

Базовый пример аспектов

Следующие фасетные запросы применяются к индексу hotels-sample. Вы можете использовать представление JSON в обозревателе поиска для вставки JSON-запроса. Чтобы начать, см. Добавление фасетной навигации в результаты поиска.

Первый запрос получает аспекты для категорий, рейтингов, тегов и комнат с значениями baseRate в определенных диапазонах. Обратите внимание, что последний аспект находится в подфилде коллекции Комнат. Грани учитывают родительский документ (Отели), а не промежуточные поддокументы (Номера), поэтому ответ определяет количество отелей, которые имеют номера в каждой ценовой категории.

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 
}  

Во втором примере фильтр используется для сузки предыдущего результата фасетного запроса после выбора пользователем рейтинга 3 и категории "Мотель".

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  
} 

Третий пример задает верхний предел для уникальных терминов, возвращаемых в запросе. Значение по умолчанию равно 10, но это значение можно увеличить или уменьшить с помощью параметра счетчика в атрибуте аспектов. В этом примере возвращаются аспекты для города, ограниченные 5.

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

В этом примере показаны три фасета для "Категория", "Теги" и "Рейтинг", с переопределением количества для "Теги" и переопределением диапазона для "Рейтинг", который в противном случае хранится как значение типа 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" уменьшите количество тегов в разделе "Теги" до пяти лучших.

Только для числовых значений и значений DateTime можно задать значения в поле граней (например, facet=Rating,values:1|2|3|4|5), чтобы разделить результаты на непрерывные диапазоны (на основе либо числовых значений, либо периодов времени). Кроме того, можно добавить "interval", как и в facet=Rating,interval:1.

Каждый диапазон создается, начиная с 0, выбирая значение из списка в качестве конечной точки, и затем отделяя предыдущий диапазон для создания отдельных интервалов.

Пример уникальных значений

Вы можете сформулировать запрос, возвращающий отдельное число значений для каждого поля фасетной области. В этом примере сформулируется пустой или неквалифицированный запрос ("search": "*"), соответствующий всем документам, но если установить top в ноль, вы получите только подсчёты без результатов.

Для краткости этот запрос содержит только два поля, помеченные как facetable в индексе hotels-sample.

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

Пример иерархии аспектов (предварительная версия)

С помощью последней версии API latest preview REST API или портала Azure можно настроить иерархию аспектов с использованием операторов > и ;.

Порядок операций в выражении аспектов, включающих иерархии аспектов:

• Оператор опций (запятая ,), разделяющий параметры фасетов для поля фасетов, например, запятая в Rooms/BaseRate,values
• Круглые скобки, как те, которые охватывают (Rooms/BaseRate,values:50 ; Rooms/Type).
• Оператор вложенности (угловая скобка >)
• Оператор добавления (точка с запятой ;), показанный во втором примере "Tags>(Rooms/BaseRate,values:50 ; Rooms/Type)" в этом разделе, где два дочерних аспекта являются одноранговым элементом в родительском элементе Тегов.

Обратите внимание, что круглые скобки обрабатываются перед операциями вложения и добавления: A > B ; C будет отличаться от A > (B ; C).

Существует несколько примеров для иерархий аспектов. Первый пример — это запрос, который возвращает только несколько документов, что полезно для просмотра полного ответа. Фасеты подсчитывают родительский документ (Отели), а не промежуточные поддокументы (номера), поэтому ответ определяет количество отелей, имеющих номера в каждом фасете.

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 
}

Результаты этого запроса приведены следующим образом. Оба отеля имеют бассейны. Для других тегов только один отель предоставляет удобства.

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

Второй пример расширяет предыдущий, демонстрируя несколько аспектов верхнего уровня с несколькими дочерними элементами. Обратите внимание, что оператор с точкой с запятой (;) отделяет каждый дочерний элемент.

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

Чтобы вернуть эту иерархию, создайте запрос, в котором категории и рейтинги являются братьями и сестрами в разделе Address/City.

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

Если удалить наиболее внутренние скобки, категория и рейтинг больше не являются братьями и сестрами, так как правила приоритета означают, что > оператор вычисляется раньше ;.

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

Родительским элементом верхнего уровня по-прежнему является Адрес/StateProvince, но теперь Адрес/Город и Рейтинг находятся на одном уровне.

Address/StateProvince
  Rating
  Address/City
    Category

Пример фильтрации аспектов (предварительная версия)

С помощью REST API latest preview REST API или портала Azure можно настроить фильтры аспектов.

Фасетная фильтрация позволяет ограничить значения фасетов, соответствующие указанному регулярному выражению. Два новых параметра принимают регулярное выражение, которое применяется к полю аспектов:

• includeTermFilter фильтрует значения аспектов для тех, которые соответствуют регулярному выражению
• excludeTermFilter фильтрует значения аспектов для тех, которые не соответствуют регулярному выражению

Если строка фасета удовлетворяет обоим условиям, excludeTermFilter имеет приоритет, потому что набор строк для группировки сначала оценивается с помощью includeTermFilter, а затем исключается с excludeTermFilter.

Возвращаются только те значения аспектов, которые соответствуют регулярному выражению. Эти параметры можно объединить с другими вариантами опций граней (например, count, sort, и иерархическим фасетированием) в строковых полях.

Так как регулярное выражение вложено в строковое значение JSON, необходимо избежать двойной кавычки (") и символов обратной косой черты (\). Регулярное выражение ограничено косой чертой (/). Дополнительные сведения о шаблонах escape-адресов см. в статье "Поиск регулярных выражений".

В следующем примере показано, как избежать специальных символов в регулярном выражении, таких как обратная косая черта, двойные кавычки или символы синтаксиса регулярных выражений.

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

Пример агрегирования аспектов (предварительная версия)

С помощью latest preview REST API или портала Azure можно агрегировать аспекты.

Агрегаты аспектов позволяют вычислять метрики из значений аспектов. Возможность агрегирования работает вместе с существующими параметрами фасетов.

Задание пороговых значений точности для агрегирования кратности

При агрегации кардинальности можно задать параметр precisionThreshold как демаркацию между подсчетами, которые ожидаются как близкие к точным, и менее точными подсчетами. Максимальное значение — 40 000. Значение по умолчанию — 3000.

Фасетирование производится в памяти. Увеличение precisionThreshold приводит к большему потреблению памяти (precisionThreshold значение, умноженное на 8 байт).

Пример: агрегирование аспектов суммы

Можно суммировать любое поле аспектов числового типа данных (за исключением векторов и географических координат).

Ниже приведен пример использования индекса hotels-sample. Поле Rooms/SleepsCount является аспектичным и числовым, поэтому мы выбираем это поле для демонстрации суммы. Если мы суммируем это поле, мы получаем количество сна для всего отеля. Помните, что фасеты считают основной документ (Отели), а не промежуточные поддокументы (номера), поэтому ответ суммирует SleepsCount всех номеров одного отеля. В этом запросе мы добавляем фильтр, чтобы подсчитать значение 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
}

Ответ запроса может выглядеть следующим образом. Windy Ocean Model может разместить в общей сложности 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 
            } 
        ] 
    } 
}

Пример. Указание значения по умолчанию для замены отсутствующих значений

Все метрики поддерживают указание значения по умолчанию, если документ не содержит значения.

• Для нестроковых типов (числовых, дата-время, логических) задайте параметру 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#: добавление поиска в веб-приложения как пример фасетной навигации, включающий код для уровня представления. В этом примере также содержатся фильтры, предложения и автозавершение. Он использует JavaScript и React для слоя презентации.