検索結果の処理

クエリ呼び出しが正常に終了すると、その結果が SearchResults オブジェクトとして返されます。Results オブジェクトによって、インデックス内に見つかった一致ドキュメントの数と返された一致ドキュメントの数がわかります。また、一致する ScoredDocuments のリストも含まれます。検索で呼び出しのたびに返されるドキュメントの数に制限があるため、通常、リストには見つかったドキュメントの一部しか含まれません。オフセットやカーソルを使用して、検索条件に一致するドキュメントのサブセットの取得を繰り返すことによって、最終的に該当するドキュメントをすべて取得できます。

結果

appengine/standard/search/snippets/snippets.py 
def query_results(index, query_string):
    result = index.search(query_string)
    total_matches = result.number_found
    list_of_docs = result.results
    number_of_docs_returned = len(list_of_docs)
    return total_matches, list_of_docs, number_of_docs_returned

limit クエリ オプションの値によっては、結果で返される一致ドキュメントの数が、見つかった数より少ない場合があります。見つかった数の精度が、見つかった数より低い場合に、見つかった数は推定数になるので注意してください。検索オプションの構成にかかわらず、1 度の search() 呼び出しで検出できる一致ドキュメントの数は最大 10,000 個です。

返されたドキュメントより多くのドキュメントが見つかり、それらすべてを取得する必要がある場合は、後述のように、オフセットやカーソルを使用して検索を繰り返す必要があります。

スコア付きドキュメント

検索結果には、クエリに一致する ScoredDocuments のリストが含まれます。リストを繰り返して、各ドキュメントを順番に処理できます。

appengine/standard/search/snippets/snippets.py 
for scored_document in results:
        print(scored_document)

デフォルトでスコア付きドキュメントには、インデックス化された元のドキュメントのすべてのフィールドが含まれます。クエリ オプションで returned_fields を指定した場合、このようなフィールドのみがドキュメントの fields プロパティに表示されます。returned_expressions または snippeted_fields を指定して計算フィールドを作成した場合、これらのフィールドはドキュメントの expressions プロパティに個別に表示されます。

オフセットの使用

検索で、一度に返せる数より多くのドキュメントが見つかった場合、オフセットを使用して、一致するドキュメントのリストへのインデックスを作成します。たとえば、デフォルトのクエリ制限が 20 ドキュメントであるとします。検索を初めて実行し（オフセット 0 で）、最初の 20 ドキュメントを取得した後に、オフセットを 20 に設定し、同じ検索を再実行して、次の 20 ドキュメントを取得します。オフセットを返されるドキュメント数分増やしながら検索を繰り返します。

appengine/standard/search/snippets/snippets.py 
def query_offset(index, query_string):
    offset = 0

    while True:
        # Build the query using the current offset.
        options = search.QueryOptions(offset=offset)
        query = search.Query(query_string=query_string, options=options)

        # Get the results
        results = index.search(query)

        number_retrieved = len(results.results)
        if number_retrieved == 0:
            break

        # Add the number of documents found to the offset, so that the next
        # iteration will grab the next page of documents.
        offset += number_retrieved

        # Process the matched documents
        for document in results:
            print(document)

オフセットはきわめて大きな結果セットに対して繰り返す場合、非効率的になることがあります。

カーソルの使用

カーソルを使用して、結果の部分範囲を取得することもできます。カーソルは、連続したページに検索結果を表示しようとし、クエリ間でインデックスが変更された可能性がある場合でもすべてのドキュメントをスキップしないようにする場合に便利です。また、カーソルはきわめて大きな結果セットを繰り返す場合にも効率的です。

カーソルを使用するには、初期カーソルを作成し、それをクエリ オプションに含める必要があります。クエリごとと結果ごとの 2 種類のカーソルがあります。クエリごとのカーソルを使用すると、検索呼び出しによって返される結果オブジェクトごとに個別のカーソルが関連付けられます。結果ごとのカーソルでは、結果内のすべてのスコア付きドキュメントにカーソルが関連付けられます。

クエリごとのカーソルの使用

デフォルトで、新しく構築されるカーソルはクエリごとのカーソルです。このカーソルは、検索の結果で返された最後のドキュメントの位置を保持します。これは検索ごとに更新されます。インデックス内の一致するすべてのドキュメントを列挙するには、結果で null カーソルが返されるまで同じ検索を実行します。

appengine/standard/search/snippets/snippets.py 
def query_cursor(index, query_string):
    cursor = search.Cursor()

    while cursor:
        # Build the query using the cursor.
        options = search.QueryOptions(cursor=cursor)
        query = search.Query(query_string=query_string, options=options)

        # Get the results and the next cursor
        results = index.search(query)
        cursor = results.cursor

        for document in results:
            print(document)

結果ごとのカーソルの使用

結果ごとのカーソルを作成するには、初期カーソルの作成時に、カーソルの per_result プロパティを true に設定する必要があります。検索が返されると、すべてのドキュメントにカーソルが関連付けられます。そのカーソルを使用して、新たな検索を実行する際に特定のドキュメントから始まる結果を返すよう指定できます。結果ごとのカーソルを検索に渡した場合、結果自体にはクエリごとのカーソルが関連付けられないことに注意してください。このとき result.getCursor() は null を返すため、これを使用して一致するすべてのドキュメントを取得したかどうかを検知することはできません。

appengine/standard/search/snippets/snippets.py 
def query_per_document_cursor(index, query_string):
    cursor = search.Cursor(per_result=True)

    # Build the query using the cursor.
    options = search.QueryOptions(cursor=cursor)
    query = search.Query(query_string=query_string, options=options)

    # Get the results.
    results = index.search(query)

    document_cursor = None
    for document in results:
        # discover some document of interest and grab its cursor, for this
        # sample we'll just use the first document.
        document_cursor = document.cursor
        break

    # Start the next search from the document of interest.
    if document_cursor is None:
        return

    options = search.QueryOptions(cursor=document_cursor)
    query = search.Query(query_string=query_string, options=options)
    results = index.search(query)

    for document in results:
        print(document)

カーソルの保存と復元

カーソルは後で使用するためにウェブセーフ文字列としてシリアル化し、保存して復元できます。

appengine/standard/search/snippets/snippets.py 
def saving_and_restoring_cursor(cursor):
    # Convert the cursor to a web-safe string.
    cursor_string = cursor.web_safe_string
    # Restore the cursor from a web-safe string.
    cursor = search.Cursor(web_safe_string=cursor_string)