Búsqueda por facetas

La búsqueda por facetas te permite adjuntar información categórica a tus documentos. Una faceta es un par atributo/valor. Por ejemplo, la faceta "tamaño" puede tener los valores "pequeño", "mediano" y "grande".

Al usar facetas con la búsqueda, puedes obtener información resumida que te ayude a acotar una consulta y a desglosar los resultados en una serie de pasos.

Esto resulta útil en aplicaciones como los sitios de compras, donde se pretende ofrecer un conjunto de filtros para que los clientes puedan acotar los productos que quieren ver.

Los datos agregados de una faceta muestran cómo se distribuyen los valores de esa faceta. Por ejemplo, la faceta "tamaño" puede aparecer en muchos de los documentos de tu conjunto de resultados. Los datos agregados de esa faceta pueden mostrar que el valor "pequeño" ha aparecido 100 veces, "mediano" 300 veces y "grande" 250 veces. Cada par facet/valor representa un subconjunto de documentos en el resultado de la consulta. A cada par se le asocia una clave, llamada refinamiento. Puedes incluir acotaciones en una consulta para obtener documentos que coincidan con la cadena de consulta y que tengan los valores de facet correspondientes a una o varias acotaciones.

Cuando realices una búsqueda, puedes elegir las facetas que quieres recoger y mostrar con los resultados, o bien habilitar la detección de facetas para seleccionar automáticamente las que aparecen con más frecuencia en tus documentos.

Añadir facetas a un documento

Añade facetas a un documento antes de añadirlo a un índice. Hazlo al mismo tiempo que especificas los campos del documento:

def add_faceted_document(index):
    document = search.Document(
        doc_id="doc1",
        fields=[search.AtomField(name="name", value="x86")],
        facets=[
            search.AtomFacet(name="type", value="computer"),
            search.NumberFacet(name="ram_size_gb", value=8),
        ],
    )

    index.put(document)

Una faceta es similar a un campo de documento: tiene un nombre y toma un valor.

Los nombres de las facetas siguen las mismas reglas que los campos de los documentos: distinguen entre mayúsculas y minúsculas, y solo pueden contener caracteres ASCII. Deben empezar por una letra y pueden contener letras, números o guiones bajos. El nombre no puede tener más de 500 caracteres.

El valor de una faceta puede ser una cadena atómica (de 500 caracteres como máximo) o un número (un valor de coma flotante de doble precisión comprendido entre -2.147.483.647 y 2.147.483.647).

Puedes asignar varios valores a una faceta de un documento añadiendo una faceta con el mismo nombre y tipo varias veces, usando un valor diferente cada vez.

No hay límite en el número de valores que puede tener una faceta. Tampoco hay límite en cuanto al número de facetas que puede añadir a un documento ni al número de facetas con nombres únicos en un índice.

Ten en cuenta que cada vez que uses una faceta, puede tomar un valor atómico o numérico. Se puede asociar una faceta con el nombre "size" a un documento con el valor de cadena "small" y a otro documento con el valor numérico 8. De hecho, la misma faceta puede aparecer varias veces en el mismo documento con ambos tipos de valores. Aunque se permite, no recomendamos usar valores de átomo y de número para la misma faceta.

Aunque una faceta tiene un tipo específico cuando la añades a un documento, los resultados de búsqueda reúnen todos sus valores. Por ejemplo, los resultados de la faceta "size" pueden mostrar que hubo 100 instancias del valor "small", 150 instancias de "medium" y 135 instancias de valores numéricos en el intervalo [4, 8). No se muestran los valores numéricos exactos ni su distribución de frecuencia.

Cuando recuperas un documento mediante una consulta, no puedes acceder directamente a sus facetas y valores. Debes solicitar que se devuelva la información de las facetas con tu consulta, tal como se explica en la sección siguiente.

Usar una búsqueda por facetas para obtener información de las facetas

Puedes pedirle al backend de búsqueda que descubra las facetas que se usan con más frecuencia. Esto se llama descubrimiento automático de facetas. También puede recuperar información de facetas de forma explícita seleccionando una faceta por su nombre o por su nombre y valor. Puedes combinar los tres tipos de recuperación de facetas en una sola consulta.

Solicitar información de facetas no afectará a los documentos que devuelva tu consulta. Puede afectar al rendimiento. Realizar una búsqueda por facetas con la profundidad predeterminada de 1000 tiene el mismo efecto que definir el límite de puntuación de las opciones de ordenación en 1000.

Descubrimiento automático de facetas

La detección automática de facetas busca las facetas que aparecen con más frecuencia en el conjunto de tus documentos. Por ejemplo, supongamos que los documentos que coinciden con su consulta incluyen una faceta "color" que aparece 5 veces con el valor "rojo", 5 veces con el valor "blanco" y 5 veces con el color "azul". Esta faceta tiene un recuento total de 15. A efectos de descubrimiento, se clasificaría por encima de otra faceta "shade" que aparece en los mismos documentos coincidentes 6 veces con el valor "dark" y 7 veces con el valor "light".

Para habilitar la detección de facetas, debes definirla en la consulta:

def facet_discovery(index):
    # Create the query and enable facet discovery.
    query = search.Query("name:x86", enable_facet_discovery=True)
    results = index.search(query)

    for facet in results.facets:
        print("facet {}.".format(facet.name))
        for value in facet.values:
            print(
                "{}: count={}, refinement_token={}".format(
                    value.label, value.count, value.refinement_token
                )
            )

Cuando recupera facetas mediante el descubrimiento, de forma predeterminada solo se devuelven los 10 valores más frecuentes de una faceta. Puede aumentar este límite hasta 100 con el parámetro FacetOptions discovery_limit.

Ten en cuenta que la detección automática de facetas no está diseñada para devolver todas las facetas posibles y sus valores. Las facetas devueltas por el descubrimiento pueden variar de una ejecución a otra. Si quieres usar un conjunto fijo de facetas, usa el parámetro return_facets en tu consulta.

Los valores de cadena se devolverán individualmente. Los valores numéricos de una faceta descubierta se devuelven en un único intervalo [mín. máx.). Puedes examinar este intervalo y crear un subintervalo más pequeño para una consulta posterior.

Seleccionar facetas por nombre

def facet_by_name(index):
    # Create the query and specify to only return the "type" and "ram_size_gb"
    # facets.
    query = search.Query("name:x86", return_facets=["type", "ram_size_gb"])
    results = index.search(query)

    for facet in results.facets:
        print("facet {}".format(facet.name))
        for value in facet.values:
            print(
                "{}: count={}, refinement_token={}".format(
                    value.label, value.count, value.refinement_token
                )
            )

Cuando recuperas facetas por nombre, de forma predeterminada solo se devuelven los 10 valores más frecuentes de una faceta. Puedes aumentar este límite hasta 20 con el parámetro FacetOptions discovery_value_limit.

Seleccionar facetas por nombre y valor

def facet_by_name_and_value(index):
    # Create the query and specify to return the "type" facet with values
    # "computer" and "printer" and the "ram_size_gb" facet with value in the
    # ranges [0,4), [4, 8), and [8, max].
    query = search.Query(
        "name:x86",
        return_facets=[
            search.FacetRequest("type", values=["computer", "printer"]),
            search.FacetRequest(
                "ram_size_gb",
                ranges=[
                    search.FacetRange(end=4),
                    search.FacetRange(start=4, end=8),
                    search.FacetRange(start=8),
                ],
            ),
        ],
    )

    results = index.search(query)
    for facet in results.facets:
        print("facet {}".format(facet.name))
        for value in facet.values:
            print(
                "{}: count={}, refinement_token={}".format(
                    value.label, value.count, value.refinement_token
                )
            )

Todos los valores de un mismo FacetRequest deben ser del mismo tipo: una lista de valores de cadena o, en el caso de los números, una lista de FacetRanges, que son intervalos cerrados por la izquierda (inicio) y abiertos por la derecha (final). Si tu facet tiene una combinación de valores de cadena y numéricos, añade FacetRequests independientes para cada uno.

Opciones

options = FacetOptions(discover_facet_limit=5,
                       discover_facet_value_limit=10,
                       depth=6000);

La opción depth se aplica a los tres tipos de agregación de facetas: por nombre, por nombre y valor, y por detección automática. Las demás opciones solo se utilizan para la detección automática.

Ten en cuenta que la profundidad de las facetas suele ser mucho mayor que el límite de consultas. Los resultados de las facetas se calculan con una profundidad de al menos el número de documentos. Si has definido un límite de puntuación de las opciones de ordenación superior a la profundidad, se usará el límite de puntuación.

Recuperar resultados de facetas

Cuando usas parámetros de búsqueda por facetas en una consulta, la información de las facetas agregadas se incluye en el resultado de la consulta.

Una consulta tendrá una lista de FacetResult. En la lista habrá un resultado por cada faceta que aparezca en un documento que coincida con tu consulta. En cada resultado, se mostrará lo siguiente:

• El nombre del facet
• Lista de los valores más frecuentes de la faceta. Por cada valor, se indica un recuento aproximado de las veces que ha aparecido y una clave de refinamiento que se puede usar para recuperar los documentos que coinciden con esta consulta y este valor de facet.

Ten en cuenta que la lista de valores incluirá los valores de cadena y numéricos de una faceta. Si la faceta se ha detectado automáticamente, sus valores numéricos se devuelven como un solo intervalo [mín. máx.). Si has solicitado explícitamente una faceta numérica con uno o varios intervalos en tu consulta, la lista contendrá un intervalo cerrado-abierto [inicio fin) por cada intervalo.

Es posible que la lista de valores de faceta no incluya todos los valores encontrados en los documentos, ya que las opciones de consulta determinan cuántos documentos se deben examinar y cuántos valores se deben devolver.

La información agregada de cada faceta se puede consultar en los resultados de búsqueda:

query = search.Query(...)
results = index.search(query)
for facet_info in results.facets:
  ...

Por ejemplo, una consulta puede haber encontrado documentos que incluyeran una faceta "tamaño" con valores de cadena y valores numéricos. El FacetResult de esta faceta se creará de la siguiente manera:

FacetResult(name='size', values=[
  FacetResultValue(label='[8, 10)', 22, refinement=refinement_key),
  FacetResultValue(label='small', 100, refinement=refinement_key),
  FacetResultValue(label='medium', 300, refinement=refinement_key),
  FacetResultValue(label='large', 250, refinement=refinement_key)])

El parámetro label se crea a partir de un valor de faceta. En el caso de los valores numéricos, label representa un intervalo.

El refinement_key es una cadena segura para URLs y páginas web que se puede usar en una consulta posterior para recuperar los documentos que coincidan con el nombre y el valor de la faceta de ese resultado.

Usar facetas para acotar o filtrar una consulta

query = search.Query(..., facet_refinements=[refinement_key1, refinement_key2, refinement_key3])

Puedes combinar refinamientos de una o varias facetas diferentes en la misma solicitud. Todas las acotaciones que pertenecen a la misma faceta se combinan con un operador OR. Las acotaciones de diferentes facetas se combinan con un operador AND.

También es posible crear una clave FacetRefinement personalizada manualmente. Consulta la documentación de la clase para obtener más información.