Model クラス

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

Model クラスは、データモデル定義のスーパークラスです。

Modelgoogle.appengine.ext.db モジュールで定義されています。

はじめに

アプリケーションでデータモデルを定義するには、Model をサブクラス化するクラスを定義します。モデルのプロパティは、クラス属性と Property クラスのインスタンスを使用して定義します。次に例を示します。

class Story(db.Model):
  title = db.StringProperty()
  body = db.TextProperty()
  created = db.DateTimeProperty(auto_now_add=True)

アプリケーションで新しいデータ エンティティを作成するには、Model クラスのサブクラスをインスタンス化します。エンティティのプロパティは、インスタンスの属性を使用して割り当てることも、コンストラクタへのキーワード引数として割り当てることもできます。

s = Story()
s.title = "The Three Little Pigs"

s = Story(title="The Three Little Pigs")

Model サブクラスの名前は、データストア エンティティの種類名として使用されます。2 つのアンダースコア(__)で始まる種類名はすべて Datastore で予約されています。Model サブクラスでそれらの名前を使用することはできません。

属性の名前は、エンティティに設定された対応するプロパティの名前として使用されます。モデル インスタンスの属性のうち、名前がアンダースコア(_)で始まる属性は無視されます。そのため、データストアに保存されないデータについては、モデル インスタンスでこのような属性を使用して保管できます。

データストアおよび Model クラスの API には、プロパティ名とモデル インスタンス属性に関するいくつかの制約事項があります。詳細については、使用できないプロパティ名をご覧ください。

すべてのエンティティにはキーがあります。キーは、そのエンティティを一意に表す ID です。オプションで、特定の種類のすべてのエンティティで一意の文字列として、キー名をキーに含めることもできます。Key.from_path() メソッドと Model.get_by_key_name() メソッドでは、エンティティの種類とキー名を指定してエンティティを取得できます。

また、エンティティには任意のエンティティを指定することもできます。親子関係によって形成されるエンティティ グループを使用して、データストア内でのトランザクション性とデータの局所性を制御します。アプリケーションで 2 つのエンティティの間に親子関係を作成するには、親エンティティを parent 引数として子エンティティのコンストラクタに渡します。

Model.get_or_insert() メソッドを使用してエンティティを取得すると、対象のエンティティが存在しない場合には必要に応じてデータストア内にエンティティを作成できます。

keyname = "some_key"
s = Story.get_or_insert(keyname, title="The Three Little Pigs")

注: モデル インスタンスを明示的に、または Model.get_or_insert() によって初めて書き込む(put)までは、データストア内にモデル インスタンスに対応するエンティティは存在しません。

dict というモデル インスタンスのデータコピーを作成するには、db.to_dict 関数を使用します。

コンストラクタ

Model クラスのコンストラクタは次のように定義されます。

class Model (parent=None, key_name=None, **kwds)

これが、データモデル定義のスーパークラスです。

コンストラクタの実行中に、各プロパティの validate() メソッドが呼び出されます。これらの呼び出しで発生した例外は、このコンストラクタの呼び出し側に伝播されます。

引数

parent
新しいエンティティの親となるモデル インスタンスまたはエンティティのキー。
key_name

エンティティのキー名。この名前は主キーの一部となります。None の場合、システムで生成された数値 ID がキーとして使用されます。

key_name の値には __*__ の形式を使用しないでください。

キー名は、str の値を ASCII テキストに変換した状態の Unicode 文字列として保存されます。

このオブジェクトに対して put() を呼び出すと、同じキーが設定された既存のデータストア エンティティが上書きされます。

kwds
インスタンスのプロパティの初期値。キーワード引数として使用されます。 それぞれの名前が Model クラスで定義されている属性に対応します。

その他のキーワード属性

key

エンティティの明示的な Key インスタンス。key_name または parent と一緒に使用することはできません。None の場合、key_name および parent の動作にフォールバックします。allocate_ids() を使用して新しいエンティティの数値 ID を予約する場合、この属性が役立ちます。

key の値は有効な Key インスタンスでなければなりません。

このオブジェクトに対して put() を呼び出すと、同じキーが設定された既存のデータストア エンティティが上書きされます。

クラスメソッド

Model クラスには次のクラスメソッドがあります。

Model.get (keys)

指定されたキー(複数可)のモデル インスタンスを取得します。キーは、モデルの種類のエンティティを表すものでなければなりません。指定されたのが適切な種類のキーではない場合、KindError 例外が発生します。

このメソッドは db.get() 関数と同様ですが、型チェックが追加で行われます。

引数

keys
取得するエンティティのキー、キーの文字列表現、またはキーあるいはキーの文字列表現のリスト。
read_policy
目的のデータ整合性レベルを指定する読み取りポリシー:
STRONG_CONSISTENCY
最新の結果を保証します。ただし、単一のエンティティ グループに限定されます。
EVENTUAL_CONSISTENCY
複数のエンティティ グループにわたる読み取りが可能ですが、返される結果は最新のものではないことがあります。一般に、結果整合性クエリのほうが強整合性クエリよりも処理時間が短くなりますが、その保証はありません。

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

deadline
Datastore から結果が返されるのを待機する時間の最大値(秒)。この時間を過ぎると処理を中止し、エラーを返します。整数値または浮動小数点値のいずれかを指定できます。デフォルト値(60 秒)を超える値は設定できませんが、デフォルトより短い値に設定して、特定の操作が失敗と判定されるまでの時間を短くすることはできます(ユーザーへの応答の迅速化、操作の再試行、別の操作の試行、タスクキューへの操作の追加などのため)。

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

db.get() 関数もご覧ください。

Model.get_by_id (ids, parent=None)

指定された数値 ID(複数可)のモデル インスタンスを取得します。

引数

ids
数値のエンティティ ID、または数値 ID のリスト。
parent
リクエストするエンティティの親エンティティ。モデルまたはキーとして指定します。リクエストするエンティティに親エンティティがない場合は、None(デフォルト)を指定します。1 つの呼び出しで複数のエンティティをリクエストする場合、それらのエンティティの親がすべて同じでなければなりません。
read_policy
目的のデータ整合性レベルを指定する読み取りポリシー:
STRONG_CONSISTENCY
最新の結果を保証します。ただし、単一のエンティティ グループに限定されます。
EVENTUAL_CONSISTENCY
複数のエンティティ グループにわたる読み取りが可能ですが、返される結果は最新のものではないことがあります。一般に、結果整合性クエリのほうが強整合性クエリよりも処理時間が短くなりますが、その保証はありません。

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

deadline
Datastore から結果が返されるのを待機する時間の最大値(秒)。この時間を過ぎると処理を中止し、エラーを返します。整数値または浮動小数点値のいずれかを指定できます。デフォルト値(60 秒)を超える値は設定できませんが、デフォルトより短い値に設定して、特定の操作が失敗と判定されるまでの時間を短くすることはできます(ユーザーへの応答の迅速化、操作の再試行、別の操作の試行、タスクキューへの操作の追加などのため)。

ids が単一の数値 ID からなる場合、このメソッドは該当する ID がデータストア内にあればその ID に関連付けられているモデル インスタンスを返し、なければ None を返します。ids がリストの場合、戻り値は対応するモデル インスタンスのリストとなります。指定された数値 ID に関連付けられているエンティティがなければ、None 値のリストが返されます。

Model.get_by_key_name (key_names, parent=None)

指定されたキー名(複数可)のモデル インスタンスを取得します。

引数

key_names
キー名、またはキー名のリスト。
parent
リクエストするエンティティの親エンティティ。モデルまたはキーとして指定します。リクエストするエンティティに親エンティティがない場合は、None(デフォルト)を指定します。1 つの呼び出しで複数のエンティティをリクエストする場合、それらのエンティティの親がすべて同じでなければなりません。
read_policy
目的のデータ整合性レベルを指定する読み取りポリシー:
STRONG_CONSISTENCY
最新の結果を保証します。ただし、単一のエンティティ グループに限定されます。
EVENTUAL_CONSISTENCY
複数のエンティティ グループにわたる読み取りが可能ですが、返される結果は最新のものではないことがあります。一般に、結果整合性クエリのほうが強整合性クエリよりも処理時間が短くなりますが、その保証はありません。

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

deadline
Datastore から結果が返されるのを待機する時間の最大値(秒)。この時間を過ぎると処理を中止し、エラーを返します。整数値または浮動小数点値のいずれかを指定できます。デフォルト値(60 秒)を超える値は設定できませんが、デフォルトより短い値に設定して、特定の操作が失敗と判定されるまでの時間を短くすることはできます(ユーザーへの応答の迅速化、操作の再試行、別の操作の試行、タスクキューへの操作の追加などのため)。

key_names が単一のキー名からなる場合、このメソッドは該当するキー名がデータストア内にあればそのキー名に関連付けられているモデル インスタンスを返し、なければ None を返します。key_names がリストの場合、戻り値は対応するモデル インスタンスのリストとなります。指定されたキー名に関連付けられているエンティティがなければ、None 値のリストが返されます。

Model.get_or_insert (key_name, **kwds)

指定されたキー名が設定されているモデルの種類のエンティティを取得しようと試みます。該当するエンティティが存在する場合、get_or_insert() は単純にそのエンティティを返します。存在しない場合は、kwds に指定されている種類、名前、パラメータを設定した新しいエンティティを作成、保管してから返します。

アトミック性を確保するために、get 操作と以降の(可能な場合)put 操作はトランザクションにラップされます。つまり、get_or_insert() は既存のエンティティを上書きすることはありません。指定された種類と名前が設定されたエンティティが存在しない場合に限り、新しいエンティティを挿入します。つまり、get_or_insert() は以下の Python コードに相当します。

def txn(key_name, **kwds):
  entity = Story.get_by_key_name(key_name, parent=kwds.get('parent'))
  if entity is None:
    entity = Story(key_name=key_name, **kwds)
    entity.put()
  return entity

def get_or_insert(key_name, **kwargs):
  return db.run_in_transaction(txn, key_name, **kwargs)

get_or_insert('some key', title="The Three Little Pigs")

引数

key_name
エンティティのキーの名前。
kwds
指定されたキー名のインスタンスが存在しない場合に Model クラスのコンストラクタに渡すキーワード引数。対象のエンティティに親エンティティがある場合、parent 引数は必須です。

注: get_or_insert()read_policy 引数や deadline 引数を受け入れません。

このメソッドが返す、リクエストされたエンティティを表す Model クラスのインスタンスは、既存のものである場合も、メソッドが作成したものである場合もあります。すべてのデータストア操作の例に漏れず、このメソッドがトランザクションを完了できなかった場合は TransactionFailedError が発生します。

Model.all (keys_only=False)

該当するモデルに対応する種類のすべてのエンティティを表す Query オブジェクトを返します。クエリ オブジェクトに対して実行するメソッドでは、クエリの実行前にフィルタと並べ替え順を適用できます。詳細については、Query クラスをご覧ください。

引数

keys_only
クエリでエンティティ全体を返すか、またはキーだけを返すかどうか。クエリでキーだけを返すほうが、エンティティ全体を返す場合より処理時間が短く、CPU 時間を短縮できます
Model.gql (query_string, *args, **kwds)

このモデルの全インスタンスを対象に GQL クエリを実行します。

引数

query_string
GQL クエリの SELECT * FROM model(このクラスメソッドを使用することによって暗黙に定義されます)に続く部分。
args
位置パラメータ バインディング。GqlQuery() コンストラクタと同様です。
kwds
キーワード パラメータ バインディング。GqlQuery() コンストラクタと同様です。
s = Story.gql("WHERE title = :1", "Little Red Riding Hood")

s = Story.gql("WHERE title = :title", title="Little Red Riding Hood")

戻り値は GqlQuery オブジェクトです。このオブジェクトを使用して結果にアクセスできます。

Model.kind ()
モデルの種類を返します。これは通常、Model サブクラスの名前です。
Model.properties ()
この Model クラスに定義されたすべてのプロパティのディクショナリを返します。

インスタンス メソッド

モデル インスタンスには次のメソッドがあります。

key ()

このモデル インスタンスのデータストア Key を返します。

モデル インスタンスのキーには、インスタンスのエンティティの種類とあわせて一意の ID が組み込まれます。 ID は、インスタンスの作成時にアプリケーションで明示的に割り当てたキー名の文字列、またはインスタンスがデータストアに書き込まれた(put)時点で App Engine により自動的に割り当てられた整数の数値 ID のいずれかです。インスタンスに ID が割り当てられる前に key() を呼び出すと、NotSavedError 例外が発生します。

put ()

モデル インスタンスをデータストアに格納します。モデル インスタンスが新しく作成されてデータストアにまだ格納されていない場合、このメソッドにより、データストア内に新しいデータ エンティティが作成されます。それ以外の場合は、該当する既存のデータ エンティティが現在のプロパティ値で更新されます。

このメソッドは、格納されているエンティティのキーを返します。

データをコミットできなかった場合は、 TransactionFailedError 例外が発生します。

引数

deadline
Datastore から結果が返されるのを待機する時間の最大値(秒)。この時間を過ぎると処理を中止し、エラーを返します。整数値または浮動小数点値のいずれかを指定できます。デフォルト値(60 秒)を超える値は設定できませんが、デフォルトより短い値に設定して、特定の操作が失敗と判定されるまでの時間を短くすることはできます(ユーザーへの応答の迅速化、操作の再試行、別の操作の試行、タスクキューへの操作の追加などのため)。
delete ()

データストアからモデル インスタンスを削除します。インスタンスが一度もデータストアに書き込まれていない場合(put)、削除操作によって NotSavedError 例外が発生します。

引数

deadline
Datastore から結果が返されるのを待機する時間の最大値(秒)。この時間を過ぎると処理を中止し、エラーを返します。整数値または浮動小数点値のいずれかを指定できます。デフォルト値(60 秒)を超える値は設定できませんが、デフォルトより短い値に設定して、特定の操作が失敗と判定されるまでの時間を短くすることはできます(ユーザーへの応答の迅速化、操作の再試行、別の操作の試行、タスクキューへの操作の追加などのため)。
is_saved ()

モデル インスタンスが一度でもデータストアに書き込まれている場合(put)、True を返します。

このメソッドは、インスタンスが作成されてから 1 回以上データストアに書き込まれているかどうかだけをチェックします。前回の書き込み以降にインスタンスのプロパティが更新されていかどうかはチェックしません

dynamic_properties ()

このモデル インスタンスに定義されているすべての動的プロパティの名前のリストを返します。このメソッドが適用されるのは、Expando クラスのインスタンスのみです。Expando 以外のモデル インスタンスに対しては、空のリストが返されます。

parent ()

このインスタンスの親エンティティのモデル インスタンスを返します。インスタンスに親がない場合は、None を返します。

parent_key ()

このインスタンスの親エンティティの Key を返します。インスタンスに親がない場合は、None を返します。

to_xml ()

モデル インスタンスの XML 表現を返します。

プロパティ値は Atom 仕様と Data 仕様に準拠します。

使用できないプロパティ名

データストアとその API には、エンティティのプロパティおよびモデル インスタンスの属性に関するいくつかの制約事項があります。

名前の先頭と末尾のそれぞれに 2 つのアンダースコアを持つプロパティ名(__*__)は、すべてデータストアで予約されています。データストア エンティティでそのような名前のプロパティを使用することはできません。

Python モデル API は、Model クラスまたは Expando クラスの、名前がアンダースコア(_)で始まる属性をすべて無視します。アプリケーションでは、これらの属性を使用して、データストアに保存されないデータをモデル オブジェクトに関連付けることができます。

最後に、Python モデル API ではオブジェクト属性を使用してモデルのプロパティを定義します。デフォルトでは、これらのオブジェクト属性に基づく名前がデータストア エンティティのプロパティに付けられます。Model クラスにはモデルの定義以外の目的で使用するプロパティやメソッドがあるため、それらの属性を Python API でプロパティに使用することはできません。たとえば、Model クラスでは、key 属性でアクセスするプロパティを使用できません。

ただし、name 引数をプロパティ コンストラクタに渡すことにより、プロパティでデータストア用にオブジェクト属性名とは異なる名前を指定することはできます。これにより、データストア エンティティでは Model クラスで予約されている属性と同様のプロパティ名を使用し、Model クラスでは別の属性名を使用することが可能になります。

class MyModel(db.Model):
  obj_key = db.StringProperty(name="key")

Python API の Model クラスで予約されている属性名は次のとおりです。

  • all
  • app
  • copy
  • delete
  • entity
  • entity_type
  • fields
  • from_entity
  • get
  • gql
  • instance_properties
  • is_saved
  • key
  • key_name
  • kind
  • parent
  • parent_key
  • properties
  • put
  • setdefault
  • to_xml
  • update
このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

Python 2 の App Engine スタンダード環境