Ejemplos de navegación por facetas

En esta sección se amplía la configuración de navegación por facetas con ejemplos que muestran el uso básico y otros escenarios.

Los campos facetable se definen en un índice, pero los parámetros y expresiones de faceta se definen en las solicitudes de consulta. Si tiene un índice con campos facetables, puede probar jerarquías de facetas (versión preliminar),agregaciones de facetas (versión preliminar) y filtros de faceta (versión preliminar) en índices existentes.

Sintaxis y parámetros de faceta

En función de la API, una consulta de faceta suele ser una matriz de expresiones de faceta que se aplican a los resultados de búsqueda. Cada expresión de faceta contiene un nombre de campo facetable, seguido opcionalmente de una lista separada por comas de pares nombre-valor.

• la consulta de faceta es una solicitud de consulta que incluye una propiedad de faceta.
• El campo facetable es una definición de campo en el índice de búsqueda atribuida con la propiedad facetable.
• count es el número de coincidencias para cada faceta que se encuentra en los resultados de búsqueda.

En la tabla siguiente se describen los parámetros de faceta usados en los ejemplos.

count y sort se pueden combinar en la misma especificación de faceta, pero no se pueden combinar con interval o values.

interval y values no se pueden combinar.

Las facetas de intervalo de fecha y hora se calculan en función de la hora UTC si timeoffset no se ha especificado. Por ejemplo, para "facet=lastRenovationDate,interval:day", el límite del día comienza a las 00:00:00 UTC.

Ejemplo de faceta básica

Las siguientes consultas de faceta funcionan con el índice hotels-sample. Puede usar la vista JSON en el Explorador de búsqueda para pegar la consulta JSON. Para obtener ayuda con la introducción, consulte Adición de navegación por facetas a los resultados de la búsqueda.

Esta primera consulta recupera facetas para Categorías, Clasificaciones, Etiquetas y habitaciones con valores baseRate en intervalos específicos. Observe que la última faceta está en un subcampo de la colección Rooms. Las facetas cuentan el documento primario (Hoteles) y no los subdocumentos intermedios (Rooms), por lo que la respuesta determina el número de hoteles que tienen habitaciones en cada categoría de precios.

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 
}  

En este segundo ejemplo se usa un filtro para restringir el resultado de la consulta por facetas anterior después de que el usuario seleccione Clasificación 3 y categoría "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  
} 

En el tercer ejemplo se establece un límite superior en términos únicos devueltos en una consulta. El valor predeterminado es 10, pero puede aumentar o disminuir este valor mediante el parámetro count en el atributo de faceta. En este ejemplo se devuelven facetas para "city", limitadas a 5.

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

En este ejemplo se muestran tres facetas para "Categoría", "Etiquetas" y "Valoración", con una invalidación de recuento en "Etiquetas" y una invalidación de intervalo para "Valoración", que de lo contrario se almacena como doble en el í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 árbol de navegación por facetas, hay un límite predeterminado de las 10 instancias de faceta principales encontradas por la consulta. Este valor predeterminado tiene sentido para las estructuras de navegación porque mantiene la lista de valores en un tamaño manejable. Puede invalidar el valor predeterminado asignando un valor a "count". Por ejemplo, "Tags,count:5" reduce el número de etiquetas de la sección Etiquetas a los cinco primeros.

Solo para los valores Numeric y DateTime, puede establecer explícitamente valores en el campo de faceta (por ejemplo, facet=Rating,values:1|2|3|4|5) para separar los resultados en intervalos contiguos (ya sea intervalos basados en valores numéricos o períodos de tiempo). Como alternativa, puede agregar "interval", como en facet=Rating,interval:1.

Cada intervalo se crea con 0 como punto de partida, un valor de la lista como punto de conexión y, a continuación, se recorta del intervalo anterior para crear intervalos discretos.

Ejemplo de valores distintos

Puede formular una consulta que devuelva un recuento de valores distinto para cada campo facetable. En este ejemplo se formula una consulta vacía o no calificada ("search": "*") que coincide con todos los documentos, pero al establecer top en cero, se obtienen solo los recuentos, sin resultados.

Por motivos de brevedad, esta consulta incluye solo dos campos marcados como facetable en el índice 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""
    ]
}

Los resultados de esta consulta son los siguientes:

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

Ejemplo de jerarquía de facetas (versión preliminar)

Con la API REST de latest preview o el portal de Azure, puede configurar una jerarquía de facetas mediante los operadores > y ;.

El orden de las operaciones en una expresión de faceta que incluye jerarquías de facetas son:

• Operador de opciones (coma ,) que separa los parámetros para el campo de faceta, como la coma en Rooms/BaseRate,values
• Los paréntesis, como los que encierra (Rooms/BaseRate,values:50 ; Rooms/Type).
• El operador de anidamiento (marcador angular >)
• El operador para anexar (punto y coma ;), que se muestra en un segundo ejemplo "Tags>(Rooms/BaseRate,values:50 ; Rooms/Type)" de esta sección, donde dos facetas secundarias son del mismo nivel en el elemento primario Etiquetas.

Tenga en cuenta que los paréntesis se procesan antes de las operaciones de anidamiento y concatenación: A > B ; C sería diferente de A > (B ; C).

Hay varios ejemplos de jerarquías de facetas. El primer ejemplo es una consulta que devuelve solo algunos documentos, lo que resulta útil para ver una respuesta completa. Las facetas cuentan el documento primario (Hoteles) y no los subdocumentos intermedios (Rooms), por lo que la respuesta determina el número de hoteles que tienen habitaciones en cada cubo 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 
}

Los resultados de esta consulta son los siguientes. Ambos hoteles tienen piscinas. Para otras categorías, solo un hotel ofrece la amenidad.

{
  "@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 ejemplo amplía el anterior, demostrando varias facetas de nivel superior con varios elementos secundarios. Observe que el operador punto y coma (;) separa cada hijo.

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 
}  

Una respuesta parcial, recortada por brevedad, muestra Etiquetas con facetas secundarias para la tarifa base y el tipo de habitaciones. En el índice hotels-sample, ambos hoteles que coinciden con +ocean tienen habitaciones de cada tipo y una 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
            }
          ]
        }}]},
  ...
}

Las reglas de precedencia para los paréntesis que afectan los niveles de anidamiento se muestran en este último ejemplo. Supongamos que quieres devolver una jerarquía de facetas en este orden.

Address/StateProvince
  Address/City
    Category
    Rating

Para devolver esta jerarquía, cree una consulta en la que Category y Rating estén al mismo nivel jerárquico bajo Address/City.

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

Si quita los paréntesis más internos, Category y Rating ya no son hermanos porque las reglas de precedencia significan que el operador > se evalúa antes que ;.

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

El elemento primario de nivel superior sigue siendo Address/StateProvince, pero ahora Address/City y Rating están en el mismo nivel.

Address/StateProvince
  Rating
  Address/City
    Category

Ejemplo de filtrado de facetas (versión preliminar)

Con la API REST de latest preview o el portal de Azure, puede configurar filtros de facetas.

El filtrado de facetas permite restringir los valores de faceta devueltos a los que coinciden con una expresión regular especificada. Dos nuevos parámetros aceptan una expresión regular que se aplica al campo de faceta:

• includeTermFilter filtra los valores de faceta a los que coinciden con la expresión regular.
• excludeTermFilter filtra los valores de faceta a los que no coinciden con la expresión regular

Si una cadena de faceta cumple ambas condiciones, tiene excludeTermFilter prioridad porque el conjunto de cadenas de cubo se evalúa primero con includeTermFilter y, a continuación, se excluye con excludeTermFilter.

Solo se devuelven los valores de faceta que coinciden con la expresión regular. Puede combinar estos parámetros con otras opciones de faceta (por ejemplo, count, sorty faceta jerárquica) en campos de cadena.

Dado que la expresión regular está anidada dentro en un valor de cadena JSON, debe escapar tanto las comillas dobles (") como los caracteres de barra diagonal inversa (\). La propia expresión regular está delimitada por la barra diagonal (/). Para obtener más información sobre los patrones de escape, vea Búsqueda de expresiones regulares.

En el ejemplo siguiente se muestra cómo escapar caracteres especiales en la expresión regular, como barras diagonales inversas, comillas dobles o caracteres de sintaxis de expresiones regulares.

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

Este es un ejemplo de un filtro de faceta que coincide con los hoteles Económico y Estancia ampliada, con Rating como elemento secundario de cada categoría 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 
} 

En el ejemplo siguiente se muestra una respuesta abreviada (los documentos de hotel se omiten para mayor brevedad).

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

Ejemplo de agregación de facetas (versión preliminar)

Con la REST API de vista previa más reciente o el portal de Azure, usted puede agregar facetas.

Las agregaciones de facetas permiten calcular métricas a partir de valores de faceta. La funcionalidad de agregación funciona junto con las opciones de faceta existentes.

Establecimiento de umbrales de precisión para la agregación de cardinalidad

En una agregación de cardinalidad, puede establecer una opción de precisionThreshold como demarcación entre recuentos que se espera que sean precisos y recuentos que pueden ser menos precisos. El valor máximo es 40 000. El valor predeterminado es 3000.

El facetado se realiza en memoria. Incrementar precisionThreshold resulta en un mayor consumo de memoria (el valor de precisionThreshold multiplicado por 8 bytes).

Ejemplo: Agregación de facetas sumatorias

Puede sumar cualquier campo facetable de un tipo de datos numérico (excepto vectores y coordenadas geográficas).

Este es un ejemplo mediante el índice de muestra de hoteles. El campo Rooms/SleepsCount es desglosable y numérico, por eso hemos elegido este campo para demostrar la suma. Si sumamos ese campo, obtenemos el recuento de huéspedes del hotel entero. Recuerde que las facetas cuentan el documento principal (Hoteles) y no los subdocumentos intermedios (Habitaciones), por lo que la respuesta suma el SleepsCount de todas las habitaciones de todo el hotel. En esta consulta, se agrega un filtro para sumar SleepsCount para un solo 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
}

Una respuesta para la consulta podría ser similar al ejemplo siguiente. Windy Ocean Model tiene capacidad para un total de 40 huéspedes.

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

Ejemplo: una composición de todas las agregaciones

Este es un ejemplo mediante un índice hipotético de "facetas" que muestra la sintaxis de cada agregación. Observe que la cardinalidad tiene una opción adicional precisionThreshold (el valor predeterminado es 3000) establecido en 40 000 en este ejemplo.

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

Una respuesta para la consulta podría ser similar al ejemplo siguiente.

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

Ejemplo: Especificar un valor predeterminado para sustituir los valores que faltan

Todas las métricas admiten la especificación de un valor predeterminado cuando un documento no contiene un valor.

• Para los tipos que no son de cadena (numeric, datetime, boolean), establezca el default parámetro en un valor específico: "default: 42" .

• Para los tipos de cadena, establezca el parámetro default en una cadena, delimitado mediante comillas simples: "default: 'mystringhere'".

Puede agregar un valor predeterminado que se usará si un documento contiene un valor NULL para ese campo: "facets": [ "Rooms/SleepsCount, metric: sum, default:2"]. Si una sala tiene un valor NULL para el campo Rooms/SleepsCount, el valor predeterminado sustituye por el valor que falta.

Esta es una solicitud que muestra la especificación predeterminada 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" 
    ] 
} 

En el caso de los campos de cadena, se delimita un valor predeterminado mediante el carácter de comilla simple. Para escapar del carácter, antepóngalo con la barra inversa "\". Todos los caracteres son válidos dentro de los delimitadores de cadena. El carácter de terminación no puede ser una barra diagonal inversa.

Ejemplo: Varias métricas en el mismo campo

Si los datos subyacentes admiten el caso de uso, puede especificar varias métricas en el mismo 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" 
    ] 
}

Una respuesta para la consulta podría ser similar al ejemplo siguiente.

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

Pasos siguientes

Vuelva a consultar la configuración de navegación por facetas para herramientas y API y revise los procedimientos recomendados para trabajar con facetas en el código.

Recomendamos C#: Agregar búsqueda a aplicaciones web como un ejemplo de navegación por facetas que incluye código para la capa de presentación. El ejemplo también incluye filtros, sugerencias y autocompletar. Usa JavaScript y React para la capa de presentación.