Skip to page content Skip to main navigation
English | Site Directory

e.g. "templates" or "datastore"

# 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, retrying the transaction up to 3 times. (To use a different number of retries, use db.run_in_transaction_custom_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)

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

  Runs a function containing datastore updates in a single transaction, retrying the transaction the given number of times in the event of contention. If any code raises an exception during the transaction, all datastore updates made in the transaction are rolled back.

  Arguments:

  retries
    The maximum number of times to call the transaction function in the event of contention in the entity group (more than one user attempting to modify the group simultaneously).
  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.

  Other than the ability to specify the number of retries, this function behaves identically to db.run_in_transaction().