English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# NDB Functions

#### Experimental!

NDB is an experimental, innovative, and rapidly changing new feature for App Engine. Unfortunately, being on the bleeding edge means that we may make backwards-incompatible changes to NDB. We will inform the community when this feature is no longer experimental.

## Functions

ndb.delete_multi(keys, **ctx_options)
  Deletes entities identified by the passed sequence of keys.

  Arguments

  keys
    Sequence of keys
  **ctx_options
    Context options
ndb.delete_multi_async(keys, **ctx_options)
  Asynchronously deletes entities identified by the passed sequence of keys.

  Arguments

  keys
    Sequence of keys
  **ctx_options
    Context options

  Returns a list of `Future` objects. Each future's result will be `None`.

ndb.get_multi(keys, **ctx_options)
  Fetches entities identified by the passed sequence of keys.

  Arguments

  keys
    Sequence of keys
  **ctx_options
    Context options

  Returns a list. Each list item is either a Model instance or `None` if the key wasn't found.

ndb.get_multi_async(keys, **ctx_options)
  Asynchronously fetches entities identified by the passed sequence of keys.

  Arguments

  keys
    Sequence of keys
  **ctx_options
    Context options

  Returns a list of `Future` objects. Each future's result is a Model instance or `None` if the key wasn't found.

ndb.in_transaction()
  Returns a Boolean indicating whether a transaction is currently active.
ndb.put_multi(entities, **ctx_options)
  Stores a sequence of Model instances.

  Arguments

  entities
    Sequence of Model instances
  **ctx_options
    Context options

  Returns a list with the stored keys.

ndb.put_multi_async(entities, **ctx_options)
  Asynchronously stores a sequence of Model instances.

  Arguments

  entities
    Sequence of Model instances
  **ctx_options
    Context options

  Returns a list of `Future` objects. Each future's result will be a stored key.

ndb.transaction(callback, **ctx_options)
  Run a callback in a transaction.

  Arguments

  callback
    Function or tasklet to be called
  **ctx_options
    Context options

  Returns whatever callback returns. Raises whatever callback raises or a `TransactionFailedError` exception if the transaction failed.

  To pass arguments to a callback function, use a lambda. For example,

      def my_callback(key, inc):
        ...

      transaction(lambda: my_callback(Key(...), 1))

ndb.transaction_async(callback, **ctx_options)
  Asynchronously run a callback in a transaction.

  Arguments

  callback
    Function or tasklet to be called
  **ctx_options
    Context options

  Returns a `Future`. The future's result is whatever callback returns; or raises whatever callback raises or a `TransactionFailedError` if the transaction failed.

  To pass arguments to a callback function, use a lambda. For example,

      def my_callback(key, inc):
        ...

      transaction(lambda: my_callback(Key(...), 1))

@ndb.transactional
  Decorator to make a function automatically run in a transaction. If already in a transaction, this is a no-op.

  Note: Note: If you need to override the retry count, or want some kind of async behavior, or pass Context options, use the transaction() function instead.

## Context Options

Sometimes you want a specific operation to use a different configuration: for example, you might want to vary the read policy or the RPC deadline for individual requests. You can do this by passing context options to almost any operation. For example, to set the RPC deadline to 1 second when reading an entity, you can use

    key.get(deadline=1)

or to set the memcache timeout to 30 seconds when writing an entity, you can use

    ent.put(ndb_memcache_timeout=30)

The following context options are available

Method | Type | Description
--- | --- | ---
`deadline` | `float` | Datastore call deadline, specified as a number of seconds. (By default, the call is only interrupted by the request handler deadline.)
`read_policy` | `ndb.EVENTUAL_CONSISTENCY` | Set this to `ndb.EVENTUAL_CONSISTENCY` if, instead of waiting for the Datastore to finish applying changes to all returned results, you wish to get possibly-not-current results faster.
`force_writes` | `bool` | If a write request should succeed even if the app is read-only. (This only applies to user controlled read-only periods.)
`use_cache` | `bool` | Specifies whether to store entities in in-process cache; overrides in-process cache policy for this operation.
`use_memcache` | `bool` | Specifies whether to store entities in memcache; overrides memcache policy for this operation.
`use_datastore` | `bool` | Specifies whether to store entities in Datastore; overrides Datastore policy for this operation.
`memcache_timeout` | `int` | Maximum lifetime for entities in memcache; overrides memcache timeout policy for this operation.

In some cases, options are ignored because of caching. For example, if you specify an RPC deadline for a read operation that is satisfied from the in-context cache, the deadline is ignored. On the other hand, unrecognized options cause `TypeError` to be raised.

Operations with different options are grouped together when auto-batching applies. For example, if you use `put_async()` to write some entities with `deadline = 5` and some without specifying a deadline, and all are eligible for auto-batching, the auto-batcher will make two separate RPC calls—one for the group of entities with `deadline = 5` and one for the other group—even though the default RPC deadline is also 5! This applies even if the option specified is irrelevant to the RPC operation (for example, `ndb_should_cache`).