Functions

ndb.add_flow_exception ( exc )

Specify that an exception should not be logged, but is just part of normal program flow. (Normally, raising an exception writes a warning message to the application's logs.)

Arguments

exc

Exception class that should not be logged.

By default, the following exceptions are not logged:

• webob.exc.HTTPException (and its subclasses)
• ndb.Rollback

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.non_transactional
@ndb.non_transactional( allow_existing =True)

Decorator to ensure that a function runs outside a transaction.

Arguments:

allow_existing

If True (the default) and if the decorated function is called by code in a transaction, the function runs independent of the transaction. If False and if the decorated function is called by code in a transaction, it raises an exception.

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

Transaction options

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

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

Transaction options

Returns a Future . The future returns whatever callback returns, or raises whatever callback raises or a TransactionFailedError if the transaction fails.

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
@ndb.transactional(**ctx_options)

Decorator to make a function automatically run in a transaction.

Arguments:

This decorator can have transaction options .

Context Options, Transaction Options

Context options allow you to run specific datastore operations with different configurations. 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. Some transaction-related functions take transaction options , which include additional options on top of a set of context options.

Here are a few examples using context options. To set the RPC deadline to 1 second when reading an entity, you can use:

key.get(deadline=1)

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

ent.put(ndb_memcache_timeout=30)

To delete an item that has been cached and force its reload, you can use:

key.delete(use_datastore=False)

The special keyword arguments options and config (which have identical meanings for historical reasons) allow one to specify several options as a Configuration object. This can be an ndb.ContextOptions object or (for the transactional functions and decorator) an ndb.TransactionOptions object. For example, key.get(options=ndb.ContextOptions(use_cache=True)) is equivalent to key.get(use_cache=True) . The options set in such an options object can be overridden by keyword parameters.

The following context options are available:

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 ).

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .