Python 2.7 ha llegado al final de su ciclo de vida y dejará de estar disponible el 31 de enero del 2026. Después de la retirada, no podrás desplegar aplicaciones de Python 2.7, aunque tu organización haya usado anteriormente una política de organización para volver a habilitar los despliegues de entornos de ejecución antiguos. Tus aplicaciones de Python 2.7 seguirán ejecutándose y recibiendo tráfico después de la fecha de retirada. Te recomendamos que migres a la versión compatible más reciente de Python.

Esta página se ha traducido con Cloud Translation API.

Funciones de Datastore

Nota: Se recomienda encarecidamente a los desarrolladores que creen aplicaciones nuevas que usen la biblioteca de cliente de NDB, que ofrece varias ventajas en comparación con esta biblioteca de cliente, como el almacenamiento automático en caché de entidades mediante la API Memcache. Si actualmente usas la biblioteca de cliente de DB anterior, consulta 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.

Functions

allocate_ids (model, count)

Asigna un lote de IDs en Datastore a una combinación de tipo y elemento superior de Datastore.

Los IDs asignados de esta forma no los usará el generador de secuencias de IDs automático de Datastore y se podrán usar en claves de entidad sin que haya conflictos.

Argumentos

model: La clave del modelo para el que se va a asignar un lote de IDs. Se trata de una clave normal, pero solo se necesitan el elemento superior y el tipo de clave para determinar qué secuencia de ID se debe usar.
count: Número de IDs que se van a asignar.

Devuelve una tupla de los primeros y últimos IDs que asigna. Por ejemplo, si asignas 10 IDs con esta función, obtendrás un valor devuelto en el formato (1, 10), no una lista completa de los IDs creados.

Ejemplo de asignación y 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 IDs en Datastore para una combinación de tipo y elemento superior de Datastore.

Esta función es idéntica a allocate_ids() excepto que devuelve un objeto asíncrono. Puedes llamar a get_result() en el valor devuelto para bloquear la llamada y devolver el resultado.

Argumentos

model: Una instancia de db.Model , key, o una cadena que sirva como plantilla para especificar la secuencia de IDs en la que se van a asignar los IDs. Los IDs devueltos solo se deben usar en entidades con el mismo elemento superior (si lo hay) y tipo que esta clave.
count: Número de IDs que se van a asignar.

Devuelve una tupla de los primeros y últimos IDs que asigna. Por ejemplo, si asignas 10 IDs con esta función, obtendrás un valor devuelto con el formato (1, 10), no una lista completa de los IDs creados.

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

Asigna un rango de ID con puntos finales específicos. Una vez que se hayan asignado estos IDs, podrá asignarlos manualmente a las entidades recién creadas.

El asignador automático de IDs de Datastore nunca asigna una clave que ya se haya asignado (ya sea mediante la asignación automática de IDs o mediante una llamada `allocate_ids` explícita). Por lo tanto, las entidades escritas en el intervalo de claves determinado nunca se sobrescribirán. Sin embargo, si escribes entidades con claves asignadas manualmente en este intervalo, es posible que se sobrescriban entidades ya existentes (o entidades nuevas escritas por otra solicitud), en función del estado del intervalo de claves devuelto.

Usa esta función solo si tienes un intervalo de IDs numéricos que quieras reservar (por ejemplo, para cargar en bloque entidades que ya tengan IDs). Si no te importa qué IDs recibes, usa allocate_ids().

Argumentos

model: Una instancia de db.Model , key, o una cadena que sirva como plantilla para especificar la secuencia de IDs en la que se van a asignar los IDs. Los IDs devueltos solo se deben usar en entidades con el mismo elemento superior (si lo hay) y tipo que esta clave.
start: El primer ID que se va a asignar, un número.
end: El último ID que se va a asignar, un número.

Devuelve uno de los siguientes valores: KEY_RANGE_EMPTY, KEY_RANGE_CONTENTION o KEY_RANGE_COLLISION. Si no es KEY_RANGE_EMPTY, significa que puede haber un problema al usar el intervalo 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. El objeto resultante se pasa como primer argumento a la función run_in_transaction_options().

Argumentos

propagación

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

PERMITIDO: Si ya estás en una transacción, sigue usándola. Si no, inicia una.
Nota: Si una función que usa esta política genera una excepción, probablemente no sea seguro capturar la excepción y confirmar la transacción externa, ya que es posible que la función haya dejado la transacción externa en un estado incorrecto.
OBLIGATORIO: Continúa con la transacción actual, si la hay. Si no, lanza una BadRequestError excepción.
Nota: Si una función que usa esta política genera una excepción, probablemente no sea seguro capturar la excepción y confirmar la transacción externa, ya que es posible que la función haya dejado la transacción externa en un estado incorrecto.
INDEPENDIENTE: Crea una transacción y pausa las que ya tengas.
Nota: Una función que use esta política no debe devolver ninguna entidad leída en la nueva transacción, ya que las entidades no son coherentes transaccionalmente con la transacción externa.
ANIDADO: (Aún no se admite) Crea una transacción anidada dentro de una transacción ya existente.

xg

Si True, permite transacciones entre grupos (XG). Genera una excepción BadArgumentError si se asigna un valor no booleano.

reintentos

Número de reintentos que se intentarán si falla la confirmación de la transacción.

deadline

Tiempo máximo, en segundos, que debe esperar Datastore para devolver un resultado antes de cancelar la operación con un error. Acepta un número entero o un valor de punto flotante. No se puede definir un valor superior al predeterminado (60 segundos), pero se puede reducir para asegurarse de que una operación concreta falle rápidamente (por ejemplo, para devolver una respuesta más rápida al usuario, volver a intentar la operación, probar otra operación o añadir la operación a una cola de tareas).

En el siguiente ejemplo se crean las opciones de una transacción entre grupos (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)

eliminar (modelos, fecha_límite=60)

Elimina una o varias instancias de modelo de Datastore.

Argumentos

modelos: Una instancia de modelo, una clave de entidad o una lista (u otro iterable) de instancias de modelo o claves de entidad que se van a eliminar.
deadline: Tiempo máximo, en segundos, que debe esperar Datastore para devolver un resultado antes de cancelar la operación con un error. Acepta un número entero o un valor de punto flotante. No se puede definir un valor superior al predeterminado (60 segundos), pero se puede reducir para asegurarse de que una operación concreta falle rápidamente (por ejemplo, para devolver una respuesta más rápida al usuario, volver a intentar la operación, probar otra operación o añadir la operación a una cola de tareas).

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

Siempre se producirá una excepción si se produce algún error durante la operación, aunque se hayan eliminado algunas de las entidades. Si la llamada se devuelve sin generar ninguna excepción, significa que todas las entidades se han eliminado correctamente.

Precaución: Si eliminas varias entidades en una sola operación, no se garantiza que las eliminaciones se lleven a cabo de forma atómica, a menos que la operación se realice dentro de una transacción. Otros procesos que consulten Datastore pueden ver resultados incoherentes incluso cuando la consulta se realiza con una coherencia sólida.

delete_async (models, deadline=60)

Elimina de forma asíncrona una o varias instancias de modelo de Datastore.

Esta función es idéntica a delete() excepto que devuelve un objeto asíncrono. Puedes llamar a get_result() en el valor devuelto para bloquear la llamada.

Argumentos

modelos: Una instancia de modelo, una clave de entidad o una lista (u otro iterable) de instancias de modelo o claves de entidad que se van a eliminar.
deadline: Tiempo máximo, en segundos, que debe esperar Datastore para devolver un resultado antes de cancelar la operación con un error. Acepta un número entero o un valor de punto flotante. No se puede definir un valor superior al predeterminado (60 segundos), pero se puede reducir para asegurarse de que una operación concreta falle rápidamente (por ejemplo, para devolver una respuesta más rápida al usuario, volver a intentar la operación, probar otra operación o añadir la operación a una cola de tareas).

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

Esta función devuelve un objeto que te permite bloquear el resultado de la llamada.

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

Obtiene las instancias de Model específicas con las claves proporcionadas de Datastore.

Argumentos

claves

Clave de la entidad que se va a recuperar, una representación de cadena de la clave o una lista de claves o sus representaciones de cadena.

read_policy

Lee la política que especifica el nivel de coherencia de datos que quieres:

STRONG_CONSISTENCY: Garantiza los resultados más recientes, pero solo se puede usar con un grupo de entidades.
EVENTUAL_CONSISTENCY: Puede abarcar varios grupos de entidades, pero puede devolver resultados obsoletos en ocasiones. Por lo general, las consultas de coherencia eventual se ejecutan más rápido que las de coherencia fuerte, pero no hay ninguna garantía.

Nota: Las consultas globales (no antecesoras) ignoran este argumento.

deadline

Si keys consta de una sola clave (o de su representación de cadena), esta función devuelve la instancia del modelo asociada a la clave si esta existe en el almacén de datos. De lo contrario, devuelve None. Si keys es una lista, el valor devuelto es una lista correspondiente de instancias de modelo, con valores None cuando no existe ninguna entidad para una clave determinada.

Consulta también Model.get().

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

Obtiene de forma asíncrona las instancias de modelo especificadas de Datastore.

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

Argumentos

claves

Clave de la entidad que se va a recuperar, una representación de cadena de la clave o una lista de claves o sus representaciones de cadena.

read_policy

Lee la política que especifica el nivel de coherencia de datos que quieres:

STRONG_CONSISTENCY: Garantiza los resultados más recientes, pero solo se puede usar con un grupo de entidades.
EVENTUAL_CONSISTENCY: Puede abarcar varios grupos de entidades, pero puede devolver resultados obsoletos en ocasiones. Por lo general, las consultas de coherencia eventual se ejecutan más rápido que las de coherencia fuerte, pero no hay ninguna garantía.

Nota: Las consultas globales (no antecesoras) ignoran este argumento.

deadline

Consulta también Model.get().

get_indexes ()

Devuelve una lista de índices compuestos que pertenecen a la aplicación que llama.

En el siguiente ejemplo se muestra 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 ()

Devuelve de forma asíncrona una lista de índices compuestos que pertenecen a la aplicación que llama.

is_in_transaction ()

Devuelve un valor booleano que indica si el ámbito actual se está ejecutando en una transacción.

model_to_protobuf (model_instance)

Crea la serialización del búfer de protocolo de una instancia de Model. Un búfer de protocolo es el formato de serialización de Google que se usa para las llamadas a procedimientos remotos y puede ser útil para serializar objetos de Datastore con fines de copia de seguridad y restauración.

Precaución: Esta función usa un formato diferente (más antiguo) para los búferes de protocolo que el formato de búfer de protocolo de código abierto y 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 va a serializar.

Devuelve la serialización del búfer de protocolo del objeto como una cadena 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 del búfer de protocolo, tal como la devuelve model_to_protobuf().

Devuelve un objeto de la clase del tipo correspondiente. Si la clase kind no existe, se 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 igual que cualquier otra instancia de Model, por ejemplo, llamando a su método put(). El objeto conserva la clave que tenía cuando se creó el búfer de protocolo. Si ya existe un objeto con esa clave en Datastore, al guardar el objeto deserializado se sobrescribirá el objeto existente.

Precaución: Si la clave del objeto usa un ID asignado por el sistema y ese ID aún no se ha asignado a la ruta y al tipo especificados, la operación de guardado se realizará correctamente, pero el ID no se reservará. Se le puede asignar ese ID a un objeto creado en el futuro, lo que sobrescribiría el objeto anterior. Por seguridad, restaura los objetos solo en la misma aplicación en la que estaban cuando se serializaron.

model_is_projection (model_instance)

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

Argumento

model_instance: La consulta que estás comprobando para determinar si es una consulta de proyección.

Devuelve True si la consulta es una consulta de proyección y False si no lo es.

put (models, deadline=60)

Escribe una o varias instancias de modelo en Datastore.

Argumentos

modelos: Una instancia de modelo o una lista de instancias de modelo que se va a almacenar.
deadline: Tiempo máximo, en segundos, que debe esperar Datastore para devolver un resultado antes de cancelar la operación con un error. Acepta un número entero o un valor de punto flotante. No se puede definir un valor superior al predeterminado (60 segundos), pero se puede reducir para asegurarse de que una operación concreta falle rápidamente (por ejemplo, para devolver una respuesta más rápida al usuario, volver a intentar la operación, probar otra operación o añadir la operación a una cola de tareas).

Si se proporcionan varias instancias de modelo, pueden estar en más de un grupo de entidades.

Siempre se producirá una excepción si se produce algún error durante la operación, aunque se hayan escrito algunas de las entidades. Si la llamada se devuelve sin generar ninguna excepción, significa que todas las entidades se han escrito correctamente.

Si models consta de una sola instancia de modelo, esta función devuelve el objeto Key correspondiente. Si models es una lista, el valor devuelto es una lista de objetos Key correspondientes.

Precaución: Si escribes varias entidades en una sola operación, no se garantiza que las escrituras se realicen de forma atómica, a menos que la operación se lleve a cabo en una transacción. Otros procesos que consulten Datastore pueden ver resultados incoherentes incluso cuando la consulta se realiza con una coherencia sólida.

put_async (models, deadline=60)

Escribe una o varias instancias de modelo en Datastore.

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

Argumentos

modelos: Una instancia de modelo o una lista de instancias de modelo que se va a almacenar.
deadline: Tiempo máximo, en segundos, que debe esperar Datastore para devolver un resultado antes de cancelar la operación con un error. Acepta un número entero o un valor de punto flotante. No se puede definir un valor superior al predeterminado (60 segundos), pero se puede reducir para asegurarse de que una operación concreta falle rápidamente (por ejemplo, para devolver una respuesta más rápida al usuario, volver a intentar la operación, probar otra operación o añadir la operación a una cola de tareas).

Si se proporcionan varias instancias de modelo, pueden estar en más de un grupo de entidades.

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

query_descendants (model_instance)

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

Argumento

model_instance: La instancia del 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, se deshacen todas las actualizaciones realizadas en la transacción. También puedes usar el decorador @db.transactional().

Argumentos

function: Función que se va a ejecutar.
args: Argumentos posicionales que se transfieren a la función.
kwargs: Argumentos de palabras clave que se transfieren a la función.

Si la función devuelve un valor, run_in_transaction() devuelve el valor a la persona que ha llamado.

Si la función genera una excepción, se deshace la transacción. Si la excepción es una excepción Rollback, no se vuelve a generar. Cualquier otra excepción se vuelve a generar para el llamador.

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

Si no se puede confirmar la transacción (por ejemplo, debido a una alta tasa de contención), se genera una excepción 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 única transacción y vuelve a intentar la transacción un número de veces especificado en caso de conflicto. Si algún código genera una excepción durante la transacción, se deshacen todas las actualizaciones realizadas en la transacción.

Aparte de la posibilidad de especificar el número de reintentos, esta función se comporta de forma idéntica a run_in_transaction().

Argumentos

reintentos: Número máximo de veces que se llamará a la función en caso de conflicto en el grupo de entidades (más de un usuario intenta modificar el grupo simultáneamente).
function: Función que se va a ejecutar.
args: Argumentos posicionales que se transfieren a la función.
kwargs: Argumentos de palabras clave que se transfieren a la función.

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

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

En el caso de las transacciones entre grupos (XG), el parámetro xg del objeto de opciones de transacción debe tener el valor True.

Argumentos

opciones: Objeto de opciones de transacción que contiene los ajustes utilizados por esta transacción. Para habilitar las transacciones XG, su parámetro xg debe tener el valor True.
function: Función que se va a ejecutar.
args: Argumentos posicionales que se transfieren a la función.
kwargs: Argumentos de palabras clave que se transfieren a la función.

Si la función devuelve un valor, run_in_transaction_options() devuelve el valor a el llamador.

Datastore usa el bloqueo optimista y reintentos para las transacciones. Si no se puede confirmar la transacción preparada por la función, run_in_transaction_options() vuelve a llamar a la función y reintenta la transacción hasta el número de reintentos especificado en el objeto de opciones de la transacción. Como la función de transacción se puede llamar más de una vez para una sola transacción, la función no debe tener efectos secundarios, incluidas las modificaciones en los argumentos.

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

En el siguiente ejemplo se muestra cómo usar esta función para ejecutar una transacción entre grupos:

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 devuelve una representación de diccionario de una instancia de modelo.

Argumentos

model_instance: Instancia del modelo que se va a copiar.
diccionario: Si está presente, diccionario en el que se combinarán los datos del modelo. Los valores del modelo sobrescriben los valores del diccionario. Las entradas del diccionario que no se correspondan con los campos de la instancia del modelo se conservan.

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

propagación

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

PERMITIDO: Si ya estás en una transacción, sigue usándola. Si no, inicia una.
Nota: Si una función que usa esta política genera una excepción, probablemente no sea seguro capturar la excepción y confirmar la transacción externa, ya que es posible que la función haya dejado la transacción externa en un estado incorrecto.
OBLIGATORIO: Continúa con la transacción actual, si la hay. Si no, lanza una BadRequestError excepción.
Nota: Si una función que usa esta política genera una excepción, probablemente no sea seguro capturar la excepción y confirmar la transacción externa, ya que es posible que la función haya dejado la transacción externa en un estado incorrecto.
INDEPENDIENTE: Crea una transacción y pausa las que ya tengas.
Nota: Una función que use esta política no debe devolver ninguna entidad leída en la nueva transacción, ya que las entidades no son coherentes transaccionalmente con la transacción externa.
ANIDADO: (Aún no se admite) Crea una transacción anidada dentro de una transacción ya existente.

xg

Si True, permite transacciones entre grupos (XG). Genera una excepción BadArgumentError si se asigna un valor no booleano.

reintentos

Número de reintentos que se intentarán si falla la confirmación de la transacción.

deadline

@db.non_transactional (allow_existing=True)

Asegura que una función se ejecute fuera de una transacción de db, aunque se llame desde dentro de una transacción.

Argumento

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

Funciones de Datastore Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Functions

Decoradores

Funciones de Datastore