English | Site Directory

Functions

The google.appengine.ext.db package provides the following functions:

get(keys)

Gets the entity or entities for the given key or keys, of any Model.

Arguments:

keys
A Key object or a list of Key objects.

If one Key is provided, the return value is an instance of the appropriate Model class, or None if no entity exists with the given Key. If a list of Keys is provided, the return value is a corresponding list of model instances, with None values when no entity exists for a corresponding Key.

See also Model.get().

put(models)

Puts one or more model instances into the datastore.

Arguments:

models
A model instance or a list of model instances to store.

If multiple model instances are given, all puts occur in one transaction. This requires that all of the entities in a single call be in the same entity group. See Keys and Entity Groups.

Returns the Key object (if one model instance is given) or a list of Key objects (if a list of instances is given) that correspond with the stored model instances.

delete(models)

Deletes one or more model instances from the datastore.

Arguments:

models
A model instance, a Key for an entity, or a list of model instances or keys of entities to delete.

If multiple keys or model instances are given, all delete()s occur in one transaction. This requires that all of the entities be in the same entity group. The multiple value syntax cannot be used with entities in different entity groups. See Keys and Entity Groups.

run_in_transaction(function, *args, **kwargs)

Runs a function containing datastore updates in a single transaction. If any code raises an exception during the transaction, all datastore updates made in the transaction are rolled back.

Arguments:

function
The function to run in a datastore transaction.
*args
Positional arguments to pass to the function.
**kwargs
Keyword arguments to pass to the function.

If the function returns a value, run_in_transaction() returns the value to the caller.

If the function raises an exception, the transaction is rolled back. If the function raises a Rollback exception, the exception is not re-raised. For any other exception, the exception is re-raised to the caller.

The datastore uses optimistic locking and retries for transactions. If the transaction prepared by the function cannot be committed, run_in_transaction() calls the function again, and repeats for a fixed number of retries. Because the transaction function may be called more than once for a single transaction, the function should not have side effects, including modifications to arguments.

If the transaction cannot be committed, such as due to a high rate of contention, a TransactionFailedError is raised.

For more information about transactions, see Transactions.

def decrement(key, amount=1):
  counter = db.get(key)
  counter.count -= amount
  if counter.count < 0:    # don't let the 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)