Python 2.7 has reached end of supportand will bedeprecatedon January 31, 2026. After deprecation, you won't be able to deploy Python 2.7applications, even if your organization previously used an organization policy tore-enable deployments of legacy runtimes. Your existing Python2.7 applications will continue to run and receive traffic after theirdeprecation date. We recommend thatyoumigrate to the latest supported version of Python.

The Index Class

ClassIndex represents an index allowing documents to be indexed, deleted, and searched.

This API is supported for first-generation runtimes and can be used whenupgrading to corresponding second-generation runtimes. If you are updating to the App Engine Python 3 runtime, refer to themigration guide to learn about your migration options for legacy bundled services.

Index is defined in thegoogle.appengine.api.search module.

Note:There are asynchronous methods corresponding to each instance method:put_async,delete_async,get_async,search_async, andget_range_async.These are identical to the synchronous methods, except they all return a future. To get the actual result, callget_result() on the returned value; that call will block.

Introduction

TheIndex class provides arguments to construct an index as well as functions allowing you to add, list, search, and deletedocuments (or an iterable collection of documents) within the index. You construct an index using arguments to theIndex class, including the name and namespace of the index.

The following code shows how to put documents into an index, then search it for documents matching a query:

# 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)exceptsearch.PutError,e:result=e.results[0]ifresult.code==search.OperationResult.TRANSIENT_ERROR:# possibly retry indexing result.object_idexceptsearch.Error,e:# possibly log the failure# Query the index.try:results=index.search('subject:first body:here')# Iterate through the search results.forscored_documentinresults:# process the scored_documentexceptsearch.Error,e:# possibly log the failure

Constructor

The constructor for classIndex is defined as follows:

Index(name,namespace=None)

Construct an instance of classIndex.

Arguments

name

Index name (seename property, below, for details).

namespace

Formultitenant applications, the namespace in which index name is defined.

Result value

A new instance of classIndex.

Properties

An instance of classIndex has the following properties:

schema

Schema mapping field names to the list of types supported. Valid only for indexes returned by thesearch.get_indexes method.

name

Index name, a human-readable ASCII string identifying the index. Must contain no whitespace characters and not start with an exclamation point (!).

namespace

Namespace in which index name is defined.

storage_usage

The approximate number of bytes used by this index. The number may not reflect the results of recent changes. Valid only for indexes returned by thesearch.get_indexes method.

storage_limit

The maximum allowable storage for this index, in bytes. Valid only for indexes returned by thesearch.get_indexes method.

Instance Methods

Instances of classIndex have the following methods:

put(self,documents,deadline=None)

If the specified documents have already been put into the index, and if they have the samedoc_ids, they are reindexed with updated contents.

Arguments

documents

Document (or iterable collection of documents) to index.

deadline

Deadline for RPC call in seconds.

Result value

List of results (PutResult), one for each document requested to be indexed.

Exceptions

PutError

One or more documents failed to index, or number indexed did not match number requested.

TypeError

Unknown attribute passed.

ValueError

Argument not a document or iterable collection of documents, or number of documents larger thanMAXIMUM_DOCUMENTS_PER_PUT_REQUEST.

delete(self,document_ids,deadline=None)

Delete documents from index.

If no document exists for an identifier in the list, that identifier is ignored.

Arguments

document_ids

Identifier (or list of identifiers) of documents to delete.

deadline

Deadline for RPC call in seconds.

Exceptions

DeleteError

One or more documents failed to delete, or number deleted did not match number requested.

ValueError

Argument not a string or iterable collection of valid document identifiers, or number of document identifiers larger thanMAXIMUM_DOCUMENTS_PER_PUT_REQUEST.

get(self,doc_id,deadline=None)

Retrieves aDocument from the index using the document's identifier. If the document is not found, returnsNone.

Arguments

doc_id

The identifier of the document to retrieve.

deadline

Deadline for RPC call in seconds.

Result value

ADocument object whose identifier matches the one supplied bydoc_id.

search(query,deadline=None)

Search the index for documents matching the query. The query may be either a string or aQuery object.

For example, the following code fragment requests a search for documents where 'first' occurs in subject and 'good' occurs anywhere, returning at most 20 documents, starting the search from 'cursor token', returning another single cursor for the response, sorting by subject in descending order, returning the author, subject, and summary fields as well as a snippeted field content.

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

The following code fragment shows how to use a results cursor.

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

The following code fragment shows how to use aper_result cursor:

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

Arguments

query

The query to match against documents in the index, described in aQuery object. For more information, please see theQuery Language Overview.

deadline

Deadline for RPC call in seconds.

Result value

ASearchResults object containing a list of documents matched, number returned and number matched by the query.

Exceptions

TypeError

A parameter has an invalid type, or an unknown attribute was passed.

ValueError

A parameter has an invalid value.

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

Get a range of documents from an index, indoc_id order.

Arguments

start_id

String containing the document identifier from which to list documents. By default, starts at the first document identifier.

include_start_object

Iftrue, include document specified bystart_id.

limit

Maximum number of documents to return.

ids_only

Iftrue, return only document identifiers instead of full documents.

deadline

Deadline for RPC call in seconds.

Result value

AGetResponse object containing a list of the retrieved documents, ordered by document identifier.

Exceptions

TypeError

Unknown attribute passed.

Error

Some subclass ofError occurred while processing request.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.