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 beNone
. - 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 orNone
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. IfFalse
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 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
- Transaction options
Returns a
Future
. The future's result is whatever callback returns; or raises whatever callback raises or aTransactionFailedError
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
@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
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. Some transaction-related functions take transaction options; these include the context options but have some more options. 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 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
Option | 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. |
max_memcache_items | int
| Maximum batch size for the auto-batching feature of the
Context memcache methods.
For example, with the default size of max_memcache_items
(100), up to 100 memcache set operations will be combined into a
single set_multi operation.
|
For some transaction-related functions, the following transaction options are available (along with the inherited context options listed above) | ||
Option | Type | Description |
xg | bool
| Allow cross-group (XG ) transactions.
False by default.
|
propagation | int
| What to do if the code tries to start a transaction while already
in a transaction, ALLOWED by default.
(Except that for the function ndb.transaction() ,
NESTED is the default)
One of the
following values:
|
retries | int
| How many times to retry automatically in case of transaction failures. Zero means to try once but not re-try. |
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
).