Python 2.7 ha raggiunto la fine del supporto
e verrà ritirato
il 31 gennaio 2026. Dopo il ritiro, non potrai eseguire il deployment di applicazioni Python 2.7, anche se la tua organizzazione ha utilizzato in precedenza un criterio dell'organizzazione per riattivare i deployment di runtime legacy. Le tue applicazioni Python 2.7 esistenti continueranno a essere eseguite e a ricevere traffico dopo la
data di ritiro. Ti consigliamo di eseguire la migrazione all'ultima versione supportata di Python.
Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
La classe Index rappresenta un indice che consente di indicizzare, eliminare e cercare i documenti.
Index è definito nel modulo google.appengine.api.search.
Introduzione
La classe Index fornisce argomenti per la costruzione di un indice, nonché funzioni che consentono di aggiungere, elencare, cercare ed eliminare documenti (o una raccolta di documenti iterabile) all'interno dell'indice. Puoi creare un indice utilizzando gli argomenti della classe Index, inclusi il nome e lo spazio dei nomi dell'indice.
Il seguente codice mostra come inserire i documenti in un indice e poi cerca i documenti corrispondenti a una 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
Costruttore
Il costruttore della classe Index è definito come segue:
Index(name, namespace=None)
Costruisci un'istanza della classe Index.
Argomenti
name
Nome dell'indice (per maggiori dettagli, consulta la proprietà name di seguito).
Un'istanza della classe Index ha le seguenti proprietà:
schema
Nomi dei campi di mappatura dello schema all'elenco dei tipi supportati. Valido solo per gli indici restituiti dal metodo search.get_indexes.
name
Nome dell'indice, una stringa ASCII leggibile che identifica l'indice. Non deve contenere spazi vuoti e non deve iniziare con un punto esclamativo (!).
namespace
Spazio dei nomi in cui è definito il nome dell'indice.
storage_usage
Il numero approssimativo di byte utilizzati da questo indice. Il numero potrebbe non riflettere i risultati delle modifiche recenti. Valido solo per gli indici restituiti dal metodo search.get_indexes.
storage_limit
Lo spazio di archiviazione massimo consentito per questo indice, in byte. Valido solo per gli indici restituiti dal metodo search.get_indexes.
Metodi istanza
Le istanze della classe Index hanno i seguenti metodi:
put(self, documents, deadline=None)
Se i documenti specificati sono già stati inseriti nell'indice e hanno lo stesso doc_ids, vengono sottoposti nuovamente a indicizzazione con contenuti aggiornati.
Argomenti
documenti
Documento (o raccolta di documenti iterabile) da indicizzare.
deadline
Scadenza per la chiamata RPC in secondi.
Valore del risultato
Elenco di risultati (PutResult), uno per ogni documento di cui è stata richiesta l'indicizzazione.
Eccezioni
PutError
Non è stato possibile indicizzare uno o più documenti oppure il numero di documenti indicizzati non corrisponde a quello richiesto.
TypeError
È stato passato un attributo sconosciuto.
ValueError
L'argomento non è un documento o una raccolta di documenti iterabili oppure il numero di documenti è superiore a MAXIMUM_DOCUMENTS_PER_PUT_REQUEST.
delete(self, document_ids, deadline=None)
Elimina i documenti dall'indice.
Se non esiste alcun documento per un identificatore nell'elenco, questo viene ignorato.
Argomenti
document_ids
Identificatore (o elenco di identificatori) dei documenti da eliminare.
deadline
Scadenza per la chiamata RPC in secondi.
Eccezioni
DeleteError
Non è stato possibile eliminare uno o più documenti oppure il numero di documenti eliminati non corrisponde a quello richiesto.
ValueError
L'argomento non è una stringa o una raccolta iterabile di identificatori di documenti validi oppure il numero di identificatori di documenti è superiore a MAXIMUM_DOCUMENTS_PER_PUT_REQUEST.
get(self,doc_id, deadline=None)
Recupera un documento dall'indice utilizzando l'identificatore del documento. Se il documento non viene trovato, viene restituito None.
Argomenti
doc_id
L'identificatore del documento da recuperare.
deadline
Scadenza per la chiamata RPC in secondi.
Valore del risultato
Un oggetto Document il cui identificatore corrisponde a quello fornito da doc_id.
search(query, deadline=None)
Cerca nell'indice i documenti corrispondenti alla query. La query può essere una stringa o un oggetto Query.
Ad esempio, il seguente frammento di codice richiede una ricerca dei documenti in cui "primo" si verifica nell'oggetto e "buono" si verifica in qualsiasi posizione, restituisce al massimo 20 documenti, avvia la ricerca da "token cursore", restituisce un altro singolo cursore per la risposta, ordina per oggetto in ordine decrescente, restituisce i campi autore, oggetto e riepilogo, nonché i contenuti del campo con snippet.
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'])))
Il seguente frammento di codice mostra come utilizzare un cursore dei risultati.
cursor=results.cursorforresultinresults:# process resultresults=index.search(Query('subject:first good',options=QueryOptions(cursor=cursor)))
Il seguente frammento di codice mostra come utilizzare un cursore per_result:
La query da confrontare con i documenti nell'indice, descritta in un oggetto Query. Per ulteriori informazioni, consulta la Panoramica del linguaggio di query.
deadline
Scadenza per la chiamata RPC in secondi.
Valore del risultato
Un oggetto SearchResults contenente un elenco di documenti corrispondenti, il numero restituito e il numero di corrispondenze trovate dalla query.
Eccezioni
TypeError
Un parametro ha un tipo non valido o è stato passato un attributo sconosciuto.
Recupera un intervallo di documenti da un indice in ordine doc_id.
Argomenti
start_id
Stringa contenente l'identificatore del documento da cui elencare i documenti. Per impostazione predefinita, inizia dal primo identificatore del documento.
include_start_object
Se true, includi il documento specificato da start_id.
limit
Il numero massimo di documenti da restituire.
ids_only
Se true, restituisce solo gli identificatori dei documenti anziché i documenti completi.
deadline
Scadenza per la chiamata RPC in secondi.
Valore del risultato
Oggetto A GetResponse contenente un elenco dei documenti recuperati, ordinati per identificatore documento.
Eccezioni
TypeError
È stato passato un attributo sconosciuto.
Errore
Si è verificato un sottotipo di Error durante l'elaborazione della richiesta.
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Difficile da capire","hardToUnderstand","thumb-down"],["Informazioni o codice di esempio errati","incorrectInformationOrSampleCode","thumb-down"],["Mancano le informazioni o gli esempi di cui ho bisogno","missingTheInformationSamplesINeed","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 2025-09-04 UTC."],[[["\u003cp\u003eThe \u003ccode\u003eIndex\u003c/code\u003e class allows for the management of documents within an index, including indexing, deleting, and searching.\u003c/p\u003e\n"],["\u003cp\u003eAsynchronous methods like \u003ccode\u003eput_async\u003c/code\u003e, \u003ccode\u003edelete_async\u003c/code\u003e, \u003ccode\u003eget_async\u003c/code\u003e, \u003ccode\u003esearch_async\u003c/code\u003e, and \u003ccode\u003eget_range_async\u003c/code\u003e are available, returning a future object that can be used to retrieve the result via \u003ccode\u003eget_result()\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eIndex\u003c/code\u003e constructor takes the index's \u003ccode\u003ename\u003c/code\u003e and an optional \u003ccode\u003enamespace\u003c/code\u003e to create an instance, which can be used to perform methods like \u003ccode\u003eput\u003c/code\u003e, \u003ccode\u003edelete\u003c/code\u003e, \u003ccode\u003eget\u003c/code\u003e, \u003ccode\u003esearch\u003c/code\u003e, and \u003ccode\u003eget_range\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003esearch\u003c/code\u003e method allows querying the index using a string or a \u003ccode\u003eQuery\u003c/code\u003e object, which can be further customized with a \u003ccode\u003eQueryOptions\u003c/code\u003e to control parameters like limits, cursors, and sort options.\u003c/p\u003e\n"],["\u003cp\u003eThe properties of an \u003ccode\u003eIndex\u003c/code\u003e object include the name, namespace, schema, storage_usage, and storage_limit, while instance methods allow to manage documents, like put a document to the index, deleting an existing one, retrieving a document by it's ID, searching for documents matching a query and retrieving a range of documents by ID.\u003c/p\u003e\n"]]],[],null,["# The Index Class\n\nClass `Index` represents an index allowing documents to be indexed, deleted, and searched.\n| This API is supported for first-generation runtimes and can be used when [upgrading to corresponding second-generation runtimes](/appengine/docs/standard/\n| python3\n|\n| /services/access). If you are updating to the App Engine Python 3 runtime, refer to the [migration guide](/appengine/migration-center/standard/migrate-to-second-gen/python-differences) to learn about your migration options for legacy bundled services.\n\n`Index` is defined in the `google.appengine.api.search` module.\n| **Note:** There are asynchronous methods corresponding to each instance method: `put_async`, `delete_async`, `get_async`, `search_async`, and `get_range_async`. These are identical to the synchronous methods, except they all return a future. To get the actual result, call `get_result()` on the returned value; that call will block.\n\nIntroduction\n------------\n\nThe `Index` class provides arguments to construct an index as well as functions allowing you to add, list, search, and delete [documents](/appengine/docs/legacy/standard/python/search/documentclass) (or an iterable collection of documents) within the index. You construct an index using arguments to the `Index` class, including the name and namespace of the index.\n\nThe following code shows how to put documents into an index, then search it for documents matching a query: \n\n```python\n# Get the index.\nindex = search.Index(name='index-name')\n\n# Create a document.\ndoc = search.Document(\n doc_id='document-id',\n fields=[search.TextField(name='subject', value='my first email'),\n search.HtmlField(name='body', value='\u003chtml\u003esome content here\u003c/html\u003e')])\n\n# Index the document.\ntry:\n index.put(doc)\nexcept search.PutError, e:\n result = e.results[0]\n if result.code == search.OperationResult.TRANSIENT_ERROR:\n # possibly retry indexing result.object_id\nexcept search.Error, e:\n # possibly log the failure\n\n# Query the index.\ntry:\n results = index.search('subject:first body:here')\n\n # Iterate through the search results.\n for scored_document in results:\n # process the scored_document\n\nexcept search.Error, e:\n # possibly log the failure\n```\n\nConstructor\n-----------\n\nThe constructor for class `Index` is defined as follows:\n\n\nIndex(name, namespace=None)\n\n: Construct an instance of class `Index`.\n\n: Arguments\n\n name\n\n : Index name (see [name property](#Index_name), below, for details).\n\n namespace\n\n : For [multitenant applications](/appengine/docs/legacy/standard/python/multitenancy), the namespace in which index name is defined.\n\n Result value\n\n : A new instance of class `Index`.\n\n \u003cbr /\u003e\n\nProperties\n----------\n\nAn instance of class `Index` has the following properties:\n\nschema\n\n: Schema mapping field names to the list of types supported. Valid only\n for indexes returned by the [search.get_indexes](/appengine/docs/legacy/standard/python/search/functions#get_indexes)\n method.\n\nname\n\n: Index name, a human-readable ASCII string identifying the index. Must contain no whitespace characters and not start with an exclamation point (`!`).\n\nnamespace\n\n: Namespace in which index name is defined.\n\nstorage_usage\n\n: The approximate number of bytes used by this index. The number may not reflect the\n results of recent changes. Valid only\n for indexes returned by the [search.get_indexes](/appengine/docs/legacy/standard/python/search/functions#get_indexes)\n method.\n\nstorage_limit\n\n: The maximum allowable storage for this index, in bytes. Valid only\n for indexes returned by the [search.get_indexes](/appengine/docs/legacy/standard/python/search/functions#get_indexes)\n method.\n\nInstance Methods\n----------------\n\nInstances of class `Index` have the following methods:\n\nput(self, documents, deadline=None)\n\n: If the specified documents have already been put into the index, and if they have the same `doc_ids`, they are reindexed with updated contents.\n\n: Arguments\n\n documents\n\n : Document (or iterable collection of documents) to index.\n\n deadline\n\n : Deadline for RPC call in seconds.\n\n Result value\n\n : List of results (`PutResult`), one for each document requested to be indexed.\n\n Exceptions\n\n PutError\n\n : One or more documents failed to index, or number indexed did not match number requested.\n\n TypeError\n\n : Unknown attribute passed.\n\n ValueError\n\n : Argument not a document or iterable collection of documents, or number of documents larger than `MAXIMUM_DOCUMENTS_PER_PUT_REQUEST`.\n\n\ndelete(self, document_ids, deadline=None)\n\n: Delete documents from index.\n\n If no document exists for an identifier in the list, that identifier is ignored.\n\n: Arguments\n\n document_ids\n\n : Identifier (or list of identifiers) of documents to delete.\n\n deadline\n\n : Deadline for RPC call in seconds.\n\n Exceptions\n\n DeleteError\n\n : One or more documents failed to delete, or number deleted did not match number requested.\n\n ValueError\n\n : Argument not a string or iterable collection of valid document identifiers, or number of document identifiers larger than `MAXIMUM_DOCUMENTS_PER_PUT_REQUEST`.\n\n\nget(self,doc_id, deadline=None)\n\n: Retrieves a [Document](/appengine/docs/legacy/standard/python/search/documentclass) from the index using the document's identifier. If the document is not found, returns `None`.\n\n: Arguments\n\n doc_id\n\n : The identifier of the document to retrieve.\n\n deadline\n\n : Deadline for RPC call in seconds.\n\n Result value\n\n : A [Document](/appengine/docs/legacy/standard/python/search/documentclass) object whose identifier matches the one supplied by doc_id.\n\n\nsearch(query, deadline=None)\n\n: Search the index for documents matching the query. The query may be either a string or a [Query](/appengine/docs/legacy/standard/python/search/queryclass) object.\n\n 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. \n\n ```python\n results = index.search(\n # Define the query by using a Query object.\n query=Query('subject:first good',\n options=QueryOptions(limit=20,\n cursor=Cursor(),\n sort_options=SortOptions(\n expressions=[SortExpression(expression='subject',\n default_value='')],\n limit=1000),\n returned_fields=['author', 'subject', 'summary'],\n snippeted_fields=['content'])))\n ```\n\n The following code fragment shows how to use a results cursor. \n\n ```python\n cursor = results.cursor\n for result in results:\n # process result\n results = index.search(Query('subject:first good',\n options=QueryOptions(cursor=cursor))\n )\n ```\n\n The following code fragment shows how to use a `per_result` cursor: \n\n ```python\n results = index.search(query=Query('subject:first good',\n options=QueryOptions(limit=20,\n cursor=Cursor(per_result=True),\n ...))\n )\n\n cursor = None\n for result in results:\n cursor = result.cursor\n\n results = index.search(\n Query('subject:first good', options=QueryOptions(cursor=cursor))\n )\n ```\n\n: Arguments\n\n query\n\n : The query to match against documents in the index, described in a [Query](/appengine/docs/legacy/standard/python/search/queryclass) object. For more information, please see the [Query Language Overview](/appengine/docs/legacy/standard/python/search#Query_Language_Overview).\n\n deadline\n\n : Deadline for RPC call in seconds.\n\n Result value\n\n : A [SearchResults](/appengine/docs/legacy/standard/python/search/searchresultsclass) object containing a list of documents matched, number returned and number matched by the query.\n\n Exceptions\n\n TypeError\n\n : A parameter has an invalid type, or an unknown attribute was passed.\n\n ValueError\n\n : A parameter has an invalid value.\n\n\nget_range(self, start_id=None, include_start_object=True, limit=100, ids_only=False, deadline=None)\n\n: Get a range of documents from an index, in `doc_id` order.\n\n: Arguments\n\n start_id\n\n : String containing the document identifier from which to list documents. By default, starts at the first document identifier.\n\n include_start_object\n\n : If `true`, include document specified by `start_id`.\n\n limit\n\n : Maximum number of documents to return.\n\n ids_only\n\n : If `true`, return only document identifiers instead of full documents.\n\n deadline\n\n : Deadline for RPC call in seconds.\n\n Result value\n\n : `A `[GetResponse](/appengine/docs/legacy/standard/python/search/getresponseclass) object containing a list of the retrieved documents, ordered by document identifier.\n\n Exceptions\n\n TypeError\n\n : Unknown attribute passed.\n\n Error\n\n : Some subclass of `Error` occurred while processing request."]]
