Aviso: En los próximos meses, reorganizaremos el sitio de documentación de App Engine para facilitar la búsqueda de contenido y alinearlo mejor con el resto de los productos de Google Cloud. El mismo contenido estará disponible, pero la navegación ahora coincidirá con el resto de los productos de Cloud.

Python 2 ya no es compatible con la comunidad. Recomendamos que migres las apps de Python 2 a Python 3.

Funciones de Datastore

Nota: Se recomienda enfáticamente a los desarrolladores que compilan aplicaciones nuevas que usen la biblioteca cliente de NDB, ya que tiene muchas ventajas en comparación con esta biblioteca cliente, como el almacenamiento en caché automático de entidades mediante la API de Memcache. Si por el momento usas la biblioteca cliente de DB anterior, lee la Guía de migración de DB a NDB.

Las funciones descritas en esta página se definen en el paquete google.appengine.ext.db.

Funciones

allocate_ids (model, count)

Asigna un lote de ID en Datastore para una combinación de similares y superiores de Datastore.

Los ID asignados de esta manera no serán utilizados por el generador de secuencias de ID automáticos de Datastore y se podrán usar en claves de entidad sin que se generen conflictos.

Argumentos

model: La clave de modelo para la cual se asignará un lote de ID. Esta es una clave normal, pero solo el similar y superior de la clave son necesarios para determinar la secuencia de ID que se utilizará.
count: La cantidad de ID que se asignarán.

Muestra una tupla del primer y el último ID que asigna. Por ejemplo, si asigna 10 ID mediante esta función, se los mostrará un valor en el formato (1, 10), pero no se presentará una lista completa de los ID creados.

Ejemplo de la asignación y el uso de ID:

# allocate for MyModel without an instance
handmade_key = db.Key.from_path('MyModel', 1)
first_batch = db.allocate_ids(handmade_key, 10)
first_range = range(first_batch[0], first_batch[1] + 1)

# or allocate using an existing key
model_instance = MyModel.all().get()
second_batch = db.allocate_ids(model_instance.key(), 10)
second_range = range(second_batch[0], second_batch[1] + 1)

# and then use them! woo!
my_id = second_range.pop(0)
new_key = db.Key.from_path('MyModel', my_id)
new_instance = MyModel(key=new_key)
new_instance.put()
assert new_instance.key().id() == my_id

# the Datastore will not assign ids in first_batch or second_batch
another_instance = MyModel()
another_instance.put()
assert another_instance.key().id() not in first_range
assert another_instance.key().id() not in second_range

allocate_ids_async (model, count)

Asigna de forma asíncrona un lote de ID en Datastore para una combinación de similares y superiores de Datastore.

Esta función es idéntica a allocate_ids(), excepto que muestra un objeto asíncrono. Puedes llamar a get_result() en el valor de muestra para realizar el bloqueo en la llamada y mostrar el resultado.

Argumentos

model: Una instancia db.Model, una clave o una string que funcione como una plantilla que especifique la secuencia de ID en la que se deben asignar los ID. Los identificadores mostrados solo deben usarse en entidades con el mismo superior (si existe) y del mismo grupo de similares que esta clave.
count: La cantidad de ID que se asignarán.

Muestra una tupla del primer y el último ID que asigna. Por ejemplo, si asigna 10 ID mediante esta función, se los mostrará en el formato (1, 10), pero no se presentará una lista completa de los ID creados.

allocate_id_range (model, start, end, **kwargs)

Asigna un rango de ID con extremos específicos. Una vez que se han asignado estos ID, puede vincularlos manualmente a las entidades recién creadas.

El asignador automático de ID de Datastore nunca indica una clave que ya ha sido asignada (ya sea a través de la asignación automática de ID o mediante una llamada explícita a allocate_ids). Como resultado, las entidades escritas en el rango de claves dado nunca se reemplazarán. Sin embargo, la escritura de entidades con claves asignadas manualmente en este rango puede reemplazar las entidades existentes (o las nuevas entidades escritas por una solicitud separada), en función del estado de rango de claves mostrado.

Utiliza esta función solo si tienes un rango de ID numéricos existente que deseas reservar (por ejemplo, entidades de carga masiva que ya tienen ID). Si no te importa qué ID recibes, es mejor que utilices allocate_ids().

Argumentos

model: Una instancia db.Model, una clave o una string que funcione como una plantilla que especifique la secuencia de ID en la que se deben asignar los ID. Los identificadores mostrados solo deben usarse en entidades con el mismo superior (si existe) y del mismo grupo de similares que esta clave.
start: El primer ID numérico que se asignará.
end: El último ID numérico que se asignará.

Muestra una de estas opciones: KEY_RANGE_EMPTY, KEY_RANGE_CONTENTION o KEY_RANGE_COLLISION. Si no es KEY_RANGE_EMPTY, esto representa un posible problema con el uso del rango de claves asignado.

create_transaction_options (**kwargs)

Crea un objeto de opciones de transacción (clase TransactionOptions) para controlar la ejecución de la transacción. Debes pasar el objeto resultante como primer argumento a la función run_in_transaction_options().

Argumentos

propagation

Qué hacer si se llama a esta función transaccional desde otra transacción:

ALLOWED: Si ya estás en una transacción, continúa usándola; de lo contrario, inicia una.
Nota: Si una función que utiliza esta política genera una excepción, probablemente no sea seguro detectar la excepción y confirmar la transacción externa; la función puede haber dejado la transacción externa en un estado incorrecto.
MANDATORY: Continúa en la transacción existente, si la hubiere; en caso contrario, genera una excepción BadRequestError
Nota: Si una función que utiliza esta política genera una excepción, probablemente no sea seguro detectar la excepción y confirmar la transacción externa; la función puede haber dejado la transacción externa en un estado incorrecto.
INDEPENDENT: Crea una nueva transacción, pausando cualquier transacción existente.
Nota: Una función que usa esta política no debe mostrar ninguna entidad leída en la nueva transacción, ya que las entidades no son consistentemente transaccionales con la transacción externa.
NESTED: (Aún no se admite) Crea una transacción anidada dentro de una existente.

xg

Si el valor es True, permite transacciones entre grupos (XG). Si se establece un valor no booleano, se genera una excepción BadArgumentError.

retries

Cantidad de reintentos que se realizan en caso de falla de confirmación de la transacción.

deadline

El tiempo máximo en segundos que se esperará que Datastore muestre un resultado antes de anular con un error. Acepta un valor de número entero o punto flotante. No puedes establecerlo con un valor más alto que el predeterminado (60 segundos), pero puedes reducirlo para asegurarte de que una operación en particular falle rápidamente (por ejemplo, con el objetivo de mostrar una respuesta más rápida al usuario, reintentar la operación, probar con otra o agregarla a la lista de tareas en cola).

El siguiente ejemplo crea las opciones para una transacción de grupo cruzado (XG):

from google.appengine.ext import db

xg_on = db.create_transaction_options(xg=True)

def my_txn():
  x = MyModel(a=3)
  x.put()
  y = MyModel(a=7)
  y.put()

db.run_in_transaction_options(xg_on, my_txn)

delete (models, deadline=60)

Borra una o más instancias de modelo desde Datastore.

Argumentos

models: Una instancia de modelo, una clave de entidad o una lista (o incluso otro iterable) de instancias de modelo o claves de entidad que se deben borrar.
deadline: El tiempo máximo en segundos que se esperará que Datastore muestre un resultado antes de anular con un error. Acepta un valor de número entero o punto flotante. No puedes establecerlo con un valor más alto que el predeterminado (60 segundos), pero puedes reducirlo para asegurarte de que una operación en particular falle rápidamente (por ejemplo, con el objetivo de mostrar una respuesta más rápida al usuario, reintentar la operación, probar con otra o agregarla a la lista de tareas en cola).

Al igual que con put(), si se proporcionan varias claves, estas pueden estar en más de un grupo de entidades.

Siempre se generará una excepción si se produce algún error durante la operación, incluso si algunas de las entidades realmente se borraron. Si la llamada se muestra sin generar una excepción, entonces todas las entidades fueron borradas correctamente.

Precaución: Borrar varias entidades en una sola operación no garantiza que las eliminaciones se realicen de forma atómica, a menos que la operación se realice dentro de una transacción. Otros procesos que consultan a Datastore pueden presentar resultados incoherentes aun cuando la consulta se realice con una coherencia sólida.

delete_async (models, deadline=60)

Borra de manera asíncrona una o más instancias de modelo desde Datastore.

Esta función es idéntica a delete(), excepto que muestra un objeto asíncrono. Puedes llamar a get_result() en el valor de muestra para realizar el bloqueo en la llamada.

Argumentos

models: Una instancia de modelo, una clave de entidad o una lista (o incluso otro iterable) de instancias de modelo o claves de entidad que se deben borrar.
deadline: El tiempo máximo en segundos que se esperará que Datastore muestre un resultado antes de anular con un error. Acepta un valor de número entero o punto flotante. No puedes establecerlo con un valor más alto que el predeterminado (60 segundos), pero puedes reducirlo para asegurarte de que una operación en particular falle rápidamente (por ejemplo, con el objetivo de mostrar una respuesta más rápida al usuario, reintentar la operación, probar con otra o agregarla a la lista de tareas en cola).

Al igual que con put(), si se proporcionan varias claves, estas pueden estar en más de un grupo de entidades.

Esta función muestra un objeto que te permite para realizar el bloqueo en el resultado de la llamada.

get (keys, read_policy=STRONG_CONSISTENCY, deadline=60)

Recupera las instancias de modelo específicas con las claves dadas desde Datastore.

Argumentos

keys

La clave de la entidad que se recuperará, una representación de string de la clave o una lista de claves o sus representaciones de string.

read_policy

La política de lectura que especifica el nivel deseado de coherencia de datos:

STRONG_CONSISTENCY: Garantiza los resultados más recientes, pero se limita a un solo grupo de entidades.
EVENTUAL_CONSISTENCY: Puede abarcar varios grupos de entidades, pero a veces puede mostrar resultados obsoletos. Por lo general, las consultas de coherencia eventual se ejecutan más rápido que las de coherencia sólida, pero no se garantiza.

Nota: Las consultas globales (no las principales) omiten este argumento.

deadline

Si keys consiste en una sola clave (o su representación de string), esta función muestra la instancia de modelo asociada con la clave si esta existe en Datastore, de lo contrario, None. Si keys es una lista, el valor que se muestra es una lista correspondiente de instancias de modelo, con valores None en los que no existe una entidad para una clave determinada.

También consulta Model.get().

get_async (keys, read_policy=STRONG_CONSISTENCY, deadline=60)

Recupera de forma asíncrona las instancias de modelo especificadas desde Datastore.

Esta función es idéntica a get(), excepto que muestra un objeto asíncrono. Puedes llamar a get_result() en el valor de muestra para realizar el bloqueo en la llamada y obtener los resultados.

Argumentos

keys

La clave de la entidad que se recuperará, una representación de string de la clave o una lista de claves o sus representaciones de string.

read_policy

La política de lectura que especifica el nivel deseado de coherencia de datos:

STRONG_CONSISTENCY: Garantiza los resultados más recientes, pero se limita a un solo grupo de entidades.
EVENTUAL_CONSISTENCY: Puede abarcar varios grupos de entidades, pero a veces puede mostrar resultados obsoletos. Por lo general, las consultas de coherencia eventual se ejecutan más rápido que las de coherencia sólida, pero no se garantiza.

Nota: Las consultas globales (no las principales) omiten este argumento.

deadline

También consulta Model.get().

get_indexes()

Muestra una lista de índices compuestos que pertenecen a la aplicación que realiza la llamada.

El siguiente ejemplo ilustra cómo obtener y usar los índices:

def get_index_state_as_string(index_state):
  return {db.Index.BUILDING:'BUILDING', db.Index.SERVING:'SERVING',
          db.Index.DELETING:'DELETING', db.Index.ERROR:'ERROR'}[index_state]

def get_sort_direction_as_string(sort_direction):
  return {db.Index.ASCENDING:'ASCENDING',
          db.Index.DESCENDING:'DESCENDING'}[sort_direction]

def dump_indexes():
  for index, state in db.get_indexes():
    print "Kind: %s" % index.kind()
    print "State: %s" % get_index_state_as_string(state)
    print "Is ancestor: %s" % index.has_ancestor()
    for property_name, sort_direction in index.properties():
      print "  %s:%s" % (property_name,
                         get_sort_direction_as_string(sort_direction))

get_indexes_async()

Muestra de manera asíncrona una lista de índices compuestos que pertenecen a la aplicación que realiza la llamada.

is_in_transaction()

Muestra un valor booleano que indica si el alcance actual está en ejecución en una transacción.

model_to_protobuf (model_instance)

Crea la serialización de búfer de protocolo de una instancia de Model. Un búfer de protocolo es el formato de serialización de Google utilizado para las llamadas a procedimientos remotos, y puede ser útil si deseas serializar objetos de Datastore con fines de copia de seguridad y restablecimiento.

Precaución: Esta función no utiliza el formato de búfer de protocolo de código abierto, sino un formato diferente (más antiguo) que no es compatible con la implementación de código abierto.

Argumento

model_instance: La instancia de la clase Model (o una subclase) que se serializará.

Muestra la serialización de búfer de protocolo del objeto, como una string de bytes.

model_from_protobuf (pb)

Crea una instancia de Model basada en una serialización de búfer de protocolo. Consulta model_to_protobuf() para obtener más información.

Argumento

pb: La serialización de búfer de protocolo, como lo muestra model_to_protobuf().

Muestra un objeto de la clase de similares apropiada. Si la clase de similares no existe, genera una excepción KindError. Si el objeto no es válido según el modelo, se genera una excepción BadValueError.

Puedes guardar el nuevo objeto en Datastore como cualquier otra instancia de Model (por ejemplo, con una llamada a su método put()). El objeto retiene la clave que tenía cuando se creó el búfer de protocolo. Si ya existe un objeto con esa clave en Datastore, cuando guardas el objeto deserializado se reemplaza el objeto existente.

Precaución: Si la clave del objeto utiliza un ID asignado por el sistema y ese ID aún no se ha asignado para la ruta de acceso y el similar dados, la operación de guardado se realizará correctamente, pero no se reservará el ID. A un objeto creado en el futuro se le podrá asignar ese ID y este podría reemplazar el objeto anterior. Por seguridad, restablezca los objetos solo en la misma aplicación en la que existían cuando se serializaron.

model_is_projection (model_instance)

Muestra True si la consulta especificada (model_instance) es una consulta de proyección en lugar de una consulta para una entidad completa.

Argumento

model_instance: La consulta que deseas verificar para determinar si es una consulta de proyección.

Muestra True si la consulta es una de proyección, False si no lo es.

put (models, deadline=60)

Escribe una o más instancias de modelo desde Datastore.

Argumentos

models: Una instancia de modelo o una lista de instancias de modelo que se deben almacenar.
deadline: El tiempo máximo en segundos que se esperará que Datastore muestre un resultado antes de anular con un error. Acepta un valor de número entero o punto flotante. No puedes establecerlo con un valor más alto que el predeterminado (60 segundos), pero puedes reducirlo para asegurarte de que una operación en particular falle rápidamente (por ejemplo, con el objetivo de mostrar una respuesta más rápida al usuario, reintentar la operación, probar con otra o agregarla a la lista de tareas en cola).

Si se dan varias instancias de modelo, estas pueden estar en más de un grupo de entidad.

Siempre se generará una excepción si se produce algún error durante la operación, incluso si algunas de las entidades realmente se escribieron. Si la llamada se muestra sin generar una excepción, entonces todas las entidades fueron eliminadas correctamente.

Si models consta de una única instancia de modelo, esta función muestra el objeto de clave. Si models es una lista, el valor que se muestra es una lista de objetos de clave correspondientes.

Precaución: El hecho de escribir varias entidades en una sola operación no garantiza que las eliminaciones se realicen de forma atómica, a menos que la operación se realice dentro de una transacción. Otros procesos que consultan a Datastore pueden presentar resultados incoherentes aun cuando la consulta se realice con una coherencia sólida.

put_async (models, deadline=60)

Escribe una o más instancias de modelo desde Datastore.

Esta función es idéntica a put(), excepto que muestra un objeto asíncrono. Puedes llamar a get_result() en el valor de muestra para realizar el bloqueo en la llamada y obtener los resultados.

Argumentos

models: Una instancia de modelo o una lista de instancias de modelo que se deben almacenar.
deadline: El tiempo máximo en segundos que se esperará que Datastore muestre un resultado antes de anular con un error. Acepta un valor de número entero o punto flotante. No puedes establecerlo con un valor más alto que el predeterminado (60 segundos), pero puedes reducirlo para asegurarte de que una operación en particular falle rápidamente (por ejemplo, con el objetivo de mostrar una respuesta más rápida al usuario, reintentar la operación, probar con otra o agregarla a la lista de tareas en cola).

Si se dan varias instancias de modelo, estas pueden estar en más de un grupo de entidad.

Esta función muestra un objeto asíncrono en el que se puede llamar a get_result(). Los resultados que se muestran son los mismos que para put().

query_descendants (model_instance)

Muestra una consulta para todos los descendientes de una instancia de modelo.

Argumento

model_instance: La instancia de modelo cuyos descendientes quieres encontrar.

run_in_transaction (function, *args, **kwargs)

Ejecuta una función que contiene actualizaciones de Datastore en una sola transacción. Si algún código genera una excepción durante la transacción, todas las actualizaciones realizadas en la transacción se revierten. Como alternativa, puedes usar el decorador @db.transactional().

Argumentos

function: Función que se ejecutará
args: Argumentos posicionales para pasar a la función.
kwargs: Argumentos de palabra clave para pasar a la función.

Si la función muestra un valor, run_in_transaction() muestra el valor al emisor.

Si la función genera una excepción, la transacción se revierte. Si la excepción es Rollback, no se vuelve a producir; cualquier otra excepción se vuelve a generar para el emisor.

Datastore utiliza un bloqueo optimista y vuelve a intentar las transacciones. Si la transacción preparada por la función no se puede confirmar, run_in_transaction() vuelve a llamar a la función y reintenta la transacción hasta 3 veces. (Para usar una cantidad diferente de reintentos, usa run_in_transaction_custom_retries()). Como la función de transacción puede llamarse más de una vez para una sola transacción, la función no debe tener efectos secundarios, lo que incluye modificaciones a los argumentos.

Si la transacción no se puede confirmar, por ejemplo, debido a una alta tasa de contención, se genera un TransactionFailedError.

from google.appengine.ext import db

class Counter(db.Model):
  name = db.StringProperty()
  count = db.IntegerProperty(default=0)

def decrement(key, amount=1):
  counter = db.get(key)
  counter.count -= amount
  if counter.count < 0:        # Don't let counter go negative
    raise db.Rollback()
  db.put(counter)

q = db.GqlQuery("SELECT * FROM Counter WHERE name = :1", "foo")
counter = q.get()
db.run_in_transaction(decrement, counter.key(), amount=5)

run_in_transaction_custom_retries (retries, function, *args, **kwargs)

Ejecuta una función que contiene actualizaciones de Datastore en una sola transacción, y reintenta la transacción una cantidad específica de veces en el caso de una contención. Si algún código genera una excepción durante la transacción, todas las actualizaciones realizadas en la transacción se revierten.

Además de la capacidad de especificar el número de reintentos, esta función se comporta de la misma manera que run_in_transaction().

Argumentos

retries: Cantidad máxima de veces para llamar a la función en caso de contención dentro del grupo de entidades (más de un usuario intenta modificar el grupo simultáneamente).
function: Función que se ejecutará
args: Argumentos posicionales para pasar a la función.
kwargs: Argumentos de palabra clave para pasar a la función.

run_in_transaction_options (options, function, *args, **kwargs)

Ejecuta una función que contiene actualizaciones de Datastore en un solo objeto de opciones de transacción. Si algún código genera una excepción durante la transacción, todas las actualizaciones de Datastore realizadas en la transacción se revierten.

Para las transacciones entre grupos (XG), el parámetro xg en el objeto de opciones de transacción debe establecerse en True.

Argumentos

options: El objeto de opciones de transacción que contiene la configuración que utiliza esta transacción. Para habilitar las transacciones XG, su parámetro xg debe establecerse en True.
function: Función que se ejecutará
args: Argumentos posicionales para pasar a la función.
kwargs: Argumentos de palabra clave para pasar a la función.

Si la función muestra un valor, run_in_transaction_options() muestra el valor al emisor.

Si la función genera una excepción, la transacción se revierte. Si la excepción es Rollback, no se vuelve a producir; cualquier otra excepción se vuelve a generar para el emisor.

Datastore utiliza un bloqueo optimista y vuelve a intentar las transacciones. Si no se puede confirmar la transacción preparada por la función, run_in_transaction_options() llama a la función nuevamente y reintenta la transacción hasta la cantidad de reintentos especificada en el objeto de opciones de transacción. Debido a que la función de transacción puede llamarse más de una vez para una sola transacción, la función no debe tener efectos secundarios, incluidas modificaciones a los argumentos.

Si la transacción no se puede confirmar, por ejemplo, debido a una alta tasa de contención, se genera un TransactionFailedError.

El siguiente ejemplo muestra cómo utilizar esta función para ejecutar una transacción de grupo cruzado:

from google.appengine.ext import db

xg_options = db.create_transaction_options(xg=True)

def my_txn():
  x = MyModel(a=3)
  x.put()
  y = MyModel(a=7)
  y.put()

db.run_in_transaction_options(xg_options, my_txn)

to_dict (model_instance, dictionary=None)

Crea y muestra una representación de diccionario de una instancia de modelo.

Argumentos

model_instance: Instancia de modelo que se copiará.
dictionary: Si está presente, el diccionario en el que se combinan los datos del modelo. Los valores del modelo reemplazan los valores en el diccionario; y se conservan las entradas del diccionario que no corresponden a los campos en la instancia del modelo.

Decoradores

@db.transactional (propagation=ALLOWED, xg=False, retries=3, deadline=60)

Hace que una función se ejecute dentro de una transacción db. Por lo tanto, en lugar de llamar a run_in_transaction(func), puedes llamar a func().

Argumentos

propagation

Qué hacer si se llama a esta función transaccional desde otra transacción:

ALLOWED: Si ya estás en una transacción, continúa usándola; de lo contrario, inicia una.
Nota: Si una función que utiliza esta política genera una excepción, probablemente no sea seguro detectar la excepción y confirmar la transacción externa; la función puede haber dejado la transacción externa en un estado incorrecto.
MANDATORY: Continúa en la transacción existente, si la hubiere; en caso contrario, genera una excepción BadRequestError
Nota: Si una función que utiliza esta política genera una excepción, probablemente no sea seguro detectar la excepción y confirmar la transacción externa; la función puede haber dejado la transacción externa en un estado incorrecto.
INDEPENDENT: Crea una nueva transacción, pausando cualquier transacción existente.
Nota: Una función que usa esta política no debe mostrar ninguna entidad leída en la nueva transacción, ya que las entidades no son consistentemente transaccionales con la transacción externa.
NESTED: (Aún no se admite) Crea una transacción anidada dentro de una existente.

xg

Si el valor es True, permite transacciones entre grupos (XG). Si se establece un valor no booleano, se genera una excepción BadArgumentError.

retries

Cantidad de reintentos que se realizan en caso de falla de confirmación de la transacción.

deadline

@db.non_transactional (allow_existing=True)

Garantiza que una función se ejecute fuera de una transacción db, incluso si se llama desde una transacción.

Argumento

allow_existing: Si es True, se permite que se llame a la función desde una transacción existente. Si es False, se genera una excepción BadRequestError.