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, they may be in more than one entity group. Within each entity group, all entities belonging to that group will be written in a single transaction. See Keys and Entity Groups.

An exception will always be raised if any error occurs during the operation, even if some of the entities actually were written. This may happen if the entities in the call span multiple entity groups. If the call returns without raising an exception, then all of the entities were written successfully.

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.

As with Model.put(), if multiple keys are given, they may be in more than one entity group. Within each entity group, all entities belonging to that group will be deleted in a single transaction. See Keys and Entity Groups.

An exception will always be raised if any error occurs during the operation, even if some of the entities actually were deleted. This may happen if the keys in the call span multiple entity groups. If the call returns without raising an exception, then all of the entities were deleted successfully.

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)