Nota: Python 2.7 alcanzó el fin de la asistencia el 31 de enero de 2024. Tus aplicaciones existentes de Python 2.7 seguirán ejecutándose y recibiendo tráfico. Sin embargo, App Engine podría bloquear la reimplementación de aplicaciones que usan entornos de ejecución después de la fecha de finalización de la asistencia. Te recomendamos que migres a la última versión compatible de Python.

La clase Index

La clase Index representa un índice que permite indexar, borrar y buscar documentos.

Index se define en el módulo google.appengine.api.search.

Nota: Hay métodos asíncronos que corresponden a cada método de instancia: put_async, delete_async, get_async, search_async y get_range_async. Estos son idénticos a los métodos síncronos, excepto que todos muestran un resultado futuro. Para obtener el resultado real, llama a get_result() en el valor que se muestra; esa llamada se bloqueará.

Introducción

La clase Index proporciona argumentos para construir un índice y funciones que te permiten agregar, enumerar, buscar y borrar documentos (o una colección iterable de documentos) en el índice. Para construir un índice, debes usar argumentos de la clase Index, incluidos el nombre y el espacio de nombres del índice.

El código siguiente muestra cómo colocar los documentos en un índice, para luego buscar en el índice los documentos que coinciden con una consulta:

# 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

Constructor

El constructor para la clase Index se define de la manera siguiente:

Index(name, namespace=None)

Construye una instancia de la clase Index.

Argumentos

name: Nombre del índice (para obtener más información, consulta propiedad de nombre a continuación).
namespace: En las aplicaciones multiusuario, el espacio de nombres en el que se define el nombre del índice.

Valor del resultado

Una instancia nueva de la clase Index.

Propiedades

Una instancia de la clase Index tiene las siguientes propiedades:

schema: Nombres de los campos de mapeo de esquema para la lista de tipos compatibles. Solo es válido para los índices que muestra el método search.get_indexes.
name: Nombre del índice, una string ASCII en formato legible que identifica el índice. No debe contener caracteres de espacios en blanco y no debe comenzar con un signo de exclamación (!).
namespace: Espacio de nombres en el que se define el nombre del índice.
storage_usage: El número aproximado de bytes usados por este índice. Es posible que el número no refleje los resultados de los cambios recientes. Solo es válido para los índices que muestra el método search.get_indexes.
storage_limit: El almacenamiento máximo permitido para este índice, en bytes. Solo es válido para los índices que muestra el método search.get_indexes.

Métodos de instancia

Las instancias de la clase Index tienen los siguientes métodos:

put(self, documents, deadline=None)

Si los documentos especificados ya fueron colocados en el índice, y si poseen los mismos doc_ids, se vuelven a indexar con los contenidos actualizados.

Argumentos

documents: Documento (o colección iterable de documentos) que se indexará.
deadline: Plazo para la llamada del procedimiento remoto (RPC) en segundos.

Valor del resultado

Lista de resultados (PutResult), uno para cada documento que se solicitó indexar.

Excepciones

PutError: No se pudieron indexar uno o más documentos, o el número indexado no coincidió con el número solicitado.
TypeError: Se pasó un atributo desconocido.
ValueError: El argumento no es un documento o una colección iterable de documentos, o el número de documentos es mayor que MAXIMUM_DOCUMENTS_PER_PUT_REQUEST.

delete(self, document_ids, deadline=None)

Borra documentos del índice.

Si no existe ningún documento para un identificador de la lista, el identificador se ignora.

Argumentos

document_ids: Identificador (o lista de identificadores) de documentos que se borrará.
deadline: Plazo para la llamada del procedimiento remoto (RPC) en segundos.

Excepciones

DeleteError: No se pudieron borrar uno o más documentos, o el número borrado no coincidió con el número solicitado.
ValueError: El argumento no es una string o una colección iterable de identificadores de documentos válidos, o el número de identificadores de documentos es mayor que MAXIMUM_DOCUMENTS_PER_PUT_REQUEST.

get(self,doc_id, deadline=None)

Recupera un objeto Document del índice mediante el identificador del documento. Si no encuentra el documento, se muestra None.

Argumentos

doc_id: El identificador del documento que se recuperará.
deadline: Plazo para la llamada del procedimiento remoto (RPC) en segundos.

Valor del resultado

Un objeto Document cuyo identificador coincide con el que suministra doc_id.

search(query, deadline=None)

Busca en el índice los documentos que coinciden con la consulta. La consulta puede ser una string o un objeto Query.

Por ejemplo, el siguiente fragmento de código solicita una búsqueda de documentos en los que 'first' ocurre en el asunto y 'good' ocurre en cualquier lugar, y muestra 20 documentos como máximo, comienza la búsqueda en 'cursor token', muestra otro cursor único para la respuesta, ordena los asuntos de forma descendente, y muestra los campos de autor, asunto y resumen, así como contenido del campo fragmentado.

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

En el siguiente fragmento de código, se muestra cómo usar un cursor de resultados.

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

En el siguiente fragmento de código, se muestra cómo usar un 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))
               )

Argumentos

query: La consulta que debe coincidir con los documentos del índice, descrita en un objeto Query. Para obtener más información, consulta Descripción general del lenguaje de consulta.
deadline: Plazo para la llamada del procedimiento remoto (RPC) en segundos.

Valor del resultado

Un objeto SearchResults que contiene una lista de documentos coincidentes, el número mostrado y el número que coincide con la consulta.

Excepciones

TypeError: Un parámetro tiene un tipo no válido, o se pasó un atributo desconocido.
ValueError: Un parámetro tiene un valor no válido.

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

Obtiene un rango de documentos de un índice, en orden de doc_id.

Argumentos

start_id: String que contiene el identificador de documento que se usará para enumerar los documentos. De manera predeterminada, comienza en el primer identificador de documento.
include_start_object: Si el valor es true, incluye el documento especificado por start_id.
limit: Cantidad máxima de documentos que se mostrará.
ids_only: Si el valor es true, muestra solo los identificadores de documentos en lugar de los documentos completos.
deadline: Plazo para la llamada del procedimiento remoto (RPC) en segundos.

Valor del resultado

Un objeto A GetResponse que contiene una lista de los documentos recuperados, ordenados por identificador de documento.

Excepciones

TypeError: Se pasó un atributo desconocido.
Error: Surgió una subclase de Error mientras se procesaba la solicitud.