Index 类

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

索引名称（有关详细信息，请参阅下面的 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，则会使用更新的内容重新对它们编制索引。

参数

documents

要编制索引的文档（或可迭代文档集合）。

deadline

远程过程调用 (RPC) 的期限（以秒为单位）。

结果值

结果列表 (PutResult)，每个要求编制索引的文档对应一个结果。

异常

PutError

一个或多个文档无法编制索引，或编制索引的文档数与请求的数量不符。

TypeError

传递了未知属性。

ValueError

参数不是文档或可迭代文档集合，或文档数大于 MAXIMUM_DOCUMENTS_PER_PUT_REQUEST。

delete(self, document_ids, deadline=None)

删除索引中的文档。

如果列表中的标识符没有对应的文档，则忽略该标识符。

参数

document_ids

要删除的文档的标识符（或标识符列表）。

deadline

远程过程调用 (RPC) 的期限（以秒为单位）。

异常

DeleteError

一个或多个文档无法删除，或删除的数量与请求的数量不符。

ValueError

参数不是有效文档标识符的字符串或可迭代集合，或文档标识符数大于 MAXIMUM_DOCUMENTS_PER_PUT_REQUEST。

get(self,doc_id, deadline=None)

使用文档的标识符从索引中检索文档。如果未找到该文档，则系统会返回 None。

参数

doc_id

要检索的文档的标识符。

deadline

远程过程调用 (RPC) 的期限（以秒为单位）。

结果值

Document 对象，其标识符与 doc_id 提供的标识符匹配。

在索引中搜索与查询匹配的文档。查询可以是字符串或 Query 对象。

例如，以下代码片段请求搜索主题中出现“first”且任意位置出现“good”的文档，最多返回 20 个文档，搜索从“游标标记”开始，返回另一个游标作为响应，按主题降序排列，返回作者、主题和摘要字段以及摘录的字段内容。

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

参数

query

Query 对象中描述的与索引中的文档进行匹配的查询。如需了解详情，请参阅查询语言概览。

deadline

远程过程调用 (RPC) 的期限（以秒为单位）。

结果值

SearchResults 对象，包含匹配的文档列表、返回的数量和查询匹配的数量。

异常

TypeError

参数类型无效或者传递了未知属性。

ValueError

参数值无效。

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

以 doc_id 顺序从索引中获取一系列文档。

参数

start_id

包含要从其开始列出文档的文档标识符的字符串。默认情况下，从第一个文档标识符开始。

include_start_object

如果为 true，请加入由 start_id 指定的文档。

limit

要返回的文档数上限。

ids_only

如果为 true，则仅返回文档标识符而不是完整文档。

deadline

远程过程调用 (RPC) 的期限（以秒为单位）。

结果值

A GetResponse 对象，包含检索到的文档列表，按文档标识符排序。

异常

TypeError

传递了未知属性。

错误

处理请求时发生的某些 Error 子类。