Exemplos de navegação facetada

Esta secção estende a configuração de navegação facetada com exemplos que demonstram o uso básico e outros cenários.

Os campos de facetable são definidos num índice, mas os parâmetros de facetas e expressões são definidos nos pedidos de consulta. Se tiver um índice com campos que permitem facetas, pode experimentar hierarquias de facetas (pré-visualização), agregações de facetas (pré-visualização) e filtros de facetas (pré-visualização) nos índices existentes.

Parâmetros e sintaxe das facetas

Dependendo da API, uma consulta de faceta é geralmente uma matriz de expressões facetadas que são aplicadas aos resultados de pesquisa. Cada expressão facetária contém um nome de campo facetable, seguido opcionalmente por uma lista de pares nome-valor separados por vírgulas.

• A consulta de faceta é um pedido de consulta que inclui uma propriedade de faceta.
• Campo facetable é uma definição de campo no índice de pesquisa associada à propriedade facetable.
• A contagem é o número de correspondências para cada faceta encontrada nos resultados de pesquisa.

A tabela seguinte descreve os parâmetros das facetas usados nos exemplos.

count e sort podem ser combinados na mesma especificação de faceta, mas não podem ser combinados com interval ou values.

interval e values não podem ser combinados.

As facetas de intervalo de data e hora são calculadas com base na hora UTC se timeoffset não for especificado. Por exemplo, para "facet=lastRenovationDate,interval:day", a fronteira do dia começa às 00:00:00 UTC.

Exemplo básico de facetas

As seguintes consultas de faceta funcionam contra o índice de amostra de hotéis. Pode usar a visualização JSON no Explorador de Pesquisa para colar a consulta JSON. Para ajuda para começar, consulte Adicionar navegação facetada aos resultados da pesquisa.

Esta primeira consulta recupera facetas para Categorias, Classificações, Etiquetas e salas com valores de tarifa base em intervalos específicos. Note que a última faceta está num subcampo da coleção Rooms. As facetas contam o documento principal (Hotéis) e não os subdocumentos intermédios (Quartos), portanto, a resposta contabiliza o número de hotéis que têm quartos em qualquer categoria de preços.

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 
}  

Este segundo exemplo utiliza um filtro para restringir o resultado da consulta facetada anterior após o utilizador selecionar Classificação 3 e a categoria "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  
} 

O terceiro exemplo estabelece um limite superior para termos únicos devolvidos numa consulta. O valor padrão é 10, mas podes aumentar ou diminuir esse valor usando o parâmetro count no atributo facetário. Este exemplo devolve facetas para a cidade, limitadas a 5.

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

Este exemplo apresenta três facetas para "Categoria", "Etiquetas" e "Classificação", com uma sobreposição de contagem em "Etiquetas" e uma sobreposição de intervalo para "Classificação", que de outra forma é armazenada como um duplo no índice.

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
}

Para cada árvore de navegação facetada, existe um limite padrão das 10 principais instâncias facetadas encontradas pela consulta. Este padrão faz sentido para estruturas de navegação porque mantém a lista de valores num tamanho gerível. Podes ultrapassar o padrão atribuindo um valor a "count". Por exemplo, "Tags,count:5" reduz o número de etiquetas na secção de Etiquetas para as cinco principais.

Para valores Numéricos e DateTime apenas, pode definir explicitamente valores no campo de faceta (por exemplo, facet=Rating,values:1|2|3|4|5) para separar os resultados em intervalos contíguos (sejam intervalos baseados em valores numéricos ou períodos de tempo). Alternativamente, pode adicionar "intervalo", como em facet=Rating,interval:1.

Cada intervalo é construído usando 0 como ponto de partida, um valor da lista como ponto final, e depois cortado do intervalo anterior para criar intervalos discretos.

Exemplo de valores distintos

Podes formular uma consulta que devolve uma contagem de valores distinta para cada campo de facetable. Este exemplo formula uma consulta vazia ou não qualificada ("search": "*") que corresponde em todos os documentos, mas ao definir top para zero, obtém-se apenas as contagens, sem resultados.

Para brevidade, esta consulta inclui apenas dois campos marcados como facetable no índice de amostra de hotéis.

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

Os resultados desta consulta são os seguintes:

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

Exemplo de hierarquia de facetas (pré-visualização)

Usando a API REST mais recente pré-visualização ou o portal Azure, pode configurar uma hierarquia de facetas usando os operadores > e ;.

A ordem das operações numa expressão de facetas que inclui hierarquias de facetas é:

• O operador de opções (vírgula ,) que separa os parâmetros de faceta para o campo de faceta, como a vírgula em Rooms/BaseRate,values
• Os parênteses, como os que incluem (Rooms/BaseRate,values:50 ; Rooms/Type).
• O operador de aninhamento (parêntese angular >)
• O operador de adição (designado pelo ponto e vírgula ;), é demonstrado num segundo exemplo "Tags>(Rooms/BaseRate,values:50 ; Rooms/Type)" desta secção, onde duas facetas filhas estão ao mesmo nível sob o elemento Tags.

Note que os parênteses são processados antes do aninhamento e das operações de anexação: A > B ; C seria diferente de A > (B ; C).

Existem vários exemplos de hierarquias facetárias. O primeiro exemplo é uma consulta que devolve apenas alguns documentos, o que é útil para ver uma resposta completa. As facetas contam o documento pai (Hotéis) e não subdocumentos intermédios (Quartos), pelo que a resposta determina o número de hotéis que têm quartos em cada grupo de facetas.

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 
}

Os resultados desta consulta são os seguintes. Ambos os hotéis têm piscinas. Para outras etiquetas, apenas um hotel oferece a comodidade.

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

Este segundo exemplo estende o anterior, demonstrando múltiplas facetas de topo com múltiplos filhos. Note que o operador ponto e vírgula (;) separa cada filho.

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 
}  

Uma resposta parcial, cortada para maior brevidade, mostra tags com subfacetas para o tipo de quarto e o preço base. No índice de amostra de hotéis, ambos os hotéis que correspondem a +ocean têm quartos de cada tipo e uma piscina.

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

Este último exemplo mostra as regras de precedência dos parênteses que afetam diretamente os níveis de aninhamento. Suponha que queres devolver uma hierarquia de facetas nesta ordem.

Address/StateProvince
  Address/City
    Category
    Rating

Para devolver esta hierarquia, crie uma consulta onde Categoria e Classificação são irmãs sob Endereço/Cidade.

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

Se remover os parênteses mais internos, Categoria e Classificação deixam de estar no mesmo nível hierárquico porque as regras de precedência determinam que o operador > é avaliado antes do ;.

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

O principal nível principal continua a ser Endereço/EstadoProvíncia, mas agora Endereço/Cidade e Classificação estão no mesmo nível.

Address/StateProvince
  Rating
  Address/City
    Category

Exemplo de filtragem por facetas (pré-visualização)

Usando a API REST preview mais recente ou o portal Azure, pode configurar filtros de facetas.

A filtragem de facetas permite-lhe restringir os valores de facetas devolvidos àqueles que correspondem a uma expressão regular especificada. Dois novos parâmetros aceitam uma expressão regular que é aplicada ao campo facetário:

• includeTermFilter filtra os valores das facetas para aqueles que correspondem à expressão regular
• excludeTermFilter Filtra os valores das facetas para aqueles que não correspondem à expressão regular

Se uma cadeia de facetas satisfizer ambas as condições, a excludeTermFilter tem precedência porque o conjunto de cadeias de categorias é primeiro avaliado com includeTermFilter e depois excluído com excludeTermFilter.

Apenas os valores de faceta que correspondem à expressão regular são devolvidos. Pode combinar estes parâmetros com outras opções de facetas (por exemplo, count, sort, e facetação hierárquica) em campos de strings.

Como a expressão regular está aninhada dentro de um valor de string JSON, deve escapar tanto das aspas duplas (") como do caractere de barra invertida (\). A expressão regular em si é delimitada pela barra frontal (/). Para mais informações sobre padrões de escape, veja Pesquisa por expressões regulares.

O exemplo seguinte mostra como escapar de caracteres especiais na sua expressão regular, como barras adicionais, aspas duplas ou caracteres sintáticos de expressões regulares.

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

Aqui está um exemplo de filtro de facetas que corresponde a hotéis Económicos e de Estadia Prolongada, com a Classificação como subcategoria de cada tipo de hotel.

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 
} 

O exemplo seguinte é uma resposta abreviada (os documentos do hotel são omitidos por brevidade).

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

Exemplo de agregação de facetas (pré-visualização)

Usando a mais recente API REST ou através do portal Azure, pode agregar facetas.

As agregações de facetas permitem-lhe calcular métricas a partir dos valores das facetas. A capacidade de agregação funciona em conjunto com as opções de facetação existentes.

Definição de limiares de precisão para agregação de cardinalidade

Numa agregação de cardinalidades, pode definir uma precisionThreshold opção como demarcação entre contagens que se espera serem próximas da precisão e contagens que podem ser menos precisas. O valor máximo é 40.000. O valor padrão é 3.000.

O facetamento é realizado em memória. Aumentar precisionThreshold resulta num maior consumo de memória (o precisionThreshold valor multiplicado por 8 bytes).

Exemplo: Agregação por soma de facetas

Podes somar qualquer campo facetable de um tipo de dado numérico (exceto vetores e coordenadas geográficas).

Aqui está um exemplo usando o índice de amostra de hotéis. O campo Rooms/SleepsCount é facetable e numérico, por isso escolhemos este campo para demonstrar a soma. Se somarmos esse campo, obtemos a contagem de pernoite de todo o hotel. Lembre-se que as facetas contam o documento principal (Hotéis) e não subdocumentos intermédios (Quartos), pelo que a resposta soma o SleepsCount de todos os quartos de todo o hotel. Nesta consulta, adicionamos um filtro para somar o SleepsCount para apenas um hotel.

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
}

Uma resposta à pergunta pode assemelhar-se ao seguinte exemplo. O modelo Windy Ocean pode acomodar um total de 40 convidados.

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

Exemplo: Um compósito de todas as agregações

Aqui está um exemplo usando um índice hipotético de 'facetas' que mostra a sintaxe de cada agregação. Note que a cardinalidade tem uma opção extra precisionThreshold (o padrão é 3.000) definida para 40.000 neste exemplo.

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

Uma resposta à pergunta pode assemelhar-se ao seguinte exemplo.

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

Exemplo: Especifique um padrão para substituir valores em falta

Todas as métricas suportam especificar um valor padrão quando um documento não contém um valor.

• Para tipos que não são string (numérico, data-hora, booleano), defina o default parâmetro para um valor específico: "default: 42" .

• Para tipos de cadeia, defina o default parâmetro para uma cadeia, delimitada pelo delimitador de apóstrofo único: "default: 'mystringhere'".

Pode adicionar um valor padrão para usar se um documento contiver um null para esse campo: "facets": [ "Rooms/SleepsCount, metric: sum, default:2"]. Se uma sala tiver um valor nulo para o campo Rooms/SleepsCount, o valor padrão substitui o valor em falta.

Aqui está um pedido que ilustra a especificação padrão para cada tipo de campo.

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

Para campos de texto, um valor padrão é delimitado usando o caractere de aspas simples. Para escapar ao carácter, prefixe-o com a barra diagonal "'". Todos os caracteres são válidos dentro dos delimitadores de cadeias. O carácter de terminação não pode ser uma barra invertida.

Exemplo: Múltiplas métricas no mesmo campo

Se os dados subjacentes suportarem o caso de uso, pode especificar múltiplas métricas no mesmo campo.

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

Uma resposta à pergunta pode assemelhar-se ao seguinte exemplo.

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

Próximos passos

Revise a configuração da navegação por facetas para ferramentas e APIs, e reveja as melhores práticas para trabalhar com facetas no código.

Recomendamos o C#: Adicionar pesquisa às aplicações web como exemplo de navegação facetada que inclui código para a camada de apresentação. A amostra inclui também filtros, sugestões e autocompletamento. Utiliza JavaScript e React para a camada de apresentação.