Información general sobre la biblioteca de cliente NDB de Python 2 para App Engine

La biblioteca de cliente NDB de Google Datastore permite que las aplicaciones de Python de App Engine se conecten a Datastore. La biblioteca de cliente NDB se basa en la biblioteca DB Datastore anterior y añade las siguientes funciones de almacén de datos:

  • La clase StructuredProperty, que permite que las entidades tengan una estructura anidada.
  • Caché automática integrada, que suele ofrecer lecturas rápidas y económicas a través de una caché en contexto y Memcache.
  • Admite APIs asíncronas para acciones simultáneas, además de APIs síncronas.

En esta página se ofrece una introducción y una descripción general de la biblioteca de cliente NDB de App Engine. Para obtener información sobre cómo migrar a Cloud NDB, que es compatible con Python 3, consulta el artículo Migrar a Cloud NDB.

Definir entidades, claves y propiedades

Datastore almacena objetos de datos, llamados entidades. Una entidad tiene una o varias propiedades, que son valores con nombre de uno de los varios tipos de datos admitidos. Por ejemplo, una propiedad puede ser una cadena, un número entero o una referencia a otra entidad.

Cada entidad se identifica mediante una clave, un identificador único en el almacén de datos de la aplicación. La clave puede tener un elemento superior, que es otra clave. Este elemento superior puede tener otro elemento superior, y así sucesivamente. En la parte superior de esta "cadena" de elementos superiores se encuentra una clave sin elemento superior, denominada raíz.

Muestra la relación entre la entidad raíz y las entidades secundarias de un grupo de entidades.

Las entidades cuyas claves tienen la misma raíz forman un grupo de entidades o un grupo. Si las entidades están en grupos diferentes, los cambios en esas entidades a veces pueden parecer que se producen "fuera de orden". Si las entidades no están relacionadas en la semántica de tu aplicación, no pasa nada. Sin embargo, si los cambios de algunas entidades deben ser coherentes, tu aplicación debe incluirlos en el mismo grupo al crearlas.

En el siguiente diagrama de relación entre entidades y ejemplo de código se muestra cómo un Guestbook puede tener varios Greetings, cada uno de los cuales tiene propiedades content y date.

Muestra las relaciones de las entidades tal como las crea el código de ejemplo incluido.

Esta relación se implementa en el código de muestra que figura más abajo.

import cgi
import textwrap
import urllib

from google.appengine.ext import ndb

import webapp2


class Greeting(ndb.Model):
    """Models an individual Guestbook entry with content and date."""
    content = ndb.StringProperty()
    date = ndb.DateTimeProperty(auto_now_add=True)

    @classmethod
    def query_book(cls, ancestor_key):
        return cls.query(ancestor=ancestor_key).order(-cls.date)


class MainPage(webapp2.RequestHandler):
    def get(self):
        self.response.out.write('<html><body>')
        guestbook_name = self.request.get('guestbook_name')
        ancestor_key = ndb.Key("Book", guestbook_name or "*notitle*")
        greetings = Greeting.query_book(ancestor_key).fetch(20)

        greeting_blockquotes = []
        for greeting in greetings:
            greeting_blockquotes.append(
                '<blockquote>%s</blockquote>' % cgi.escape(greeting.content))

        self.response.out.write(textwrap.dedent("""\
            <html>
              <body>
                {blockquotes}
                <form action="/sign?{sign}" method="post">
                  <div>
                    <textarea name="content" rows="3" cols="60">
                    </textarea>
                  </div>
                  <div>
                    <input type="submit" value="Sign Guestbook">
                  </div>
                </form>
                <hr>
                <form>
                  Guestbook name:
                    <input value="{guestbook_name}" name="guestbook_name">
                    <input type="submit" value="switch">
                </form>
              </body>
            </html>""").format(
                blockquotes='\n'.join(greeting_blockquotes),
                sign=urllib.urlencode({'guestbook_name': guestbook_name}),
                guestbook_name=cgi.escape(guestbook_name)))


class SubmitForm(webapp2.RequestHandler):
    def post(self):
        # We set the parent key on each 'Greeting' to ensure each guestbook's
        # greetings are in the same entity group.
        guestbook_name = self.request.get('guestbook_name')
        greeting = Greeting(parent=ndb.Key("Book",
                                           guestbook_name or "*notitle*"),
                            content=self.request.get('content'))
        greeting.put()
        self.redirect('/?' + urllib.urlencode(
            {'guestbook_name': guestbook_name}))


app = webapp2.WSGIApplication([
    ('/', MainPage),
    ('/sign', SubmitForm)
])

Usar modelos para almacenar datos

Un modelo es una clase que describe un tipo de entidad, incluidos los tipos y la configuración de sus propiedades. Es más o menos análogo a una tabla de SQL. Para crear una entidad, llama al constructor de la clase del modelo y, a continuación, almacénala llamando al método put().

En este código de ejemplo se define la clase de modelo Greeting. Cada entidad Greeting tiene dos propiedades: el contenido de texto de la felicitación y la fecha en la que se creó.

class Greeting(ndb.Model):
    """Models an individual Guestbook entry with content and date."""
    content = ndb.StringProperty()
    date = ndb.DateTimeProperty(auto_now_add=True)
 
class SubmitForm(webapp2.RequestHandler):
    def post(self):
        # We set the parent key on each 'Greeting' to ensure each guestbook's
        # greetings are in the same entity group.
        guestbook_name = self.request.get('guestbook_name')
        greeting = Greeting(parent=ndb.Key("Book",
                                           guestbook_name or "*notitle*"),
                            content=self.request.get('content'))
        greeting.put()

Para crear y almacenar un nuevo saludo, la aplicación crea un objeto Greeting y llama a su método put().

Para asegurarse de que los saludos de un libro de visitas no aparezcan "desordenados", la aplicación define una clave principal al crear un nuevo Greeting. Por lo tanto, el nuevo saludo estará en el mismo grupo de entidades que otros saludos del mismo libro de visitas. La aplicación usa este hecho cuando realiza consultas: usa una consulta de ancestro.

Consultas e índices

Una aplicación puede hacer consultas para encontrar entidades que coincidan con algunos filtros.

    @classmethod
    def query_book(cls, ancestor_key):
        return cls.query(ancestor=ancestor_key).order(-cls.date)


class MainPage(webapp2.RequestHandler):
    def get(self):
        self.response.out.write('<html><body>')
        guestbook_name = self.request.get('guestbook_name')
        ancestor_key = ndb.Key("Book", guestbook_name or "*notitle*")
        greetings = Greeting.query_book(ancestor_key).fetch(20)

Una consulta de NDB típica filtra las entidades por tipo. En este ejemplo, query_book genera una consulta que devuelve entidades Greeting. Una consulta también puede especificar filtros en los valores y las claves de las propiedades de las entidades. Como en este ejemplo, una consulta puede especificar un ancestro y encontrar solo las entidades que "pertenecen" a algún ancestro. Una consulta puede especificar el orden. Si una entidad determinada tiene al menos un valor (posiblemente nulo) para cada propiedad de los filtros y los criterios de ordenación, y los valores de las propiedades cumplen todos los criterios de filtro, esa entidad se devuelve como resultado.

Cada consulta usa un índice, una tabla que contiene los resultados de la consulta en el orden deseado. Datastore subyacente mantiene automáticamente los índices simples (índices que usan una sola propiedad).

Define sus índices complejos en un archivo de configuración, index.yaml. El servidor web de desarrollo añade automáticamente sugerencias a este archivo cuando encuentra consultas que aún no tienen índices configurados.

Puedes ajustar los índices manualmente editando el archivo antes de subir la aplicación. Puedes actualizar los índices por separado de la carga de la aplicación ejecutando gcloud app deploy index.yaml. Si tu almacén de datos tiene muchas entidades, se tarda mucho tiempo en crear un nuevo índice para ellas. En este caso, es recomendable actualizar las definiciones de índice antes de subir el código que utiliza el nuevo índice. Puede usar la consola de administración para saber cuándo se han terminado de crear los índices.

Este mecanismo de indexación admite una amplia gama de consultas y es adecuado para la mayoría de las aplicaciones. Sin embargo, no admite algunos tipos de consultas habituales en otras tecnologías de bases de datos. En concreto, no se admiten las combinaciones.

Información sobre las escrituras de NDB: confirmación, invalidación de caché y aplicación

NDB escribe los datos en pasos:

  • En la fase de confirmación, el servicio Datastore subyacente registra los cambios.
  • NDB invalida sus cachés de las entidades afectadas. Por lo tanto, las lecturas futuras leerán (y almacenarán en caché) el almacén de datos subyacente en lugar de leer valores obsoletos de la caché.
  • Por último, quizás unos segundos después, el almacén de datos subyacente aplica el cambio. Hace que el cambio sea visible para las consultas globales y, finalmente, para las lecturas coherentes.

La función NDB que escribe los datos (por ejemplo, put()) devuelve un valor después de la invalidación de la caché. La fase de aplicación se produce de forma asíncrona.

Si se produce un fallo durante la fase de confirmación, se reintenta automáticamente, pero si los fallos continúan, tu aplicación recibe una excepción. Si la fase de confirmación se completa correctamente, pero la de aplicación falla, la aplicación se completa cuando se produce una de las siguientes situaciones:

  • Las "barridas" periódicas de Datastore comprueban si hay trabajos de confirmación incompletos y los aplican.
  • La siguiente escritura, transacción o lectura con coherencia fuerte en el grupo de entidades afectado provoca que los cambios que aún no se han aplicado se apliquen antes de la lectura, la escritura o la transacción.

Este comportamiento afecta a cómo y cuándo se muestran los datos en tu aplicación. Es posible que el cambio no se aplique por completo al almacén de datos subyacente hasta unos cientos de milisegundos después de que la función NDB devuelva un valor. Una consulta que no sea de ancestro realizada mientras se aplica un cambio puede ver un estado incoherente, es decir, parte del cambio, pero no todo.

Transacciones y datos de almacenamiento en caché

La biblioteca de cliente de NDB puede agrupar varias operaciones en una sola transacción. La transacción no se puede completar a menos que todas las operaciones que la componen se realicen correctamente. Si alguna de las operaciones falla, la transacción se revierte automáticamente. Esto es especialmente útil en aplicaciones web distribuidas, donde varios usuarios pueden acceder o manipular los mismos datos al mismo tiempo.

NDB usa Memcache como servicio de caché para los "puntos de acceso" de los datos. Si la aplicación lee algunas entidades con frecuencia, NDB puede leerlas rápidamente de la caché.

Usar Django con NDB

Para usar NDB con el framework web Django, añade google.appengine.ext.ndb.django_middleware.NdbDjangoMiddleware a la entrada MIDDLEWARE_CLASSES en tu archivo settings.py de Django. Es mejor insertarlo delante de cualquier otra clase de middleware, ya que es posible que otro middleware haga llamadas al almacén de datos y no se gestionen correctamente si se invoca antes que este middleware. Puedes consultar más información sobre el middleware de Django.

¿Qué debo hacer ahora?

Consulta más información sobre lo siguiente: