注: Python 2.7 は、2024 年 1 月 31 日にサポートが終了しました。既存の Python 2.7 アプリケーションは引き続き実行され、トラフィックを受信します。ただし、サポート終了日を過ぎると、ランタイムを使用するアプリケーションの再デプロイが App Engine によってブロックされることがあります。サポートされている最新バージョンの Python に移行することをおすすめします。

ファセット検索

ファセット検索により、ドキュメントにカテゴリ情報を追加できます。ファセットは属性と値のペアです。たとえば、「size」というファセットが「small」、「medium」、「large」などの値を持つとします。

検索でファセットを使用すると、一連のステップでクエリを絞り込み、結果に「ドリルダウン」するために役立つ概要情報を取得できます。

これはショッピングサイトのような用途で有用な機能であり、購入者が見たい商品を絞り込めるように一連のフィルタを提供できます。

ファセットの集計データは、ファセットの値の分布状態を示します。たとえば、ファセット「size」が結果セットで多くのドキュメントに出現しているとします。そのファセットの集計データには、「small」の値が 100 回出現し、「medium」が 300 回、「large」が 250 回出現したことが示されます。各ファセットと値のペアは、クエリ結果内のドキュメントのサブセットを表します。各ペアには refinement というキーが関連付けられています。クエリに絞り込みを含めると、クエリ文字列に一致し、1 つ以上の絞り込みに対応するファセット値のあるドキュメントを取得できます。

検索を実行する場合、収集し、結果で表示するファセットを選択し、ファセット検出を有効にして、ドキュメントで最も頻繁に出現するファセットを自動的に選択できます。

ドキュメントにファセットを追加する

インデックスにドキュメントを追加する前に、ドキュメントにファセットを追加します。これはドキュメントのフィールドを指定するときに同時に行います。

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)

ファセットはドキュメントフィールドに似ており、名前と 1 つの値を持ちます。

ファセット名はドキュメントフィールドと同じルールに従います。名前は大文字と小文字が区別され、ASCII 文字のみ含めることができます。それらは文字で始まり、文字、数字、またはアンダースコアを含めることができます。名前は 500 文字を超えることはできません。

ファセットの値は、アトミック文字列（500 文字以内）または数値（-2147483647 から 2147483647 までの倍精度浮動小数点値）のいずれかです。

1 つのドキュメントのファセットに複数の値を割り当てるには、毎回異なる値を使用して、同じ名前と型のファセットを何回も追加します。

ファセットに指定できる値の数に上限はありません。ドキュメントに追加できるファセット数やインデックス内の一意の名前が付けられたファセット数にも上限はありません。

ファセットを使用するときは毎回、アトミック値または数値のどちらでも指定できます。「size」の名前を持つファセットは、文字列値「small」で 1 つのドキュメントに追加し、数値 8 で別のドキュメントに追加できます。実際に、同じファセットが両方の種類の値で、同じドキュメントに複数回出現できます。可能であっても同じファセットにアトミック値と数値の両方を使用することはおすすめできません。

ファセットはドキュメントに追加する際に特定の型を持ちますが、検索結果は、その値をすべてまとめて収集します。たとえば、ファセット「size」に、値「small」の 100 インスタンス、「medium」の 150 インスタンス、および範囲 [4, 8) の数値の 135 インスタンスがあったことが示されます。正確な数値とそれらの頻度分布は表示されません。

クエリを使用してドキュメントを取得する場合、そのファセットや値に直接アクセスすることはできません。次のセクションで説明するように、クエリでファセット情報が返されるようにリクエストする必要があります。

ファセット検索を使用してファセット情報を取得する

検索バックエンドに、最も頻繁に使用されているファセットの検出を要求できます。これは自動ファセット検出と呼ばれます。名前または名前と値でファセットを選択して、ファセット情報を明示的に取得することもできます。1 つのクエリで 3 種類すべてのファセット取得を混在させ、照合させることができます。

ファセット情報の要求は、クエリで返されるドキュメントに影響しません。それはパフォーマンスに影響する可能性があります。デフォルトの深さ 1,000 のファセット検索を実行することは、並べ替えオプションスコア上限を 1,000 に設定するのと同じ効果があります。

自動ファセット検出

自動ファセット検出はドキュメントの集計で最も頻繁に出現するファセットを探します。たとえば、クエリに一致するドキュメントに、値「red」で 5 回、値「white」で 5 回、値「blue」で 5 回出現する「color」ファセットが含まれているとします。このファセットの合計カウントは 15 になります。検出の目的で、これは同じ一致するドキュメントに、値「dark」で 6 回および値「light」で 7 回出現する別のファセット「shade」より上の順位になります。

クエリにファセット検出を設定して有効にする必要があります。

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

検出によってファセットを取得する場合、デフォルトでは、ファセットの最も頻繁に出現する 10 個の値のみが返されます。FacetOptions discovery_limit パラメータを使用すると、この上限を 100 まで増やすことができます。

自動ファセット検出では、可能性のあるすべてのファセットとその値が返されるわけではない点に注意してください。検出で返されるファセットは、実行ごとに異なる可能性があります。固定された一連のファセットが必要な場合は、クエリで return_facets パラメータを使用します。

文字列値は個別に返されます。検出されたファセットの数値は 1 つの範囲 [min max) で返されます。この範囲を調査して、後のクエリ用に小さな部分範囲を作成できます。

名前でファセットを選択する

名前のみでファセットに関する情報を取得するには、クエリに return_facets パラメータを追加し、リストにファセット名を指定します。

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

名前でファセットを取得する場合、デフォルトでファセットの最も頻繁に出現する 10 個の値のみが返されます。FacetOptions discovery_value_limit パラメータを使用すると、この上限を 20 まで増やすことができます。

名前と値でファセットを選択する

ファセットの特定の値の情報だけを取得するには、FacetRequest オブジェクトを含む return_facets パラメータと値のリストを追加します。

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

1 つの FacetRequest 内の値はすべて、文字列値のリストまたは FacetRanges のリスト（数値の場合）のいずれか同じ型でなければなりません。数値の場合は、左側（開始）はその値を含み、右側（終了）はその値を含まない区間で指定します。ファセットに文字列値と数値が混在している場合は、それぞれに個別の FacetRequests を追加します。

オプション

ファセット検索を制御するには、facet_options パラメータをクエリ呼び出しに追加します。このパラメータは FacetOptions の 1 つのインスタンスを取得します。このパラメータを使用して、ファセット検索のデフォルトの動作をオーバーライドします。

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

パラメータ	説明	デフォルト
`discover_facet_limit`	ファセット検出が有効にされている場合に、検出するファセット数。0 の場合、ファセット検出は無効になります。	10
`discover_facet_value_limit`	検出された上位の各ファセットについて返される値の数。	10
`depth`	ファセット情報を収集するために評価するクエリ結果内のドキュメントの最小数。	1,000

depth オプションは、名前、名前と値、自動検出による 3 つすべての種類のファセット集計に適用されます。他のオプションは自動検出専用です。

ファセットの深さは通常クエリ制限よりはるかに大きいことに注意してください。ファセット結果は、ドキュメントの深さ数以上に計算されます。並べ替えオプションを深さより大きいスコア制限に設定している場合、スコア上限が代わりに使われます。

ファセット結果の取得

クエリでファセット検索パラメータを使用すると、集計されたファセット情報がクエリ結果自体に付属します。

クエリには FacetResult のリストが含まれます。クエリに一致したドキュメントに出現するファセットごとに、1 つの結果がリストにあります。各結果で、次を取得します。

ファセット名
ファセットの最も頻繁な値のリスト。値ごとに、その出現回数のおおよそのカウント、このクエリとファセット値に一致するドキュメントを取得するために使用できる絞り込みキーがあります。

値のリストには、ファセットの文字列と数値が含まれることに注意してください。ファセットが自動検出された場合、その数値が 1 つの間隔 [min max) として返されます。クエリで 1 つ以上の範囲を持つ数値ファセットを明示的に要求した場合、リストには範囲ごとに 1 つの closed-open 間隔 [start end) が含まれます。

クエリオプションによって、調査するドキュメント数や返される値の数が指定されているため、ファセット値のリストに、ドキュメントで見つかったすべての値が含まれないことがあります。

各ファセットの集計情報を検索結果から読み取ることができます。

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

たとえば、クエリによって文字列値と数値の「size」ファセットを含むドキュメントが見つかったとします。このファセットの FacetResult は次のように構築されます。

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

label パラメータはファセット値から構成されます。数値の場合、label は範囲を表します。

refinement_key は、後でクエリで使用して、その結果のファセット名と値に一致するドキュメントを取得できるウェブ / URL セーフ文字列です。

ファセットを使用してクエリを絞り込み / フィルタする

各 FacetResultValue に関連付けられた絞り込みを行うと、これらのファセット値を持つドキュメントのみを結果に含めることができます。1 つ以上のキーを使用するクエリを絞り込むには、これらをクエリオブジェクトに渡します。

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

同じリクエストで、1 つ以上の異なるファセットの絞り込みを組み合わせることができます。同じファセットに属するすべての絞り込みは OR で結合します。異なるファセットの絞り込みは AND で組み合わせます。

手動でカスタム FacetRefinement キーを作成することもできます。詳細については、クラスのドキュメントをご覧ください。