NDB 函数

函数

ndb.add_flow_exception(exc)
指定某个异常不应被记录,而只是正常程序流的一部分。(通常情况下,如果引发异常,系统会将警告消息写入应用的日志中。)

参数

exc
不应记录的异常类。

默认情况下,不会记录以下异常:

  • webob.exc.HTTPException(及其子类)
  • ndb.Rollback
ndb.delete_multi(keys, **ctx_options)
删除由传递的键序列标识的实体。

参数

keys
序列
**ctx_options
上下文选项
ndb.delete_multi_async(keys, **ctx_options)
异步删除由传递的键序列标识的实体。

参数

keys
序列
**ctx_options
上下文选项

返回 Future 对象的列表。每个 future 的结果都将是 None

ndb.get_multi(keys, **ctx_options)
提取由传递的键序列标识的实体。

参数

keys
序列
**ctx_options
上下文选项

返回一个列表。每个列表项要么是 Model 实例,要么是 None(如果未找到键)。

ndb.get_multi_async(keys, **ctx_options)
异步提取由传递的键序列标识的实体。

参数

keys
序列
**ctx_options
上下文选项

返回 Future 对象的列表。每个 future 的结果要么是 Model 实例,要么是 None(如果未找到键)。

ndb.in_transaction()
返回布尔值,指出事务当前是否处于活跃状态。
@ndb.non_transactional
@ndb.non_transactional
使用修饰器以确保函数在事务外运行。

参数:

allow_existing
如果为 True(默认值)并且事务中的代码调用修饰函数,则该函数独立于事务运行。如果为 False 并且事务中的代码调用修饰函数,则会引发异常。
ndb.put_multi(entities, **ctx_options)
存储一系列 Model 实例。

参数

实体
Model 实例序列
**ctx_options
上下文选项

返回包含已存储的的列表。

ndb.put_multi_async(entities, **ctx_options)
异步存储一系列 Model 实例。

参数

实体
Model 实例序列
**ctx_options
上下文选项

返回 Future 对象的列表。每个 future 的结果都将是存储的

ndb.transaction(callback, **ctx_options)
在事务中运行回调。

参数

callback
要调用的函数或 tasklet
**ctx_options
事务选项

返回回调返回的任何结果。 抛出回调抛出的任何结果;如果事务失败,则抛出 TransactionFailedError 异常。

要将参数传递给回调函数,请使用 lambda。例如,

def my_callback(key, inc):
  ...

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

ndb.transaction_async(callback, **ctx_options)
在事务中异步运行回调。

参数

callback
要调用的函数或 tasklet
**ctx_options
事务选项

返回 Future。 此 future 返回回调返回的任何结果;或者抛出回调抛出的任何结果;如果事务失败,则抛出 TransactionFailedError

要将参数传递给回调函数,请使用 lambda。例如,

def my_callback(key, inc):
  ...

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

@ndb.transactional
@ndb.transactional
使用修饰器使函数自动在事务中运行。

参数:

此修饰器可以包含事务选项

上下文选项、事务选项

上下文选项允许您使用不同的配置运行特定的数据存储区操作。例如,您可能想要针对各个请求更改读取政策或 RPC 截止时间。 您几乎可以将上下文选项传递给任何操作,并可借此实现上述目的。 某些事务相关函数会采用事务选项,其中,除一组上下文选项外,还包含其他选项。

以下是使用上下文选项的几个示例。要将读取实体时的 RPC 截止时间设置为 1 秒,可以使用以下方法:

key.get(deadline=1)

要将写入实体时的 Memcache 超时设置为 30 秒,可以使用以下方法:

ent.put(ndb_memcache_timeout=30)

要删除已缓存的项目并强制重新加载该项目,可以使用以下方法:

key.delete(use_datastore=False)

特殊关键字参数 optionsconfig(由于历史原因具有相同的含义)允许将多个选项指定为 Configuration 对象。这可以是 ndb.ContextOptions 对象或(对于事务函数和装饰器)ndb.TransactionOptions 对象。 例如,key.get(options=ndb.ContextOptions(use_cache=True)) 等同于 key.get(use_cache=True)。在此类选项对象中设置的选项可能会被关键字参数所覆盖。

可以使用以下上下文选项

选项类型说明
deadline float Datastore 调用截止时间,指定为几秒。 (默认情况下,只有请求处理程序截止时间会导致调用中断。)
read_policy ndb.EVENTUAL_CONSISTENCY 如果将其设置为 ndb.EVENTUAL_CONSISTENCY,则不会等待 Datastore 对返回的所有结果应用更改,而会更快地获得可能不是最新的结果。
force_writes bool 指定写入请求是否应该成功(即使当应用处于只读模式时)。 (这仅适用于用户控制的只读周期。)
use_cache bool 指定是否在进程内缓存中存储实体;覆盖此操作的进程内缓存政策。
use_memcache bool 指定是否在 Memcache 中存储实体;覆盖此操作的 Memcache 政策。
use_datastore bool 指定是否在 Datastore 中存储实体;覆盖此操作的 Datastore 政策。
memcache_timeout int 实体在 Memcache 中的最长有效期;覆盖此操作的 Memcache 超时政策。
max_memcache_items int Context Memcache 方法的自动批处理功能的最大批量大小。 例如,如果使用 max_memcache_items 的默认大小 100,则最多可将 100 个 Memcache Set 操作组合成单个 set_multi 操作。

对于某些事务相关函数,可以使用以下事务选项(以及上面列出的继承上下文选项):

选项类型说明
xg bool 允许跨组 (XG) 事务。 默认为 False
propagation int

NDB 为事务内的事务(称为“嵌套事务”)提供有限支持。

propagation 参数可控制在代码尝试启动嵌套事务时发生的情况。

@ndb.transactional 的传播政策默认为 ALLOWED

ndb.transaction() 的传播政策默认为 NESTED。 NDB 不支持 NESTED 政策,因此代码将抛出 BadRequestError 异常。在本例中,NDB 设置了不受支持的默认值,以便程序员明确了解嵌套事务的限制。

propagation 参数可以是以下值之一:

ndb.TransactionOptions.NESTED
提交外部政策时,NESTED 传播政策将提交外部和内部事务中的所有更改。不过,如果在内部事务中抛出异常,那么所有更改都将被抛出,但允许选择性地恢复并继续外部事务。不支持 NESTED 政策。如果您使用此政策,您的代码将抛出 BadRequestError 异常。
ndb.TransactionOptions.MANDATORY
始终传播现有事务;如果没有现有事务,则抛出异常。如果使用此政策的函数抛出异常,则捕获异常并提交外部事务可能不安全;该函数可能会使外部事务处于错误状态。
ndb.TransactionOptions.ALLOWED
如果存在现有事务,则传播该事务。 如果使用此政策的函数抛出异常,则捕获异常并提交外部事务可能不安全;该函数可能会使外部事务处于错误状态。
ndb.TransactionOptions.INDEPENDENT
始终使用新事务,“暂停”所有现有事务。 使用此政策的函数不应返回在新事务中读取的任何实体,因为这些实体在事务方面与调用者的事务不一致。
retries int 事务失败时自动重试的次数。 零表示尝试一次,但不会重试。

在某些情况下,选项会因缓存而被忽略。 例如,如果某项读取操作能够从上下文缓存中被满足,那么当您为该读取操作指定 RPC 截止时间时,该截止时间将会被忽略。 另一方面,无法识别的选项会导致引发 TypeError

应用自动批处理时,系统会将具有不同选项的操作组合在一起。例如,如果您使用 put_async() 写入一些具有 deadline = 5 的实体和一些未指定截止时间的实体,并且所有实体都符合自动批处理条件,那么自动批处理程序将执行两个单独的 RPC 调用(一个调用针对具有 deadline = 5 的实体组,另一个调用针对另一个实体组),即便默认的 RPC 截止时间也是 5,仍然如此!这同样适用于指定选项与 RPC 操作不相关的情况(例如 ndb_should_cache)。