Classe Index

La classe Index représente un index permettant d'indexer, de supprimer et de rechercher des documents.

La classe Index est définie dans le module google.appengine.api.search.

Présentation

La classe Index fournit des arguments pour construire un index, ainsi que des fonctions vous permettant d'ajouter, de répertorier, de rechercher et de supprimer des documents (ou une collection de documents itérable) au sein de l'index. Vous construisez un index à l'aide d'arguments de la classe Index, y compris le nom et l'espace de noms de l'index.

Le code suivant montre comment insérer des documents dans un index, puis rechercher des documents correspondant à une requête :

# 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

Constructeur

Le constructeur de la classe Index est défini comme suit :

Index(name, namespace=None)

Permet de construire une instance de la classe Index.

Arguments

name

Nom de l'index (voir la section Propriétés ci-dessous pour plus d'informations).

namespace

Pour les applications à architecture mutualisée, espace de noms dans lequel le nom d'index est défini.

Valeur de résultat

Nouvelle instance de la classe Index.

Propriétés

Une instance de la classe Index possède les propriétés suivantes :

schema

Noms de champs de mise en correspondance de schéma associés à la liste des types compatibles. Valide uniquement pour les index renvoyés via la méthode search.get_indexes.

name

Nom d'index, chaîne ASCII lisible destinée à identifier l'index. Ne doit contenir aucun caractère d'espacement ni commencer par un point d'exclamation (!).

namespace

Espace de noms dans lequel le nom d'index est défini.

storage_usage

Nombre approximatif d'octets utilisés par cet index. Peut ne pas refléter les résultats des modifications récentes. Valide uniquement pour les index renvoyés via la méthode search.get_indexes.

storage_limit

Stockage maximal autorisé pour cet index, en octets. Valide uniquement pour les index renvoyés via la méthode search.get_indexes.

Méthodes des instances

Les instances de la classe Index utilisent les méthodes suivantes :

put(self, documents, deadline=None)

Si les documents spécifiés ont déjà été insérés dans l'index et s'ils ont les mêmes valeurs doc_ids, ils sont réindexés avec le contenu mis à jour.

Arguments

documents

Document (ou collection de documents pouvant être remplacés) à indexer.

deadline

Date limite pour l'appel RPC en secondes.

Valeur de résultat

Liste des résultats (PutResult), un pour chaque document devant être indexé.

Exceptions

PutError

Un ou plusieurs documents n'ont pas pu être indexés, ou le numéro indexé ne correspond pas au numéro demandé.

TypeError

Attribut inconnu transmis.

ValueError

Argument (et non un document ou une collection de documents pouvant être remplacés) ou nombre de documents supérieur à MAXIMUM_DOCUMENTS_PER_PUT_REQUEST.

delete(self, document_ids, deadline=None)

Supprime des documents d'un index.

S'il n'existe aucun document associé à un identifiant dans la liste, cet identifiant est ignoré.

Arguments

document_ids

Identifiant (ou liste d'identifiants) des documents à supprimer.

deadline

Date limite pour l'appel RPC en secondes.

Exceptions

DeleteError

Un ou plusieurs documents n'ont pas pu être supprimés, ou le numéro supprimé ne correspond pas au numéro demandé.

ValueError

Argument (et non une chaîne ou une collection d'identifiants de document valides pouvant être remplacés) ou nombre d'identifiants de document supérieur à MAXIMUM_DOCUMENTS_PER_PUT_REQUEST.

get(self,doc_id, deadline=None)

Récupère un document de l'index en utilisant l'identifiant du document. Si le document n'est pas trouvé, la valeur None est renvoyée.

Arguments

doc_id

Identifiant du document à récupérer.

deadline

Date limite pour l'appel RPC en secondes.

Valeur de résultat

Objet Document dont l'identifiant correspond à celui fourni par doc_id.

Recherche dans l'index les documents correspondant à la requête. La requête peut être une chaîne ou un objet Query.

Par exemple, le fragment de code ci-après demande une recherche de documents à partir du terme "first" dans le sujet et du terme "good" présent partout dans le texte, selon les critères suivants : renvoi de 20 documents au plus, curseur de résultats sur un seul document, tri par sujet et par ordre décroissant, et champs d'auteur, de sujet, de résumé et d'extrait de contenu.

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

Le fragment de code suivant montre comment utiliser un curseur de résultats.

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

Le fragment de code suivant montre comment utiliser un curseur 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))
               )

Arguments

query

Requête à faire correspondre aux documents de l'index, décrite dans un objet Query. Pour plus d'informations, consultez la présentation du langage de requête.

deadline

Date limite pour l'appel RPC en secondes.

Valeur de résultat

Objet SearchResults contenant une liste de documents correspondants, le nombre renvoyé et le nombre correspondant à la requête.

Exceptions

TypeError

L'un des paramètres possède un type non valide ou un attribut inconnu a été transmis.

ValueError

L'un des paramètres contient une valeur non valide.

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

Obtient une plage de documents à partir d'un index, classés selon l'identifiant de document (doc_id).

Arguments

start_id

Chaîne contenant l'identifiant du document à partir duquel répertorier les documents. Par défaut, commence par le premier identifiant de document.

include_start_object

Si la valeur est définie sur true, inclut le document spécifié par start_id.

limit

Nombre maximal de documents à renvoyer.

ids_only

Si la valeur est définie sur true, renvoie uniquement les identifiants de document au lieu de documents complets.

deadline

Date limite pour l'appel RPC en secondes.

Valeur de résultat

Objet A GetResponse contenant une liste des documents récupérés, classés selon l'identifiant de document.

Exceptions

TypeError

Attribut inconnu transmis.

Erreur

Une sous-classe d'erreur (Error) est survenue lors du traitement de la demande.