Mit Attributen suchen

Durch die Suche mit Attributen können Sie Ihren Dokumenten Kategoriedaten anhängen. Beim Suchvorgang wird ein Attribut/Wert-Paar verwendet. Das Attribut "Größe" kann beispielsweise die Werte "klein", "mittel" und "groß" haben.

Durch die Verwendung von Attributen bei der Suche können Sie zusammenfassende Informationen abrufen, die Ihnen bei der Verfeinerung einer Abfrage helfen und eine Aufschlüsselung der Ergebnisse in mehreren Schritten ermöglichen.

Dies ist bei Anwendungen wie Shoppingwebsites nützlich, auf denen Sie eine Reihe von Filtern anbieten möchten, damit Kunden die angezeigten Produkte eingrenzen können.

Die aggregierten Daten für ein Attribut geben Auskunft über die Verteilung seiner Werte. Das Attribut „Größe” kann beispielsweise in zahlreichen Dokumenten Ihrer Ergebnisse auftauchen. Die aggregierten Daten für dieses Attribut können etwa Auskunft darüber geben, dass der Wert „klein” 100-mal, der Wert „mittel” 300-mal und der Wert „groß” 250-mal vorkommt. Jedes Attribut/Wert-Paar stellt eine Teilmenge von Dokumenten im Abfrageergebnis dar. Jedem Paar ist ein Schlüssel zugeordnet, der als Suchfilter bezeichnet wird. Sie können Suchfilter in eine Abfrage aufnehmen, um Dokumente abzurufen, die mit dem Abfragestring übereinstimmen und deren Attributwerte einem oder mehreren Suchfiltern entsprechen.

Bei einer Suche können Sie wählen, welche Attribute erfasst und in den Ergebnissen angezeigt werden sollen. Sie haben auch die Möglichkeit, die Attributerkennung zu aktivieren, sodass automatisch die am häufigsten in Ihren Dokumenten vorkommenden Attribute ausgewählt werden.

Einem Dokument Attribute hinzufügen

Weisen Sie einem Dokument Attribute zu, bevor Sie es einem Index hinzufügen. Sie sollten dies dann tun, wenn Sie die Felder des Dokuments angeben:

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)

Ein Attribut ähnelt einem Dokumentfeld, es hat einen Namen und einen Wert.

Attribute werden nach denselben Regeln wie Dokumentfelder benannt: Es wird zwischen Groß- und Kleinschreibung unterschieden und sie dürfen nur ASCII-Zeichen enthalten. Sie müssen mit einem Buchstaben beginnen und können Buchstaben, Ziffern oder Unterstriche enthalten. Ein Name darf maximal 500 Zeichen lang sein.

Der Wert eines Attributs kann entweder ein atomarer String (maximal 500 Zeichen lang) oder eine Zahl (Gleitkommawert mit doppelter Genauigkeit zwischen -2.147.483.647 und 2.147.483.647) sein.

Sie können einem Attribut in einem Dokument mehrere Werte zuweisen. Fügen Sie zu diesem Zweck das Attribut mit demselben Namen und Typ mehrmals hinzu und verwenden Sie dabei jedes Mal einen anderen Wert.

Ein Attribut kann eine unbegrenzte Anzahl von Werten haben. Auch die Anzahl der Attribute, die Sie einem Dokument hinzufügen können, oder die Anzahl der Attribute mit eindeutigen Namen in einem Index ist unbegrenzt.

Beachten Sie, dass ein Attribut bei jeder Verwendung entweder einen atomaren oder einen numerischen Wert annehmen kann. Ein Attribut namens „Größe” kann an ein Dokument mit dem Stringwert „klein” und an ein anderes Dokument mit dem numerischen Wert „8” angehängt werden. Dasselbe Attribut kann sogar mit beiden Werttypen mehrmals in demselben Dokument auftauchen. Es wird jedoch davon abgeraten, für ein Attribut sowohl atomare als auch numerische Werte zu verwenden.

Obgleich ein Attribut, das Sie einem Dokument hinzufügen, einen bestimmten Typ hat, werden in den Suchergebnissen alle Werte des Attributs zusammengefasst. Zum Beispiel könnten die Ergebnisse für das Attribut „Größe” zeigen, dass es 100 Instanzen des Werts „klein”, 150 Instanzen des Werts „mittel” und 135 Instanzen von numerischen Werten im Bereich [4, 8) gab. Die genauen numerischen Werte und die Häufigkeit ihrer Verteilung werden nicht angezeigt.

Wenn Sie ein Dokument mithilfe einer Abfrage abrufen, können Sie nicht direkt auf seine Attribute und Werte zugreifen. Sie müssen angeben, dass mit Ihrer Abfrage Attributinformationen zurückgegeben werden. Dies wird im nächsten Abschnitt erläutert.

Attributinformationen mit einer Attributsuche abrufen

Sie können angeben, dass das Backend für die Suche die am häufigsten verwendeten Attribute für Sie ermitteln soll. Dies wird als „automatische Attributerkennung” bezeichnet. Sie können Attributinformationen auch explizit abrufen, indem Sie ein Attribut nach Name oder nach Name und Wert auswählen. Sie können alle drei Arten des Attributabrufs in einer einzigen Abfrage mischen und abgleichen.

Die Abfrage von Attributinformationen hat keinen Einfluss darauf, welche Dokumente durch die Abfrage zurückgegeben werden. Sie kann jedoch die Leistung beeinträchtigen. Sie erzielen durch eine Suche mit Attributen mit der Standardtiefe 1.000 denselben Effekt, wie wenn Sie als Scorer-Limit für Sortieroptionen 1.000 festlegen.

Automatische Attributerkennung

Bei der automatischen Attributerkennung werden die Attribute gesucht, die in der Zusammenfassung Ihrer Dokumente am häufigsten angezeigt werden. Angenommen, die zu Ihrer Abfrage passenden Dokumente enthalten das Attribut „Farbe”, das fünfmal mit dem Wert „rot”, fünfmal mit dem Wert „weiß” und fünfmal mit dem Wert „blau” vorkommt. Dieses Attribut kommt insgesamt 15-mal vor. Für die Erkennung würde es höher eingestuft werden als das Attribut „Farbton”, das in denselben übereinstimmenden Dokumenten sechsmal mit dem Wert „dunkel” und siebenmal mit dem Wert „hell” auftaucht.

Sie müssen die Attributerkennung aktivieren, indem Sie sie in Ihrer Abfrage festlegen:

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
                )
            )

Wenn Sie Attribute durch Erkennung abrufen, werden standardmäßig nur die zehn am häufigsten vorkommenden Werte eines Attributs zurückgegeben. Mit dem Parameter FacetOptions discovery_limit können dieses Limit auf bis zu 100 erhöhen.

Die automatische Attributerkennung dient nicht dazu, alle möglichen Attribute und deren Werte zurückzugeben. Welche Attribute durch Erkennung zurückgegeben werden, kann von Ausführung zu Ausführung variieren. Wenn Sie nach bestimmten Attributen suchen möchten, verwenden Sie in der Abfrage den Parameter return_facets.

Stringwerte werden einzeln zurückgegeben. Die numerischen Werte eines erkannten Attributs werden innerhalb eines einzelnen Bereichs [min max) zurückgegeben. Sie können diesen Bereich überprüfen und für eine spätere Abfrage einen kleineren Teilbereich erstellen.

Facetten nach Name auswählen

Um Informationen zu einem Attribut nur nach dessen Name abzurufen, fügen Sie der Abfrage den Parameter return_facets einschließlich des Attributnamens hinzu:

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
                )
            )

Wenn Sie Attribute nach ihrem Namen abrufen, werden standardmäßig nur deren zehn am häufigsten auftretende Werte zurückgegeben. Mit dem Parameter FacetOptions discovery_value_limit können dieses Limit auf bis zu 20 erhöhen.

Attribute nach Name und Wert auswählen

Wenn Sie nur Informationen zu bestimmten Werten eines Attributs abrufen möchten, fügen Sie den Parameter return_facets einschließlich des Objekts FacetRequest mit einer Werteliste hinzu:

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
                )
            )

Die Werte in einer einzelnen FacetRequest müssen alle vom gleichen Typ sein, entweder eine Liste mit Stringwerten oder, bei Zahlen, eine Liste von FacetRanges, also Intervalle, die links geschlossen (Start) und rechts offen (Ende) sind. Wenn das Attribut sowohl String- als auch Zahlenwerte enthält, fügen Sie jeweils separate FacetRequest-Objekte hinzu.

Optionen

Sie können die facettierte Suche steuern, indem Sie den Parameter facet_options zu einem Abfrageaufruf hinzufügen. Für diesen Parameter wird eine einzelne Instanz von FacetOptions verwendet. Mit diesem Parameter können Sie das Standardverhalten der Suche mit Attributen überschreiben.

options = FacetOptions(discover_facet_limit=5,
                       discover_facet_value_limit=10,
                       depth=6000);
Parameter Beschreibung Standard
discover_facet_limit Anzahl der erkannten Attribute bei aktivierter Attributerkennung. Mit 0 deaktivieren Sie die Attributerkennung. 10
discover_facet_value_limit Anzahl der Werte, die für jedes der am häufigsten erkannten Attribute zurückgegeben werden. 10
depth Mindestanzahl von Dokumenten in Abfrageergebnissen, die zum Erfassen von Attributinformationen ausgewertet werden. 1000

Die Option depth gilt für alle drei Arten der Attributaggregation: nach Name, Name und Wert und automatischer Erkennung. Die anderen Optionen dienen nur der automatischen Erkennung.

Beachten Sie, dass die Attributtiefe normalerweise viel größer als das Abfragelimit ist. Die Attributergebnisse werden mindestens bis zur Tiefe der Dokumente berechnet. Wenn Sie für die Sortieroptionen ein höheres Scoring-Limit als die Tiefe festgelegt haben, wird stattdessen das Scoring-Limit verwendet.

Attributergebnisse abrufen

Wenn Sie in einer Abfrage Attributsuchparameter verwenden, enthalten die aggregierten Attributinformationen auch das Abfrageergebnis selbst.

Eine Abfrage enthält eine Liste mit FacetResult. In der Liste wird für jedes Attribut, das in einem mit Ihrer Abfrage übereinstimmenden Dokument enthalten ist, ein Ergebnis angezeigt. Sie erhalten für jedes Ergebnis Folgendes:

  • Den Attributnamen
  • Eine Liste der häufigsten Werte für das Attribut. Zu jedem Wert wird die ungefähre Häufigkeit angezeigt, mit der er aufgetreten ist, sowie ein Suchfilterschlüssel, mit dem Sie die mit der Abfrage und dem Attributwert übereinstimmenden Dokumente abrufen können.

Beachten Sie, dass die Werteliste den String und die numerischen Werte eines Attributs enthält. Bei automatischer Erkennung des Attributs werden dessen numerische Werte als ein Intervall [min max) zurückgegeben. Wenn Sie explizit ein numerisches Attribut mit einem oder mehreren Bereichen abgefragt haben, enthält die Liste für jeden Bereich ein am Anfang geschlossenes und am Ende offenes Intervall [Anfang Ende).

Die Liste der Attributwerte enthält möglicherweise nicht alle in Ihren Dokumenten gefundenen Werte. Es hängt von den Abfrageoptionen ab, wie viele Dokumente untersucht und wie viele Werte zurückgegeben werden.

Die zusammengefassten Informationen zu jedem Attribut finden Sie in den Suchergebnissen:

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

Bei einer Abfrage können beispielsweise Dokumente zurückgegeben werden, die das Attribut "Größe" mit Stringwerten und numerischen Werten enthalten. Das FacetResult für diese Facette wird folgendermaßen aufgebaut:

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)])

Der Parameter label wird aus einem Attributwert erstellt. Bei numerischen Werten ist label die Darstellung eines Bereichs.

refinement_key ist ein sicherer Web-/URL-String, mit dem sich bei einer späteren Abfrage die Dokumente abrufen lassen, die dem Attributnamen und -wert des Ergebnisses entsprechen.

Mit Attributen Abfragen verfeinern/filtern

Mit einer Verfeinerung zu einem FacetResultValue lassen sich Ihre Ergebnisse weiter einschränken, sodass nur Dokumente mit diesen Attributwerten enthalten sind. Um Abfragen mit einem oder mehreren dieser Schlüssel zu verfeinern, übergeben Sie sie an das Abfrageobjekt:

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

Sie können innerhalb derselben Abfrage Suchfilter für ein oder mehrere Attribute kombinieren. Alle Suchfilter eines Attributs werden mit OR verknüpft. Suchfilter für unterschiedliche Attribute werden mit AND verknüpft.

Ein benutzerdefinierter FacetRefinement-Schlüssel kann auch manuell erstellt werden. Weitere Informationen finden Sie in der Dokumentation zu Klassen.