El API de almacén de datos representa entidades en forma de instancias de clases de modelos. Los métodos de una instancia de modelo crean, actualizan y eliminan la entidad. Las entidades se pueden extraer del almacén de datos como instancias de modelo mediante consultas o claves.
Las instancias de las clases Model (y Expando) representan entidades de almacén de datos. Las aplicaciones crean una nueva entidad de un tipo determinado mediante una llamada al constructor de la clase de modelo que se corresponde con el tipo.
| 
pet = Pet(name="Fluffy",
type="cat",
owner=users.get_current_user())
La nueva entidad no se crea en el almacén de datos hasta que la instancia se "coloca" por primera vez, mediante una llamada al método put() en la instancia o mediante la transferencia de la instancia a la función db.put().
pet.put() db.put(pet)
Si una instancia se ha almacenado anteriormente, el método put() actualiza la entidad existente.
Las consultas devuelven resultados en forma de instancias de modelo. Estas instancias se pueden modificar y devolver al almacén de datos.
if users.get_current_user():
user_pets = db.GqlQuery("SELECT * FROM Pet WHERE owner = :1",
users.get_current_user())
for pet in user_pets:
pet.spayed_or_neutered = True
db.put(user_pets)
El almacén de datos puede ejecutar consultas entre entidades de un determinado tipo. Una consulta puede filtrar los resultados mediante condiciones que deben cumplir los valores de propiedad de entidad y puede devolver los resultados ordenados por valores de propiedad. Una consulta también puede limitar el ámbito de búsqueda a entidades con un determinado ancestro; consulta Claves y grupos de entidades.
Puedes obtener una descripción completa del funcionamiento de las consultas, incluidas varias acciones que las consultas no pueden realizar, en la sección Consultas e índices.
El API de almacén de datos proporciona dos interfaces para realizar consultas sobre propiedades de entidad: Query, una interfaz que prepara consultas mediante el uso de métodos en un objeto de consulta, y GqlQuery, una interfaz que utiliza un lenguaje de consulta parecido a SQL llamado GQL.
El método all() aplicado a una clase Model (o Expando) devuelve un objeto Query que representa una consulta para todas las entidades del tipo correspondiente. La aplicación prepara la consulta mediante una llamada a los métodos filter(), order() y ancestor() aplicados al objeto.
class Story(db.Model):
title = db.StringProperty()
date = db.DateTimeProperty()
query = Story.all()
query.filter('title =', 'Foo')
query.order('-date')
query.ancestor(key)
# These methods can be chained together on one line.
query.filter('title =', 'Foo').order('-date').ancestor(key)
El constructor de la clase GqlQuery utiliza una cadena de consulta GQL y enlaces de parámetros opcionales. La cadena de consulta especifica el tipo, así como filtros, los criterios de ordenación y las condiciones de ancestro. La cadena de consulta también puede incluir una desviación y un límite de resultados.
# Parameters can be bound with positional arguments.
query = db.GqlQuery("SELECT * FROM Story WHERE title = :1 "
"AND ANCESTOR IS :2 "
"ORDER BY date DESC",
'Foo', key)
# Or, parameters can be bound with keyword arguments.
query = db.GqlQuery("SELECT * FROM Story WHERE title = :title "
"AND ANCESTOR IS :parent "
"ORDER BY date DESC",
title='Foo', parent=key)
# String, number and Boolean values can be literal values in the string.
query = db.GqlQuery("SELECT * FROM Story WHERE title = 'Foo' "
"AND ANCESTOR IS :parent "
"ORDER BY date DESC",
parent=key)
El método de clase gql() de una clase Model también prepara un objeto GqlQuery a partir de una cadena. La cadena es la cadena de consulta GQL en la que se ha omitido la expresión SELECT * FROM Model, porque esta parte está implícita.
query = Story.gql("WHERE title = :title "
"AND ANCESTOR IS :parent "
"ORDER BY date DESC",
title='Foo', parent=key)
Se puede utilizar el método bind() para volver a vincular los enlaces de parámetros a valores nuevos. Las aplicaciones pueden reutilizar un objeto GqlQuery si vuelven a vincular los parámetros y a ejecutar la consulta.
Los objetos Query y GqlQuery no ejecutan la consulta hasta que la aplicación intenta acceder a los resultados. Cuando la aplicación accede a los resultados, la consulta se ejecuta y los resultados se cargan en la memoria en forma de instancias de la clase de modelo de la consulta. Ambas clases de consulta proporcionan dos métodos para ejecutar la consulta y acceder a los resultados: el método fetch() y la interfaz de iterador.
El método fetch() selecciona un número máximo de resultados para extraer (el límite) y un número opcional de resultados que omitir (la desviación). El método ejecuta la consulta y, a continuación, extrae los resultados hasta que alcanza el límite o no hay más resultados. Una vez que los resultados se han cargado en memoria, accede a la desviación si se ha especificado una y, a continuación, devuelve los resultados solicitados en forma de lista de instancias de modelo. La consulta completa se ejecuta para cada llamada a fetch().
Nota: la desviación no afecta al número de resultados extraídos del almacén de datos. Todos los resultados que no superan el límite se extraen y se almacenan en memoria. La desviación sólo afecta a los elementos devueltos por el método fetch().
results = query.fetch(10) for result in results: print "Title: " + result.title
El límite y la desviación proporcionados al método fetch() sobrescriben cualquier desviación y límite especificados en una cadena de consulta GQL.
Si el objeto de consulta se utiliza como iterador, la consulta se ejecuta sin límite ni desviación, los resultados se cargan en memoria y el valor devuelto es un iterador para los resultados. El iterador genera instancias de la clase de modelo.
for result in query: print "Title: " + result.title
Nota: el almacén de datos devuelve un máximo de 1.000 resultados como respuesta a una consulta, independientemente de la desviación y del límite utilizados para extraer los resultados. En estos 1.000 resultados se incluye cualquier resultado que se omita mediante una desviación; por ejemplo, una consulta con más de 1.000 resultados que utilice una desviación de 100 devolverá 900 resultados.
Una vez almacenada una entidad en el almacén de datos, ésta presentará una clave única. Los valores clave se representan en el API en forma de instancias de la clase Key. El método put() de una instancia de modelo y la función db.put() devuelven la clave de la entidad almacenada. Una vez que se haya almacenado por primera vez una instancia de modelo, el método key() de la instancia de modelo devolverá la clave de la instancia.
entity.put() key = entity.key() # ... entity = db.get(key)
Un uso habitual de un valor Key es su almacenamiento como valor de una propiedad en otra entidad. La clase de propiedad de modelo ReferenceProperty permite la referencia y la anulación de la referencia automáticas de instancias de modelo como claves: se puede asignar una instancia de modelo directamente a una clase ReferenceProperty, cuya clave se utilizará como valor.
class PetOwner(db.Model): name = db.StringProperty() class Pet(db.Model): name = db.StringProperty() owner = db.ReferenceProperty(PetOwner) owner = PetOwner(name="Albert") pet = Pet(name="Fluffy", owner=owner) # This is equivalent: pet = Pet(name="Fluffy", owner=owner.key())
Del mismo modo, un valor de ReferenceProperty al que se accede a través de una propiedad actúa como su instancia. La entidad de datos se extrae de forma automática, aunque no se extrae hasta que se utiliza.
pets = db.GqlQuery("SELECT * FROM Pet WHERE name = :1", "Fluffy")
pet = pets.get()
owner_name = pet.owner.name
Los valores clave almacenados sin el modelo ReferenceProperty, tales como una propiedad dinámica Expando o un elemento ListProperty, no disponen del comportamiento de anulación de referencia automática.
La función db.get() extrae una entidad del almacén de datos para obtener una clave (o una lista de claves).
Las claves se pueden codificar como cadenas para su transmisión fuera de la aplicación. Para volver a convertir una clave codificada con cadena en un objeto Key, la aplicación transmite la cadena al constructor de Key.
obj = MyModel(name="Foo")
self.response.write('<a href="/view?key=%s">%s</a>' % (str(obj.key()),
obj.name()))
# ...
key_name = self.request.get('key')
obj = db.get(db.Key(key_name))
Nota: la codificación de cadena de una clave es opaca, pero no está encriptada. Si la aplicación requiere que las claves no se puedan averiguar, deberás encriptar la clave codificada con cadena antes de enviarla al usuario.
Las aplicaciones pueden eliminar una entidad del almacén de datos mediante una instancia de modelo o una clave. El método delete() de la instancia de modelo elimina la entidad correspondiente del almacén de datos. La función delete() utiliza una clave o una lista de claves y elimina la entidad (o las entidades) del almacén de datos.
q = db.GqlQuery("SELECT * FROM Message WHERE create_date < :1", earliest_date)
results = q.fetch(10)
for result in results:
result.delete()
# or...
q = db.GqlQuery("SELECT * FROM Message WHERE create_date < :1", earliest_date)
results = q.fetch(10)
db.delete(results)
Si se elimina una entidad, no se modificará ningún valor de Key en el almacén de datos que pueda hacer referencia a la entidad. Si la aplicación pretendiera anular la referencia a un valor de Key para una entidad eliminada, debería hacerlo mediante db.get() y, a continuación, probar el valor de retorno antes de acceder a las propiedades.
La eliminación de una entidad que es ancestro de otras entidades no afecta al resto de entidades. La aplicación podrá seguir accediendo a las subentidades siempre que no dependa de la existencia del ancestro para crear claves para ellas.