注: Python 2.7 は、2024 年 1 月 31 日にサポートが終了しました。既存の Python 2.7 アプリケーションは引き続き実行され、トラフィックを受信します。ただし、サポート終了日を過ぎると、ランタイムを使用するアプリケーションの再デプロイが App Engine によってブロックされることがあります。サポートされている最新バージョンの Python に移行することをおすすめします。

データストア関数

注: 新しいアプリケーションを作成する際は、NDB クライアントライブラリを使用することを強くおすすめします。NDB クライアントライブラリには、Memcache API によるエンティティの自動キャッシュをはじめ、このクライアントライブラリにはないメリットがあります。古い DB クライアントライブラリを現在使用している場合は、DB から NDB への移行ガイドをお読みください。

このページで説明する関数は、google.appengine.ext.db パッケージで定義されています。

関数

allocate_ids (model, count)

Datastore の種類と親の組み合わせに、Datastore の ID バッチを割り当てます。

この方法で割り当てられた ID は、Datastore の自動 ID シーケンス生成ツールで使用されませんが、エンティティキーで競合の心配をせず使用できます。

引数

model: ID バッチを割り当てるモデルキー。これは通常のキーですが、使用する ID シーケンスを特定するにはキーの親と種類が必要になります。
count: 割り当てる ID の数。

割り当てられる最初の ID と最後の ID のタプルを返します。たとえば、この関数を使用して 10 個の ID を割り当てると、（1, 10）の形式で値が返されます。作成された ID の完全なリストが返されるわけではありません。

ID の割り当てと使用例:

# allocate for MyModel without an instance
handmade_key = db.Key.from_path('MyModel', 1)
first_batch = db.allocate_ids(handmade_key, 10)
first_range = range(first_batch[0], first_batch[1] + 1)

# or allocate using an existing key
model_instance = MyModel.all().get()
second_batch = db.allocate_ids(model_instance.key(), 10)
second_range = range(second_batch[0], second_batch[1] + 1)

# and then use them! woo!
my_id = second_range.pop(0)
new_key = db.Key.from_path('MyModel', my_id)
new_instance = MyModel(key=new_key)
new_instance.put()
assert new_instance.key().id() == my_id

# the Datastore will not assign ids in first_batch or second_batch
another_instance = MyModel()
another_instance.put()
assert another_instance.key().id() not in first_range
assert another_instance.key().id() not in second_range

allocate_ids_async (model, count)

Datastore の種類と親の組み合わせに、Datastore の ID バッチを非同期で割り当てます。

この関数は、非同期オブジェクトを返す点を除き、allocate_ids() と同じです。get_result() を呼び出すと、戻り値に応じて呼び出しをブロックし、結果を返すことができます。

引数

model: ID シーケンスを指定し、ID を割り当てるテンプレートとして機能する db.Model インスタンス、キーまたは文字列。返された ID は、このキーと親が同じであり（存在する場合）、同じ種類のエンティティで使用する必要があります。
count: 割り当てる ID の数。

allocate_id_range (model, start, end, **kwargs)

特定のエンドポイントの ID の範囲を割り当てます。これらの ID が割り当てられると、新しく作成したエンティティに ID を手動で割り当てることができます。

Datastore の自動 ID 割り当てツールは、ID の自動割り当てまたは明示的な `allocate_ids` 呼び出しで割り当て済みのキーを割り当てません。このため、特定のキー範囲に書き込まれたエンティティが上書きされることはありません。ただし、この範囲に手動で割り当てたキーのエンティティを作成すると、返されたキー範囲の状態によっては、既存のエンティティ（あるいは、別のリクエストで作成された新しいエンティティ）が上書きされる場合があります。

この関数は、予約する数値 ID 範囲が存在する場合にだけ利用してください（たとえば、ID のあるエンティティを一括で読み込む場合など）。受け取る ID を確認する必要がない場合には、代わりに allocate_ids() を使用します。

引数

model: ID シーケンスを指定し、ID を割り当てるテンプレートとして機能する db.Model インスタンス、キーまたは文字列。返された ID は、このキーと親が同じであり（存在する場合）、同じ種類のエンティティで使用する必要があります。
start: 最初に割り当てる ID。数値です。
end: 最後に割り当てる ID。数値です。

（KEY_RANGE_EMPTY、KEY_RANGE_CONTENTION、KEY_RANGE_COLLISION）のいずれかを返します。KEY_RANGE_EMPTY でない場合、割り当てられたキー範囲の使用で問題が発生している可能性があります。

create_transaction_options (**kwargs)

トランザクション実行を制御するためのトランザクションオプションオブジェクト（クラス TransactionOptions）を作成します。返されたオブジェクトは run_in_transaction_options() 関数の最初の引数として渡します。

引数

propagation

このトランザクション関数が別のトランザクション内から呼び出された場合の処理内容:

ALLOWED: すでにトランザクション中の場合は、そのトランザクションを引き続き使用します。それ以外の場合は、トランザクションを開始します。
注: このポリシーを使用する関数が例外をスローした場合、例外をキャッチして外側のトランザクションを commit することは安全ではありません。関数によって外側のトランザクションが不適切な状態に置かれている可能性があります。
MANDATORY: 既存のトランザクション内で続行します（該当する場合）。それ以外の場合は、BadRequestError 例外が発生します。
注: このポリシーを使用する関数が例外をスローした場合、例外をキャッチして外側のトランザクションを commit することは安全ではありません。関数によって外側のトランザクションが不適切な状態に置かれている可能性があります。
INDEPENDENT: 既存のトランザクションを一時停止して、新しいトランザクションを作成します。
注: このポリシーを使用する関数では、新しいトランザクション内で読み取ったエンティティを返さないようにしてください。これは、新しいトランザクション内で読み取ったエンティティと、外側のトランザクションとの間に、トランザクションの一貫性がないためです。
NESTED: （現時点ではサポートされていません）既存のトランザクション内に、ネストされたトランザクションを作成します。

xg

True の場合、クロスグループ（XG）トランザクションを許可します。ブール値以外を設定すると、BadArgumentError 例外が発生します。

retries

トランザクションの commit が失敗した場合に再試行する回数。

deadline

Datastore から結果が返されるのを待機する時間の最大値（秒）。この時間を過ぎると処理を中止し、エラーを返します。整数値または浮動小数点値のいずれかを指定できます。デフォルト値（60 秒）を超える値は設定できませんが、デフォルトより短い値に設定することは可能です。これにより、特定のオペレーションが失敗と判定されるまでの時間を短くすることができます（ユーザーへのレスポンスの迅速化、オペレーションの再試行、別のオペレーションの試行、タスクキューへのオペレーションの追加などの目的に利用できます）。

以下の例では、後続のクロスグループ（XG）トランザクションのオプションを作成します。

from google.appengine.ext import db

xg_on = db.create_transaction_options(xg=True)

def my_txn():
  x = MyModel(a=3)
  x.put()
  y = MyModel(a=7)
  y.put()

db.run_in_transaction_options(xg_on, my_txn)

delete (models, deadline=60)

Datastore から 1 つ以上のモデルインスタンスを削除します。

引数

models: モデルインスタンス、モデルインスタンスのエンティティキー / リスト（他のイテラブル）または削除するエンティティキー。
deadline: Datastore から結果が返されるのを待機する時間の最大値（秒）。この時間を過ぎると処理を中止し、エラーを返します。整数値または浮動小数点値のいずれかを指定できます。デフォルト値（60 秒）を超える値は設定できませんが、デフォルトより短い値に設定することは可能です。これにより、特定のオペレーションが失敗と判定されるまでの時間を短くすることができます（ユーザーへのレスポンスの迅速化、オペレーションの再試行、別のオペレーションの試行、タスクキューへのオペレーションの追加などの目的に利用できます）。

put() と同様に、複数のキーが指定する場合、それらのキーは複数のエンティティグループ内にあってもかまいません。

オペレーション中にエラーが発生すると、エンティティの一部が削除されていても例外が発生します。例外が発生せずに呼び出しが完了した場合、すべてのエンティティが正常に削除されています。

注意: オペレーションがトランザクション内で実行されない限り、1 回のオペレーションで複数のエンティティを削除してもアトミックに削除されるとは限りません。クエリを強整合性で実行しても、Datastore にクエリを送信する他のプロセスで矛盾する結果が生成される可能性があります。

delete_async (models, deadline=60)

Datastore から 1 つ以上のモデルインスタンスを非同期で削除します。

この関数は、非同期オブジェクトを返す点を除き、delete() と同じです。get_result() を呼び出すと、戻り値に応じて呼び出しをブロックできます。

引数

models: モデルインスタンス、モデルインスタンスのエンティティキー / リスト（他のイテラブル）または削除するエンティティキー。
deadline: Datastore から結果が返されるのを待機する時間の最大値（秒）。この時間を過ぎると処理を中止し、エラーを返します。整数値または浮動小数点値のいずれかを指定できます。デフォルト値（60 秒）を超える値は設定できませんが、デフォルトより短い値に設定することは可能です。これにより、特定のオペレーションが失敗と判定されるまでの時間を短くすることができます（ユーザーへのレスポンスの迅速化、オペレーションの再試行、別のオペレーションの試行、タスクキューへのオペレーションの追加などの目的に利用できます）。

put() と同様に、複数のキーが指定する場合、それらのキーは複数のエンティティグループ内にあってもかまいません。

この関数が返すオブジェクトを使用すると、呼び出しの結果に応じてブロックできます。

get (keys, read_policy=STRONG_CONSISTENCY, deadline=60)

Datastore のキーを使用して、特定のモデルインスタンスをフェッチします。

引数

keys

取得するエンティティのキー、キーの文字列表現、またはキーあるいはキーの文字列表現のリスト。

read_policy

目的のデータ整合性レベルを指定する読み取りポリシー

STRONG_CONSISTENCY: 最新の結果を保証します。ただし、単一のエンティティグループに限定されます。
EVENTUAL_CONSISTENCY: 複数のエンティティグループにわたる読み取りが可能ですが、返される結果は最新のものではないことがあります。一般に、結果整合性クエリのほうが強整合性クエリよりも処理時間が短くなりますが、その保証はありません。

注: グローバル（非祖先）クエリでは、この引数は無視されます。

deadline

keys が単一のキー（またはキーの文字列表現）からなる場合、この関数は該当するキーが Datastore 内にあればそのキーに関連付けられているモデルインスタンスを返し、なければ None を返します。keys がリストの場合、戻り値は対応するモデルインスタンスのリストとなります。指定されたキーに関連付けられているエンティティがなければ、None 値のリストを返します。

Model.get() もご覧ください。

get_async (keys, read_policy=STRONG_CONSISTENCY, deadline=60)

指定されたモデルインスタンスを Datastore から非同期でフェッチします。

この関数は、非同期オブジェクトを返す点を除き、get() と同じです。get_result() を呼び出すと、戻り値に応じて呼び出しをブロックし、結果を返すことができます。

引数

keys

取得するエンティティのキー、キーの文字列表現、またはキーあるいはキーの文字列表現のリスト。

read_policy

目的のデータ整合性レベルを指定する読み取りポリシー

STRONG_CONSISTENCY: 最新の結果を保証します。ただし、単一のエンティティグループに限定されます。
EVENTUAL_CONSISTENCY: 複数のエンティティグループにわたる読み取りが可能ですが、返される結果は最新のものではないことがあります。一般に、結果整合性クエリのほうが強整合性クエリよりも処理時間が短くなりますが、その保証はありません。

注: グローバル（非祖先）クエリでは、この引数は無視されます。

deadline

Model.get() もご覧ください。

get_indexes ()

呼び出し側のアプリケーションに属する複合インデックスのリストを返します。

以下の例では、インデックスを取得して使用しています。

def get_index_state_as_string(index_state):
  return {db.Index.BUILDING:'BUILDING', db.Index.SERVING:'SERVING',
          db.Index.DELETING:'DELETING', db.Index.ERROR:'ERROR'}[index_state]

def get_sort_direction_as_string(sort_direction):
  return {db.Index.ASCENDING:'ASCENDING',
          db.Index.DESCENDING:'DESCENDING'}[sort_direction]

def dump_indexes():
  for index, state in db.get_indexes():
    print "Kind: %s" % index.kind()
    print "State: %s" % get_index_state_as_string(state)
    print "Is ancestor: %s" % index.has_ancestor()
    for property_name, sort_direction in index.properties():
      print "  %s:%s" % (property_name,
                         get_sort_direction_as_string(sort_direction))

get_indexes_async ()

呼び出し側のアプリケーションに属する複合インデックスのリストを非同期で返します。

is_in_transaction ()

トランザクションで現在のスコープが実行されているかどうかを表すブール値を返します。

model_to_protobuf (model_instance)

Model インスタンスのプロトコルバッファをシリアル化します。プロトコルバッファは Google のシリアル化形式で、リモートプロシージャコールで使用されます。バックアップまたは復元で Datastore オブジェクトのシリアル化を行う場合に使用します。

注意: この関数では、オープンソースプロトコルバッファ形式以外のプロトコルには別の形式を使用します。この形式はオープンソースの実装と互換性がありません。

引数

model_instance: シリアル化するクラス Model（またはサブクラス）のインスタンス。

オブジェクトのプロトコルバッファのシリアル化をバイト文字列として返します。

model_from_protobuf (pb)

プロトコルバッファのシリアル化に基づいて Model インスタンスを作成します。詳細については、model_to_protobuf() をご覧ください。

引数

pb: プロトコルバッファのシリアル化。model_to_protobuf() によって返されます。

該当する種類クラスのオブジェクトを返します。種類クラスが存在しない場合、KindError 例外が発生します。オブジェクトがモデルに有効でない場合は、BadValueError 例外が発生します。

他の Model インスタンスと同様に、put() メソッドを使用して新しいオブジェクトを Datastore に保存できます。このオブジェクトは、プロトコルバッファの作成時に取得したキーを保持します。このキーを持つオブジェクトが Datastore にすでに存在している場合、シリアル化を解除したオブジェクトを保存すると、既存のオブジェクトが上書きされます。

注意: オブジェクトのキーがシステム割り当ての ID を使用し、ID が特定のパスと種類に割り当てられていない場合、保存は成功しますが、ID は予約されません。この ID が今後作成されるオブジェクトに割り当てられる場合があります。その場合、以前のオブジェクトは上書きされます。安全のため、シリアル化されたときに存在していたアプリケーションでのみオブジェクトを復元してください。

model_is_projection (model_instance)

指定されたクエリ（model_instance）が完全なエンティティに対するクエリではなく、射影クエリである場合に True を返します。

引数

model_instance: 射影クエリかどうかを確認しているクエリ。

クエリが射影クエリの場合は True を返し、そうでない場合は False を返します。

put (models, deadline=60)

1 つ以上のモデルインスタンスを Datastore に書き込みます。

引数

models: 保存するモデルインスタンスまたはモデルインスタンスのリスト。
deadline: Datastore から結果が返されるのを待機する時間の最大値（秒）。この時間を過ぎると処理を中止し、エラーを返します。整数値または浮動小数点値のいずれかを指定できます。デフォルト値（60 秒）を超える値は設定できませんが、デフォルトより短い値に設定することは可能です。これにより、特定のオペレーションが失敗と判定されるまでの時間を短くすることができます（ユーザーへのレスポンスの迅速化、オペレーションの再試行、別のオペレーションの試行、タスクキューへのオペレーションの追加などの目的に利用できます）。

複数のモデルインスタンスが存在する場合、複数のエンティティグループが存在する可能性があります。

オペレーション中にエラーが発生すると、エンティティの一部が書き込まれていても例外が発生します。例外が発生せずに呼び出しが完了した場合、すべてのエンティティが正常に書き込まれています。

models が単一のモデルインスタンスから構成されている場合、この関数は対応する Key オブジェクトを返します。models がリストの場合は、対応する Key オブジェクトのリストを返します。

注意: オペレーションがトランザクション内で実行されない限り、1 回のオペレーションで複数のエンティティを書き込んでも、アトミックに書き込まれるとは限りません。クエリを強整合性で実行しても、Datastore にクエリを送信する他のプロセスで矛盾する結果が生成される可能性があります。

put_async (models, deadline=60)

1 つ以上のモデルインスタンスを Datastore に書き込みます。

この関数は、非同期オブジェクトを返す点を除き、put() と同じです。get_result() を呼び出すと、戻り値に応じて呼び出しをブロックし、結果を返すことができます。

引数

models: 保存するモデルインスタンスまたはモデルインスタンスのリスト。
deadline: Datastore から結果が返されるのを待機する時間の最大値（秒）。この時間を過ぎると処理を中止し、エラーを返します。整数値または浮動小数点値のいずれかを指定できます。デフォルト値（60 秒）を超える値は設定できませんが、デフォルトより短い値に設定することは可能です。これにより、特定のオペレーションが失敗と判定されるまでの時間を短くすることができます（ユーザーへのレスポンスの迅速化、オペレーションの再試行、別のオペレーションの試行、タスクキューへのオペレーションの追加などの目的に利用できます）。

複数のモデルインスタンスが存在する場合、複数のエンティティグループが存在する可能性があります。

この関数は、get_result() を呼び出すことができる非同期オブジェクトを返します。返される結果は put() と同じです。

query_descendants (model_instance)

モデルインスタンスのすべての子孫のクエリを返します。

引数

model_instance: 検索する子孫のモデルインスタンス。

run_in_transaction (function, *args, **kwargs)

Datastore の更新を含む関数を 1 つのトランザクションで実行します。トランザクションの実行中に任意のコードで例外が発生すると、トランザクションで行われた更新がすべてロールバックされます。または、@db.transactional() デコレータを使用することもできます。

引数

function: 実行する関数。
args: 関数に渡す位置引数。
kwargs: 関数に渡すキーワード引数。

関数が値を返すと、run_in_transaction() が値を呼び出し側に返します。

関数で例外が発生すると、トランザクションがロールバックされます。例外が Rollback 例外の場合、再度発生することはありません。他の例外の場合、呼び出し側で同じ例外が発生します。

Datastore は、楽観的ロックを使用してトランザクションを再試行します。関数が準備したトランザクションを commit できない場合、run_in_transaction() は関数を再度呼び出し、トランザクションを最大 3 回まで再試行します（異なる再試行回数を変更するには、run_in_transaction_custom_retries() を使用します）。1 回のトランザクションでトランザクション関数が複数回呼び出される可能性があるため、引数の変更などの副作用がないようにしてください。

高い競合発生率などが原因でトランザクションを commit できない場合、TransactionFailedError 例外が発生します。

from google.appengine.ext import db

class Counter(db.Model):
  name = db.StringProperty()
  count = db.IntegerProperty(default=0)

def decrement(key, amount=1):
  counter = db.get(key)
  counter.count -= amount
  if counter.count < 0:        # Don't let counter go negative
    raise db.Rollback()
  db.put(counter)

q = db.GqlQuery("SELECT * FROM Counter WHERE name = :1", "foo")
counter = q.get()
db.run_in_transaction(decrement, counter.key(), amount=5)

run_in_transaction_custom_retries (retries, function, *args, **kwargs)

Datastore の更新を含む関数を 1 つのトランザクションで実行します。競合が発生した場合、指定された回数、トランザクションを再試行します。トランザクションの実行中に任意のコードで例外が発生すると、トランザクションで行われた更新がすべてロールバックされます。

再試行回数の指定を除き、この関数の動作は run_in_transaction() と同じです。

引数

retries: エンティティグループ内で競合が発生したとき（複数のユーザーがグループを同時に変更した場合）に関数を呼び出す最大回数。
function: 実行する関数。
args: 関数に渡す位置引数。
kwargs: 関数に渡すキーワード引数。

run_in_transaction_options (options, function, *args, **kwargs)

トランザクションオプションオブジェクトに指定されたオプションを使用して、Datastore の更新を含む関数を 1 つのトランザクションで実行します。トランザクションの実行中に任意のコードで例外が発生すると、トランザクションで行われた Datastore の更新がすべてロールバックされます。

クロスグループ（XG）トランザクションの場合、トランザクションオプションオブジェクトの xg パラメータを True に設定する必要があります。

引数

options: このトランザクションで使用される設定を含むトランザクションオプションオブジェクト。XG トランザクションを有効にするには、xg パラメータを True に設定する必要があります。
function: 実行する関数。
args: 関数に渡す位置引数。
kwargs: 関数に渡すキーワード引数。

関数が値を返すと、run_in_transaction_options() が値を呼び出し側に返します。

Datastore は、楽観的ロックを使用してトランザクションを再試行します。関数が準備したトランザクションを commit できない場合、run_in_transaction_options() は関数を再度呼び出し、トランザクションオプションオブジェクトで指定された試行回数に達するまでトランザクションを再試行します。1 回のトランザクションでトランザクション関数が複数回呼び出される可能性があるため、引数の変更などの副作用がないようにしてください。

高い競合発生率などが原因でトランザクションを commit できない場合、TransactionFailedError 例外が発生します。

以下の例では、この関数を使用してクロスグループトランザクションを実行しています。

from google.appengine.ext import db

xg_options = db.create_transaction_options(xg=True)

def my_txn():
  x = MyModel(a=3)
  x.put()
  y = MyModel(a=7)
  y.put()

db.run_in_transaction_options(xg_options, my_txn)

to_dict (model_instance, dictionary=None)

モデルインスタンスの辞書表現を作成して返します。

引数

model_instance: コピーするモデルインスタンス。
dictionary: モデルのデータを統合する辞書（存在する場合）。モデル値が辞書の値を上書きします。モデルインスタンスのフィールドに対応していない辞書エントリは維持されます。

デコレータ

@db.transactional (propagation=ALLOWED, xg=False, retries=3, deadline=60)

db トランザクション内で関数を実行します。したがって、run_in_transaction(func) の代わりに、func() を呼び出すことができます。

引数

propagation

このトランザクション関数が別のトランザクション内から呼び出された場合の処理内容:

ALLOWED: すでにトランザクション中の場合は、そのトランザクションを引き続き使用します。それ以外の場合は、トランザクションを開始します。
注: このポリシーを使用する関数が例外をスローした場合、例外をキャッチして外側のトランザクションを commit することは安全ではありません。関数によって外側のトランザクションが不適切な状態に置かれている可能性があります。
MANDATORY: 既存のトランザクション内で続行します（該当する場合）。それ以外の場合は、BadRequestError 例外が発生します。
注: このポリシーを使用する関数が例外をスローした場合、例外をキャッチして外側のトランザクションを commit することは安全ではありません。関数によって外側のトランザクションが不適切な状態に置かれている可能性があります。
INDEPENDENT: 既存のトランザクションを一時停止して、新しいトランザクションを作成します。
注: このポリシーを使用する関数では、新しいトランザクション内で読み取ったエンティティを返さないようにしてください。これは、新しいトランザクション内で読み取ったエンティティと、外側のトランザクションとの間に、トランザクションの一貫性がないためです。
NESTED: （現時点ではサポートされていません）既存のトランザクション内に、ネストされたトランザクションを作成します。

xg

True の場合、クロスグループ（XG）トランザクションを許可します。ブール値以外を設定すると、BadArgumentError 例外が発生します。

retries

トランザクションの commit が失敗した場合に再試行する回数。

deadline

@db.non_transactional (allow_existing=True)

トランザクション内から呼び出されても、db トランザクションの外部で関数を実行します。

引数

allow_existing: True の場合、既存のトランザクション内から関数を呼び出すことができます。False の場合、BadRequestError 例外をスローします。