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
コンテキスト オプション

リストを返します。各リスト項目は、モデル インスタンスか 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)
関数がトランザクション外で実行されるようにするデコレータ。

引数

allow_existing
True(デフォルト)であり、かつ、装飾関数がトランザクション内のコードで呼び出される場合、その関数はトランザクションとは独立して実行されます。False であり、かつ、装飾関数がトランザクション内のコードで呼び出される場合、例外が発生します。
ndb.put_multi(entities, **ctx_options)
一連の Model インスタンスを保存します。

引数

entities
Model インスタンスのシーケンス
**ctx_options
コンテキスト オプション

保存されたキーでリストを返します。

ndb.put_multi_async(entities, **ctx_options)
Model インスタンスのシーケンスを非同期で保存します。

引数

entities
Model インスタンスのシーケンス
**ctx_options
コンテキスト オプション

Future オブジェクトのリストを返します。各 Future の結果は、保存されたキーです。

ndb.transaction(callback, **ctx_options)
トランザクション内でコールバックを実行します。

引数

callback
呼び出される関数 / タスクレット
**ctx_options
トランザクション オプション

callback が返したものを返します。トランザクションが失敗した場合は、callback で生成された例外がそのまま生成されるか、または TransactionFailedError 例外が生成されます。

コールバック関数に引数を渡すには、ラムダを使用します。次に例を示します。

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))
ndb.transaction_async(callback, **ctx_options)
トランザクション内で callback を非同期的に実行します。

引数

callback
呼び出される関数 / タスクレット
**ctx_options
トランザクション オプション

Future を返します。フューチャーは callback が返したものを返します。トランザクションが失敗した場合は、callback で生成された例外がそのまま生成されるか、または TransactionFailedError 例外が生成されます。

コールバック関数に引数を渡すには、ラムダを使用します。次に例を示します。

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))
@ndb.transactional
@ndb.transactional(**ctx_options)
関数をトランザクション内で自動的に実行させるデコレータ。

引数

このデコレータには、トランザクション オプションを含めることができます。

コンテキスト オプション、トランザクション オプション

コンテキスト オプションにより、異なる構成で特定のデータストア演算を実行できます。たとえば、個々のリクエストごとに読み取りポリシーや RPC 期限を変えたいことがあります。この設定を行うには、コンテキスト オプションを渡します。ほぼすべての演算に適用できます。一部のトランザクション関連関数ではトランザクション オプションを受け取るものがあります。これには、一連のコンテキスト オプションの先頭に追加のオプションがあります。

コンテキスト オプションを使った例をいくつか挙げます。エンティティ読み取り時の RPC 期限を 1 秒に設定するには、次の構文を使用します。

key.get(deadline=1)

エンティティの書き込み時の memcache タイムアウトを 30 秒に設定するには、次の構文を使用します。

ent.put(ndb_memcache_timeout=30)

キャッシュに保存された項目を削除し、そのリロードを強制するには、次の構文を使用します。

key.delete(use_datastore=False)

特殊なキーワード引数 options および config(時系列的な理由から同じ意味を持つ引数です)を使用すると、複数のオプションを構成オブジェクトとして指定できます。これは、ndb.ContextOptions オブジェクトまたは(トランザクション関数およびデコレータの場合は)ndb.TransactionOptions オブジェクトになります。たとえば、key.get(options=ndb.ContextOptions(use_cache=True))key.get(use_cache=True) と同じです。こうしたオプション オブジェクトに設定されたオプションは、キーワード パラメータによって上書きできます。

利用可能なコンテキスト オプションは次のとおりです。

オプション種類説明
deadline float データストア呼び出し期限です。秒数で指定します(デフォルトでは、呼び出しはリクエスト ハンドラ期限によってのみ、中断されます)。
read_policy ndb.EVENTUAL_CONSISTENCY これを ndb.EVENTUAL_CONSISTENCY に設定するのは、返されたすべての結果に Datastore が変更を適用するまで待たずに、必ずしも最新ではない結果をいち早く取得する場合です。
force_writes bool アプリが読み取り専用の場合でも、書き込みリクエストを続行するかどうかを指定します(これは、ユーザー制御の読み取り専用期間にのみ適用されます)。
use_cache bool エンティティをインプロセス キャッシュに保存するかどうかを指定します。この演算に関するインプロセス キャッシュ ポリシーをオーバーライドします。
use_memcache bool エンティティを memcache に保存するかどうかを指定します。この演算に関する memcache ポリシーをオーバーライドします。
use_datastore bool エンティティをデータストアに保存するかどうかを指定します。この演算に関するデータストア ポリシーをオーバーライドします。
memcache_timeout int memcache 内のエンティティの最大保存期間です。この演算に関する memcache タイムアウト ポリシーをオーバーライドします。
max_memcache_items int Context Memcache メソッドの自動バッチ機能の最大バッチサイズ。たとえば、デフォルトのバッチサイズ max_memcache_items(100)では、最大 100 の Memcache セット演算が単一の set_multi 演算に結合されます。

一部のトランザクション関連関数の場合、次のトランザクション オプションを使用できます(上記にリストされた固有のコンテキスト オプションのほかに)。

オプション種類説明
xg bool クロスグループ(XG)トランザクションを許可します。デフォルトは False です。
propagation int

NDB では「ネストされたトランザクション」と呼ばれる、トランザクション内のトランザクションに対して限定的なサポートを提供しています。

伝播パラメータは、コードがネストされたトランザクションの開始を試行した場合に発生する動作を制御します。

@ndb.transactional の伝播ポリシーのデフォルトは ALLOWED です。

ndb.transaction() の伝播ポリシーのデフォルトは NESTED です。NESTED ポリシーは NDB でサポートされておらず、コードは BadRequestError 例外をスローします。その場合、NDB はサポートされていないデフォルト値を設定し、プログラマがネストされたトランザクションの制限について明確に意識できるようにします。

伝播パラメータは次のいずれかの値が可能です。

ndb.TransactionOptions.NESTED
NESTED 伝播ポリシーは、外部ポリシーが commit したときに外部トランザクションと内部トランザクションのすべての変更を commit します。ただし、内部トランザクションで例外がスローされると、すべての変更が廃棄されますが、外部トランザクションは復元して続行することが可能です。NESTED ポリシーはサポートされていません。このポリシーを使用した場合は、コードで BadRequestError 例外がスローされます。
ndb.TransactionOptions.MANDATORY
常に既存のトランザクションを伝播します。既存のトランザクションがない場合は例外をスローします。このポリシーを使用する関数が例外をスローした場合、例外を取得して外部トランザクションを commit することは安全ではないことがあります。この関数によって、外部トランザクションが不適切な状態になっている可能性があります。
ndb.TransactionOptions.ALLOWED
既存のトランザクションが存在する場合に、伝播します。このポリシーを使用する関数が例外をスローした場合、例外を取得して外部トランザクションを commit することは安全ではないことがあります。この関数によって、外部トランザクションが不適切な状態になっている可能性があります。
ndb.TransactionOptions.INDEPENDENT
既存のトランザクションを「一時停止」して、常に新しいトランザクションを使用します。このポリシーを使用する関数では、新しいトランザクション内で読み取ったエンティティを返さないようにしてください。これは、新しいトランザクション内で読み取ったエンティティと呼び出し側のトランザクションとの間に一貫性がないためです。
retries int トランザクションが失敗した場合に再試行を自動で何回行うかを指定します。「0」に設定すると、1 回試行した後、それ以上再試行は行いません。

キャッシュ保存のため、オプションが無視されることがあります。たとえば、インコンテキスト キャッシュから満たされる読み取りオペレーションの RPC 期限を指定した場合、その期限は無視されます。一方、認識できないオプションでは TypeError が生成されます。

異なるオプションを設定した演算は、自動バッチの適用時にグループ化されます。たとえば、put_async() を使用し、deadline = 5 を指定して期限を指定せずに複数のエンティティを書き込んだ場合で、かつ、すべてのエンティティが自動バッチ適用の対象である場合は、たとえデフォルトの RPC 期限も 5 であった場合でも、自動バッチャーにより 2 つの別々の RPC 呼び出し(deadline = 5 を指定したグループ エンティティ用と、別のグループ用)が作成されます。これは、指定したオプションが RPC オペレーションとは無関係である場合(ndb_should_cache など)でも、当てはまります。