索引類別

Index 類別是一種索引，可用來將文件編入索引，也可用於刪除和搜尋文件。

Index 應在 google.appengine.api.search 模組中定義。

簡介

Index 類別提供用來建構索引的引數，以及可在索引內新增、列出、搜尋和刪除文件 (或是文件的可疊代集合) 的函式。您可以使用 Index 類別的引數建立索引，包括索引的名稱和命名空間。

下列程式碼示範了如何將文件編入索引，然後在索引中搜尋符合查詢的文件：

# Get the index.
index = search.Index(name='index-name')

# Create a document.
doc = search.Document(
    doc_id='document-id',
    fields=[search.TextField(name='subject', value='my first email'),
            search.HtmlField(name='body', value='<html>some content here</html>')])

# Index the document.
try:
    index.put(doc)
except search.PutError, e:
    result = e.results[0]
    if result.code == search.OperationResult.TRANSIENT_ERROR:
        # possibly retry indexing result.object_id
except search.Error, e:
    # possibly log the failure

# Query the index.
try:
    results = index.search('subject:first body:here')

    # Iterate through the search results.
    for scored_document in results:
        # process the scored_document

except search.Error, e:
    # possibly log the failure

建構函式

Index 類別的建構函式定義如下：

Index(name, namespace=None)

建構 Index 類別的例項。

引數

name

索引名稱 (詳情請參閱下方的名稱屬性)。

namespace

對於多租戶架構應用程式而言，命名空間內的索引名稱已定義。

結果值

Index 類別的新例項。

屬性

Index 類別的執行個體具有下列屬性：

schema

結構定義對應支援類型清單的欄位名稱。只適用於由 search.get_indexes 方法傳回的索引。

name

索引名稱，是使用者可判讀的 ASCII 字串，用於識別索引。不得包含空白字元，且開頭不得為驚嘆號 (!)。

namespace

已定義索引名稱的命名空間。

storage_usage

此索引使用位元組的概略數量。這個數字可能無法反映出近期變更的結果。只適用於由 search.get_indexes 方法傳回的索引。

storage_limit

此索引允許的儲存空間上限，以位元組為單位。只適用於由 search.get_indexes 方法傳回的索引。

實例方法

Index 類別的例項有以下方法：

put(self, documents, deadline=None)

如果指定的文件已放入索引，且具有相同的 doc_ids，系統會使用更新後的內容重新建立索引。

引數

文件

要編入索引的文件 (或文件的可疊代集合)。

deadline

以秒為單位的 RPC 呼叫期限。

結果值

結果清單 (PutResult)，每個索引要求的文件各一個。

例外狀況

PutError

一份或多份文件無法編入索引，或是索引數與要求數不相符。

TypeError

傳送了未知屬性。

ValueError

並非文件或文件的可疊代集合的引數，或是大於 MAXIMUM_DOCUMENTS_PER_PUT_REQUEST 的文件數。

delete(self, document_ids, deadline=None)

從索引刪除文件。

如果清單的 ID 中不存在對應的文件，系統就會略過該 ID。

引數

document_ids

要刪除的文件的 ID (或是 ID 清單)。

deadline

以秒為單位的 RPC 呼叫期限。

例外

DeleteError

無法刪除一份或多份文件，或是刪除數與要求數不相符。

ValueError

並非字串或有效文件 ID 的可疊代集合之引數，或是文件 ID 數大於 MAXIMUM_DOCUMENTS_PER_PUT_REQUEST。

get(self,doc_id, deadline=None)

使用文件 ID 從索引中擷取文件。如果找不到文件，則傳回 None。

引數

doc_id

要擷取的文件的 ID。

deadline

以秒為單位的 RPC 呼叫期限。

Result value

文件物件，其 ID 與 doc_id 提供的 ID 相符。

搜尋符合查詢文件的索引。查詢可為字串或查詢物件。

例如，以下程式碼片段要求搜尋文件，搜尋條件是主旨中出現「first」，且「good」出現在文件中任何位置，最多傳回 20 份文件，並從「cursor token」開始搜尋，系統傳回另一個代表回應的游標，以降序排列主旨，並傳回作者、主旨和摘要欄位，以及欄位內容程式碼片段。

results = index.search(
          # Define the query by using a Query object.
          query=Query('subject:first good',
              options=QueryOptions(limit=20,
                  cursor=Cursor(),
                  sort_options=SortOptions(
                      expressions=[SortExpression(expression='subject',
                                                  default_value='')],
                      limit=1000),
                  returned_fields=['author', 'subject', 'summary'],
                  snippeted_fields=['content'])))

下列程式碼片段說明如何使用結果游標。

cursor = results.cursor
for result in results:
     # process result
results = index.search(Query('subject:first good',
                       options=QueryOptions(cursor=cursor))
                      )

下列程式碼片段說明如何使用 per_result 游標：

results = index.search(query=Query('subject:first good',
                       options=QueryOptions(limit=20,
                       cursor=Cursor(per_result=True),
                       ...))
                       )

cursor = None
for result in results:
    cursor = result.cursor

results = index.search(
          Query('subject:first good', options=QueryOptions(cursor=cursor))
               )

引數

查詢

根據索引中的文件進行比對查詢，如查詢物件中所述。詳情請參閱「查詢語言總覽」。

deadline

以秒為單位的 RPC 呼叫期限。

Result value

SearchResults 物件，含有相符的文件、傳回的數字、符合查詢的數字組成的清單。

例外

TypeError

參數含有無效的類型，或傳送了未知的屬性。

ValueError

參數含有無效的值。

get_range(self, start_id=None, include_start_object=True, limit=100, ids_only=False, deadline=None)

以 doc_id 順序從索引中取得文件範圍。

引數

start_id

含有文件 ID 的字串，會以此列出文件。依據預設，系統會從第一個文件 ID 開始。

include_start_object

如果是 true，請加入 start_id 指定的文件。

limit

傳回文件的數量上限。

ids_only

如果為 true，則只會傳回文件 ID，而非完整文件。

deadline

以秒為單位的 RPC 呼叫期限。

結果值

A GetResponse 物件，其中包含已擷取文件的清單，依文件 ID 排序。

例外狀況

TypeError

傳送了未知屬性。

錯誤

處理要求時出現一些 Error 子類別。