注: 新しいアプリケーションを作成する際は、NDB クライアント ライブラリを使用することを強くおすすめします。NDB クライアント ライブラリには、Memcache API によるエンティティの自動キャッシュをはじめ、このクライアント ライブラリにはないメリットがあります。古い DB クライアント ライブラリを現在使用している場合は、DB から NDB への移行ガイドをお読みください。
App Engine Datastore は、データ エンティティのプロパティに関して固定された一連の値の型をサポートしています。
Property
クラスでは、基本となる値の型との間で変換される新しい型を定義できます。これらの値の型は、
Expando
動的プロパティと
ListProperty
集約プロパティ モデルで直接使用できます。
次の表は、基本となるデータ型に直接対応する値を持つ Property クラスを示しています。これらの値の型は、Expando 動的プロパティや ListProperty 集約型で使用できます。
Property クラス | 値の型 | 並べ替え順 |
---|---|---|
IntegerProperty
|
int
long
(64 ビット) |
数値 |
FloatProperty
|
float
|
数値 |
BooleanProperty
|
bool
|
False < True |
StringProperty
|
str
unicode
|
Unicode(str は ASCII として処理されます) |
TextProperty
|
db.Text
|
なし |
ByteStringProperty
|
ByteString
|
バイト順 |
BlobProperty
|
db.Blob
|
なし |
DateProperty
TimeProperty
DateTimeProperty
|
datetime.date
datetime.time
datetime.datetime
|
時系列 |
GeoPtProperty
|
db.GeoPt
|
緯度、 経度の順 |
PostalAddressProperty
|
db.PostalAddress
|
Unicode |
PhoneNumberProperty
|
db.PhoneNumber
|
Unicode |
EmailProperty
|
db.Email
|
Unicode |
UserProperty
|
users.User
|
メールアドレス Unicode 順UserProperty クラスの説明に含まれる注意事項のとおり、 UserProperty の使用は避けてください。 |
IMProperty
|
db.IM
|
Unicode |
LinkProperty
|
db.Link
|
Unicode |
CategoryProperty
|
db.Category
|
Unicode |
RatingProperty
|
db.Rating
|
数値 |
ReferenceProperty
SelfReferenceProperty
|
db.Key
|
パス要素順 (種類、識別子、 種類、識別子...) |
blobstore.BlobReferenceProperty
|
blobstore.BlobInfo
|
バイト順 |
ListProperty
StringListProperty
|
サポートされている型の
list
|
昇順の場合は、小さい要素から順に 降順の場合は、大きい要素から順に |
データストアの値の型
データストア エンティティのプロパティ値の型は、次のいずれかです。Model
の定義で使用する対応する Property
クラスの一覧については、上のリストをご覧ください。
Python 標準の型と users.User
以外のこのセクションで説明するすべてのクラスは、google.appengine.ext.db
モジュールによって提供されます。
str
またはunicode
-
短い文字列(1,500 バイト以下)。
str
値は、ascii
コーデックでエンコードされたテキストとみなされ、保存する前にunicode
値に変換されます。値はデータストアからunicode
値として返されます。他のコーデックを使用する短い文字列の場合は、unicode
値を使用します。短い文字列は、データストアによってインデックスに登録され、フィルタや並べ替え順に使用できます。長さが 1,500 バイトを超え、インデックスに登録されていないテキスト文字列の場合は、
Text
インスタンスを使用します。1,500 バイトを超え(インデックスに登録されず)、エンコードされていないバイト文字列にはBlob
インスタンスを使用します。エンコードされていない 1,500 バイトまでのテキスト以外のバイト文字列には、ByteString
インスタンスを使用します。これらはインデックスに登録する必要があります。モデル プロパティ:
StringProperty
bool
-
ブール値(
True
またはFalse
)。モデル プロパティ:
BooleanProperty
int
またはlong
-
整数値(最大 64 ビット)。
Python
int
値は、保存する前に Pythonlong
値に変換されます。int
として保存された値はlong
として返されます。64 ビットを超える
long
が割り当てられた場合は、下位の 64 ビットのみが保存されます。モデル プロパティ:
IntegerProperty
float
-
浮動小数点数。
モデル プロパティ:
FloatProperty
datetime.datetime
-
日時。
datetime
モジュールのドキュメントをご覧ください。datetime
値にtzinfo
属性がある場合は、UTC タイムゾーンに変換して保存されます。データストアからは、tzinfo
がNone
である UTC として値が返されます。特定のタイムゾーンの日付と時刻の値を必要とするアプリケーションでは、値の更新時にtzinfo
を正しく設定し、値にアクセスしたときにその値を該当するタイムゾーンに変換する必要があります。一部のライブラリでは、
TZ
環境変数を使用して日付値に適用されるタイムゾーンを制御します。App Engine はこの環境変数を"UTC"
に設定します。アプリケーションでこの変数を変更しても、Python コードの外部では環境変数の変更が認識されないため、一部の datetime 関数の動作は変更されません。値を特定のタイムゾーンとの間でのみ変換する場合は、カスタムの
datetime.tzinfo
を実装してデータストアから取得した値を変換できます。import datetime import time class Pacific_tzinfo(datetime.tzinfo): """Implementation of the Pacific timezone.""" def utcoffset(self, dt): return datetime.timedelta(hours=-8) + self.dst(dt) def _FirstSunday(self, dt): """First Sunday on or after dt.""" return dt + datetime.timedelta(days=(6-dt.weekday())) def dst(self, dt): # 2 am on the second Sunday in March dst_start = self._FirstSunday(datetime.datetime(dt.year, 3, 8, 2)) # 1 am on the first Sunday in November dst_end = self._FirstSunday(datetime.datetime(dt.year, 11, 1, 1)) if dst_start <= dt.replace(tzinfo=None) < dst_end: return datetime.timedelta(hours=1) else: return datetime.timedelta(hours=0) def tzname(self, dt): if self.dst(dt) == datetime.timedelta(hours=0): return "PST" else: return "PDT" pacific_time = datetime.datetime.fromtimestamp(time.mktime(utc_time.timetuple()), Pacific_tzinfo())
詳しくは
datetime
モジュールのドキュメント(datetime.tzinfo
を含む)をご覧ください。サードパーティのモジュールpytz
もご覧ください。ただし、pytz
のディストリビューションには多くのファイルが含まれていることにご注意ください。DateTimeProperty
モデル プロパティ クラスには、モデル インスタンスが保存された日時を自動的に使用する機能などが備えられています。これらはモデルの機能であり、生のデータストア値(Expando
動的プロパティなど)では使用できません。モデル プロパティ:
DateTimeProperty
、DateProperty
、TimeProperty
list
-
サポートされているデータ型の値で構成される値のリスト。
list
をExpando
動的プロパティの値として使用する場合は、空のリストを指定できません。理由は、リストの値の保存方法にあります。list プロパティに項目がない場合、それを表す値がデータストアにはありません。プロパティの空のリスト値を表すには、静的プロパティとListProperty
クラスを使用します。モデル プロパティ:
ListProperty
-
db.Key
-
別のデータストア エンティティのキー。
注: キー文字列は 1,500 バイト以下に制限されています。
m = Employee(name="Susan", key_name="susan5") m.put() e = Employee(name="Bob", manager=m.key()) e.put() m_key = db.Key.from_path("Employee", "susan5") e = Employee(name="Jennifer", manager=m_key)
モデル プロパティ:
ReferenceProperty
、SelfReferenceProperty
-
blobstore.BlobKey
-
値をアップロードしたときに Blobstore によって生成される Blobstore 値のキー。
モデル プロパティ:
blobstore.BlobReferenceProperty
-
users.User
-
Google アカウントを持つユーザー。
ユーザーが自身のメールアドレスを変更しても、データストア内の
user.User
値は更新されません。このため、users.User
値をUserProperty
値として保存しないことを強くおすすめします。これにはメールアドレスとともに一意の ID が含まれているためです。ユーザーがメールアドレスを変更すると、古い保存済みのuser.User
と新しいuser.User
の値を比較した場合に一致しなくなります。代わりに、user.User
値のuser_id()
をユーザーの不変の一意の ID として使用します。モデル プロパティ:
UserProperty
- class Blob(arg=None)
-
バイト文字列としてのバイナリデータ。これは組み込みの
str
型のサブクラスです。Blob プロパティはインデックスに登録されず、フィルタや並べ替え順には使用できません。
Blob は画像などのバイナリデータ用です。
str
値を取りますが、この値はバイト文字列として保存され、テキストとしてエンコードされません。大規模なテキストデータにはText
インスタンスを使用してください。モデル プロパティ:
BlobProperty
class MyModel(db.Model): blob = db.BlobProperty() m = MyModel() m.blob = db.Blob(open("image.png", "rb").read())
XML では、Blob はバイナリデータを含むかどうかに関係なく Base-64 でエンコードされます。
- class ByteString(arg)
-
1,500 バイト以下の短い Blob 値(「バイト文字列」)。ByteString は
str
のサブクラスで、そのコンストラクタへの引数としてエンコードされていないstr
値を取ります。ByteString はデータストアによってインデックスに登録され、フィルタや並べ替え順に使用できます。長さが 1,500 バイトを超える(インデックスに登録されない)バイト文字列には、
Blob
インスタンスを使用します。エンコードされているテキストデータには、str
(インデックスに登録される短い文字列)またはText
(インデックスに登録されない長い文字列)を使用してください。モデル プロパティ:
ByteStringProperty
- class Text(arg=None, encoding=None)
-
長い文字列。これは組み込みの
unicode
型のサブクラスです。arg:
unicode
またはstr
値。arg がstr
の場合は、encoding で指定されたエンコードを使用して解析されます(エンコードが指定されていない場合はascii
が使用されます)。encoding に指定できる値については、標準のエンコードのリストをご覧ください。値が単純な
str
またはunicode
であるエンティティ プロパティとは異なり、Text プロパティの長さは 1,500 バイトを超えても問題ありません。ただし、Text プロパティはインデックスに登録されず、フィルタや並べ替え順には使用できません。モデル プロパティ:
TextProperty
class MyModel(db.Model): text = db.TextProperty() m = MyModel() m.text = db.Text(u"kittens") m.text = db.Text("kittens", encoding="latin-1")
- class Category(tag)
-
カテゴリまたは「タグ」。これは組み込みの
unicode
型のサブクラスです。モデル プロパティ:
CategoryProperty
class MyModel(db.Model): category = db.CategoryProperty() m = MyModel() m.category = db.Category("kittens")
XML では、これは Atom の
Category
要素です。 - class Email(email)
-
メールアドレス。これは組み込みの
unicode
型のサブクラスです。プロパティ クラスも値クラスも、メールアドレスの検証を行わず、値を保存するだけです。
モデル プロパティ:
EmailProperty
class MyModel(db.Model): email_address = db.EmailProperty() m = MyModel() m.email_address = db.Email("larry@example.com")
XML では、これは
gd:email
要素です。 - class GeoPt(lat, lon=None)
-
浮動小数点型の緯度と経度の座標で表される地理的位置。
モデル プロパティ:
GeoPtProperty
XML では、これは
georss:point
要素です。 - class IM(protocol, address=None)
-
インスタント メッセージ ハンドル。
protocol は、インスタント メッセージ サービスの正規 URL です。次のような値を指定できます。
プロトコル 説明 sip SIP/SIMPLE xmpp XMPP/Jabber http://aim.com/ AIM http://icq.com/ ICQ http://messenger.msn.com/ MSN メッセンジャー http://messenger.yahoo.com/ Yahoo メッセンジャー http://sametime.com/ Lotus Sametime http://gadu-gadu.pl/ Gadu-Gadu unknown 不明または未指定 address はハンドルのアドレスです。
モデル プロパティ:
IMProperty
class MyModel(db.Model): im = db.IMProperty() m = MyModel() m.im = db.IM("http://example.com/", "Larry97")
XML では、これは
gd:im
要素です。 - class Link(link)
-
完全修飾 URL。これは組み込みの
unicode
型のサブクラスです。モデル プロパティ:
LinkProperty
class MyModel(db.Model): link = db.LinkProperty() m = MyModel() m.link = db.Link("http://www.google.com/")
XML では、これは Atom の
Link
要素です。 - class PhoneNumber(phone)
-
人が読める形式の電話番号。これは組み込みの
unicode
型のサブクラスです。モデル プロパティ:
PhoneNumberProperty
class MyModel(db.Model): phone = db.PhoneNumberProperty() m = MyModel() m.phone = db.PhoneNumber("1 (206) 555-1212")
XML では、これは
gd.phoneNumber
要素です。 - class PostalAddress(address)
-
住所。これは組み込みの
unicode
型のサブクラスです。モデル プロパティ:
PostalAddressProperty
class MyModel(db.Model): address = db.PostalAddressProperty() m = MyModel() m.address = db.PostalAddress("1600 Ampitheater Pkwy., Mountain View, CA")
XML では、これは
gd:postalAddress
要素です。 - class Rating(rating)
-
ユーザーが 0~100 の整数で指定するコンテンツの評価。これは組み込みの
long
型のサブクラスです。このクラスは、値が 0~100 の整数であることを検証し、値が無効な場合はBadValueError
を生成します。モデル プロパティ:
RatingProperty
class MyModel(db.Model): rating = db.RatingProperty() m = MyModel() m.rating = db.Rating(97)
XML では、これは
gd:rating
要素です。
プロパティ クラス
google.appengine.ext.db
で提供されるすべてのモデル プロパティ クラスは、ベースクラス Property
のサブクラスで、ベース コンストラクタのすべての引数をサポートします。これらの引数については、ベースクラスのドキュメントをご覧ください。
google.appengine.ext.db
パッケージは、次のモデル プロパティ クラスを提供します。
- class BlobProperty(...)
-
解釈されていないバイナリデータのコレクション。
Blob データはバイト文字列です。エンコードを含むテキストデータには、
TextProperty
を使用します。値の型:
Blob
- class BooleanProperty(...)
-
ブール値(
True
またはFalse
)。値の型:
bool
- class ByteStringProperty(verbose_name=None, ...)
-
1,500 バイト以下の短い Blob 値(「バイト文字列」)。
ByteStringProperty
値はインデックスに登録され、フィルタや並べ替え順序で使用できます。StringProperty
とほぼ同じですが、値がエンコードされない点が異なります。バイトはそのまま保存されます。ByteStringProperty
が必須の場合、その値を空の文字列にすることはできません。値の型:
ByteString
- class CategoryProperty(...)
-
カテゴリまたは「タグ」(説明用の単語や語句)。
値の型:
Category
- class DateProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)
-
時刻が指定されていない日付。詳細については、
DateTimeProperty
をご覧ください。値の型:
datetime.date
(内部でdatetime.datetime
に変換) - class DateTimeProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)
-
日時。
auto_now が
True
の場合は、モデル インスタンスがデータストアに保存されるたびに、このプロパティの前の値が上書きされ、プロパティ値が現在の時刻に設定されます。これは、モデル インスタンスの「最終更新」日時を追跡するのに便利です。auto_now_add が
True
の場合は、このプロパティにすでに値が割り当てられている場合を除き、モデル インスタンスが最初にデータストアに保存されるときに、プロパティ値が現在の時刻に設定されます。これは、モデル インスタンスの「作成」日時を保存するのに便利です。日時値は、UTC タイムゾーンを使用して保存され返されます。タイムゾーンの管理方法については、
datetime.datetime
をご覧ください。値の型:
datetime.datetime
- class EmailProperty(...)
-
メールアドレス。
プロパティ クラスも値クラスも、メールアドレスの検証を行わず、値を保存するだけです。
値の型:
Email
- class FloatProperty(...)
-
浮動小数点数。
値の型:
float
- class GeoPtProperty(...)
-
浮動小数点型の緯度と経度の座標で表される地理的位置。
値の型:
GeoPt
- class IMProperty(...)
-
インスタント メッセージ ハンドル。
値の型:
IM
- class IntegerProperty(...)
-
整数値(最大 64 ビット)。
Python
int
値は、保存する前に Pythonlong
値に変換されます。int
として保存された値はlong
として返されます。64 ビットを超える
long
が割り当てられた場合は、下位の 64 ビットのみが保存されます。 - class LinkProperty(...)
-
完全修飾 URL。
値の型:
Link
- class ListProperty(item_type, verbose_name=None, default=None, ...)
-
item_type で指定された型の値のリスト。
クエリでリスト プロパティと値を比較することにより、リストメンバーに対するテストを行います。たとえば、
list_property
=
value
はこの値がリスト内に存在するかどうかをテストし、list_property
<
value
はいずれかのリストメンバーが指定された値より小さいかどうかをテストします。クエリで 2 つのリスト値を比較することはできません。2 つのリストが等価であることをテストする方法は、メンバーである各要素を個別にテストする以外にありません。
item_type は、リスト内の項目の型(Python の型またはクラス)です。リスト値のすべての項目は指定された型であることが必要です。item_type は、データストアの値の型のいずれかにする必要があり、
list
にすることはできません。ListProperty
の値をNone
にすることはできません。ただし、空のリストにすることはできます。None
が default 引数に指定された場合(または default 引数が指定されなかった場合)、このプロパティのデフォルト値は空のリストです。ヒント:
ListProperty
集約型ではProperty
クラスを使用しないため、Property
クラスの自動値や検証などの機能はリスト値のメンバーに対して自動的には適用されません。Property
クラスを使用してメンバー値を検証する場合は、このクラスをインスタンス化し、そのインスタンスのvalidate()
メソッドを値に対して呼び出します。default は、リスト プロパティのデフォルト値です。
None
の場合、デフォルトは空のリストです。リスト プロパティでカスタム検証ツールを定義することにより、空のリストを禁止できます。リスト プロパティとリスト値の詳細については、データ モデリングのページをご覧ください。
値の型: 指定された型の値を持つ Python
list
- class PhoneNumberProperty(...)
-
人が読める形式の電話番号。
値の型:
PhoneNumber
- class PostalAddressProperty(...)
-
住所。
値の型:
PostalAddress
- class RatingProperty()
-
ユーザーが 0~100 の整数で指定するコンテンツの評価。
値の型:
Rating
- class ReferenceProperty(reference_class=None, verbose_name=None, collection_name=None, ...)
-
他のモデル インスタンスへの参照。参照によって、たとえば、このプロパティを持つモデルとこのプロパティによって参照されるモデルの間にある多対 1 の関係を示すことができます。
reference_class は、参照されるモデル インスタンスのモデルクラスです。指定した場合は、このクラスのモデル インスタンスのみをこのプロパティに割り当てることができます。
None
の場合は、任意のモデル インスタンスをこのプロパティの値として指定できます。collection_name は、参照されるモデルクラスに提供されるプロパティの名前です。プロパティの値は、エンティティを参照するすべてのエンティティの
Query
です。collection_name が設定されていない場合は、modelname_set
(参照されるモデルの小文字の名前の後に_set
を追加したもの)が使用されます。注: 同じモデル内に同じモデルクラスを参照する複数のプロパティがある場合は、collection_name を設定する必要があります。そうしないと、デフォルトの名前が生成されたときに
DuplicatePropertyError
が発生します。ReferenceProperty
は、モデル インスタンスをプロパティ値として自動的に参照および逆参照します。つまり、モデル インスタンスを参照プロパティに直接割り当てることができ、そのキーが使用されます。ReferenceProperty
値は、モデル インスタンスと同じように使用できます。この値を最初にこの方法で使用するときに、データストア エンティティがフェッチされ、モデル インスタンスが作成されます。手つかずの参照プロパティによって不要なデータのクエリが実行されることはありません。class Author(db.Model): name = db.StringProperty() class Story(db.Model): author = db.ReferenceProperty(Author) story = db.get(story_key) author_name = story.author.name author = db.get(author_key) stories_by_author = author.story_set.get()
Key
値と同様に、参照プロパティの値が、存在しないデータ エンティティを参照することがあります。参照されているエンティティがデータストアから削除された場合、そのエンティティへの参照は更新されません。存在しないエンティティにアクセスすると、ReferencePropertyResolveError
が発生します。エンティティを削除しても、参照プロパティによって参照されているエンティティは削除されません。
値の型:
db.Key
- class SelfReferenceProperty(verbose_name=None, collection_name=None, ...)
-
同じクラスの別のモデル インスタンスへの参照(
ReferenceProperty
をご覧ください)。値の型:
db.Key
- class StringListProperty(verbose_name=None, default=None, ...)
-
Python
str
またはunicode
(basestring
)の値のリスト プロパティと同様です。 - class StringProperty(verbose_name=None, multiline=False, ...)
-
短い文字列。1,500 バイト以下の Python
str
またはunicode
(basestring
)の値を取ります。StringProperty
値はインデックスに登録され、フィルタや並べ替え順序で使用できます。multiline が
False
の場合は、値にラインフィード文字を含めることができません。djangoforms
ライブラリでは、これを使用してテキスト フィールドとテキスト領域フィールドの違いをデータモデルに適用します。他のライブラリでも同様の目的でこれを使用できます。文字列プロパティが必須の場合、その値を空の文字列にすることはできません。
- class TextProperty()
-
長い文字列。
StringProperty
とは異なり、TextProperty
値の長さは 1,500 バイトを超えても問題ありません。ただし、TextProperty
値はインデックスに登録されず、フィルタや並べ替え順には使用できません。TextProperty
値は、テキスト エンコードを使用してテキストを保存します。バイナリデータについては、BlobProperty
を使用してください。テキスト プロパティが必須の場合、その値を空の文字列にすることはできません。
値の型:
Text
- class TimeProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)
-
日付を含まない時刻。Python 標準ライブラリの
datetime.time
値を取ります。詳細については、DateTimeProperty
をご覧ください。値の型:
datetime.time
(内部でdatetime.datetime
に変換) - class UserProperty(verbose_name=None, auto_current_user=False, auto_current_user_add=False, ...)
-
重要: メールアドレスとユーザーの一意の ID が含まれているため、
UserProperty
を保存しないことを強くおすすめします。ユーザーがメールアドレスを変更すると、そのユーザーの古いメールアドレス(User
に格納されている)と新しいUser
の値を比較したときに一致しません。Google アカウントを持つユーザー。
auto_current_user が
True
の場合は、モデル インスタンスがデータストアに保存されるたびに、このプロパティの前の値が上書きされ、プロパティ値が現在ログインしているユーザーに設定されます。これは、モデル インスタンスを変更したユーザーを追跡するのに便利です。auto_current_user_add が
True
の場合は、このプロパティにすでに値が割り当てられている場合を除き、モデル インスタンスが最初にデータストアに保存されるときに、プロパティ値が現在ログインしているユーザーに設定されます。これは、モデル インスタンスを作成したユーザー(後でモデル インスタンスを変更したユーザーとは異なる可能性がある)を追跡するのに便利です。UserProperty にはデフォルト値を指定できません。デフォルト値は、モデルクラスを最初にインポートしたときに設定され、インポート キャッシュのため現在ログインしているユーザーにならない場合があります。
値の型:
users.User