Catatan: Developer yang membuat aplikasi baru sangat dianjurkan untuk menggunakan Library Klien NDB, yang memiliki beberapa manfaat dibandingkan dengan library klien ini, seperti menyimpan entity dalam cache secara otomatis melalui Memcache API. Jika saat ini Anda menggunakan Library Klien DB versi lama, baca Panduan Migrasi DB ke NDB
App Engine Datastore mendukung serangkaian jenis nilai yang tetap untuk properti di entity data.
Class
Property
dapat menentukan jenis baru yang dikonversi ke dan dari jenis nilai yang mendasarinya, dan jenis nilai dapat digunakan langsung dengan
properti dinamis
Expando
dan
ListProperty
menggabungkan model properti.
Tabel berikut menjelaskan class Properti yang nilainya berhubungan langsung dengan jenis data yang mendasarinya. Salah satu jenis nilai ini dapat digunakan di properti dinamis Expando atau jenis gabungan ListProperty.
Jenis Nilai Datastore
Nilai properti entity Datastore dapat berupa salah satu dari jenis berikut ini. Lihat di atas untuk daftar class
Property
yang sesuai untuk digunakan dengan
definisi
Model
.
Selain jenis standar Python dan
users.User
,
semua class yang dijelaskan di bagian ini disediakan oleh modul google.appengine.ext.db
.
str
atauunicode
-
String pendek (1.500 byte atau kurang).
Nilai
str
diasumsikan sebagai teks yang dienkode dengan codecascii
, dan dikonversi menjadi nilaiunicode
sebelum disimpan. Nilai ditampilkan oleh datastore sebagai nilaiunicode
. Untuk string pendek yang menggunakan codec lain, gunakan nilaiunicode
.String pendek diindeks oleh datastore, dan dapat digunakan dalam filter dan tata urutan. Untuk string teks yang lebih panjang dari 1.500 byte (yang tidak diindeks), gunakan instance
Text
. Untuk string byte yang tidak dienkode dengan panjang lebih dari 1.500 byte (juga tidak diindeks), gunakan instanceBlob
. Untuk string byte non-tekstual yang tidak dienkode hingga 1.500 byte (bukan karakter) yang harus diindeks, gunakan instanceByteString
.Properti model:
StringProperty
bool
-
Nilai boolean (
True
atauFalse
).Properti model:
BooleanProperty
int
ataulong
-
Nilai bilangan bulat, hingga 64 bit.
Nilai
int
Python dikonversi ke nilailong
Python sebelum penyimpanan. Nilai yang disimpan sebagaiint
akan ditampilkan sebagailong
.Jika
long
yang lebih besar dari 64 bit ditetapkan, hanya 64 bit yang paling tidak signifikan yang akan disimpan.Properti model:
IntegerProperty
float
-
Angka floating point
Properti model:
FloatProperty
datetime.datetime
-
Tanggal dan waktu Lihat dokumentasi modul
datetime
.Jika nilai
datetime
memiliki atributtzinfo
, nilai tersebut akan dikonversi ke zona waktu UTC untuk penyimpanan. Nilai kembali dari datastore sebagai UTC, dengantzinfo
None
. Aplikasi yang mengharuskan nilai tanggal dan waktu berada dalam zona waktu tertentu harus menetapkantzinfo
dengan benar saat memperbarui nilai, dan mengonversi nilai ke zona waktu tersebut saat mengakses nilai.Beberapa library menggunakan variabel lingkungan
TZ
untuk mengontrol zona waktu yang diterapkan pada nilai tanggal-waktu. App Engine menetapkan variabel lingkungan ini ke"UTC"
. Perhatikan, mengubah variabel ini dalam aplikasi tidak akan mengubah perilaku beberapa fungsi tanggal/waktu karena perubahan pada variabel lingkungan tidak terlihat di luar kode Python.Jika hanya mengonversi nilai ke dan dari zona waktu tertentu, Anda dapat menerapkan
datetime.tzinfo
kustom untuk mengonversi nilai dari datastore: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())
Lihat dokumentasi modul
datetime
(termasukdatetime.tzinfo
). Lihat juga modul pihak ketigapytz
, tetapi perhatikan bahwa distribusipytz
memiliki banyak file.Class properti model
DateTimeProperty
mencakup fitur seperti kemampuan untuk otomatis menggunakan tanggal dan waktu penyimpanan instance model. Ini adalah fitur model, dan tidak tersedia pada nilai datastore mentah (seperti dalam properti dinamisExpando
).Properti model:
DateTimeProperty
,DateProperty
,TimeProperty
list
-
Daftar nilai, yang masing-masing merupakan salah satu jenis data yang didukung.
Jika
list
digunakan sebagai nilai properti dinamisExpando
, properti ini tidak boleh berupa daftar kosong. Hal ini disebabkan oleh cara penyimpanan nilai daftar: Jika properti daftar tidak memiliki item, properti tersebut tidak memiliki representasi di datastore. Anda dapat menggunakan properti statis dan classListProperty
untuk merepresentasikan nilai daftar kosong untuk properti.Properti model:
ListProperty
-
db.Key
-
Kunci untuk entity datastore lainnya.
Catatan: String kunci dibatasi hingga 1.500 byte atau kurang.
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)
Properti model:
ReferenceProperty
,SelfReferenceProperty
-
blobstore.BlobKey
-
Kunci untuk nilai Blobstore, yang dihasilkan oleh Blobstore saat nilai diupload.
Properti model:
blobstore.BlobReferenceProperty
-
users.User
-
Pengguna dengan Akun Google.
Nilai
user.User
di datastore tidak akan diperbarui jika pengguna mengubah alamat email mereka. Oleh karena itu, sebaiknya jangan menyimpanusers.User
sebagai nilaiUserProperty
karena sudah berisi alamat email beserta ID uniknya. Jika pengguna mengubah alamat email, lalu Anda membandingkanuser.User
lama yang disimpan dengan nilaiuser.User
yang baru, nilai tersebut tidak akan cocok. Sebagai gantinya, gunakanuser_id()
dari nilaiuser.User
sebagai ID unik yang stabil milik pengguna.Properti model:
UserProperty
- class Blob(arg=None)
-
Data biner, sebagai string byte. Ini adalah subclass dari jenis
str
bawaan.Properti Blob tidak diindeks dan tidak dapat digunakan dalam filter atau tata urutan.
Blob digunakan untuk data biner, misalnya gambar. Fungsi ini mengambil nilai
str
, tetapi nilai ini disimpan sebagai string byte dan tidak dienkode sebagai teks. Gunakan instanceText
untuk data teks besar.Properti model:
BlobProperty
class MyModel(db.Model): blob = db.BlobProperty() m = MyModel() m.blob = db.Blob(open("image.png", "rb").read())
Dalam XML, blob berenkode base-64, terlepas dari apakah blob berisi data biner atau tidak.
- class ByteString(arg)
-
Nilai blob pendek ("string byte") berukuran 1.500 byte atau kurang. ByteString adalah subclass
str
, dan menggunakan nilaistr
yang tidak dienkode sebagai argumen untuk konstruktornya.ByteString diindeks oleh datastore, dan dapat digunakan dalam filter dan tata urutan. Untuk string byte yang lebih panjang dari 1.500 byte (yang tidak diindeks), gunakan instance
Blob
. Untuk data teks yang dienkode, gunakanstr
(pendek, diindeks) atauText
(panjang, tidak diindeks).Properti model:
ByteStringProperty
- class Teks(arg=Tidak ada, enkode=Tidak ada)
-
String panjang. Ini adalah subclass dari jenis
unicode
bawaan.arg nilai
unicode
ataustr
. Jika argumen adalahstr
, lalu diuraikan dengan encoding yang ditentukan oleh encoding , atauascii
jika tidak ada encoding yang ditentukan. Lihat daftar encoding standar untuk mengetahui kemungkinan nilai encoding.Tidak seperti properti entity yang nilainya adalah
str
atauunicode
sederhana, properti Teks dapat memiliki panjang lebih dari 1.500 byte. Namun, properti Teks tidak diindeks, dan tidak dapat digunakan dalam filter atau tata urutan.Properti model:
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 Kategori(tag)
-
Kategori atau "tag". Ini adalah subclass dari jenis
unicode
bawaan.Properti model:
CategoryProperty
class MyModel(db.Model): category = db.CategoryProperty() m = MyModel() m.category = db.Category("kittens")
Dalam XML, ini adalah elemen
Category
Atom. - class Email(email)
-
Alamat email. Ini adalah subclass dari jenis
unicode
bawaan.Baik class properti maupun class nilai tidak melakukan validasi alamat email, keduanya hanya menyimpan nilai.
Properti model:
EmailProperty
class MyModel(db.Model): email_address = db.EmailProperty() m = MyModel() m.email_address = db.Email("larry@example.com")
Dalam XML, ini adalah elemen
gd:email
. - class GeoPt(lat, lat=Tidak ada)
-
Titik geografis yang diwakili oleh koordinat lintang dan bujur floating point.
Properti model:
GeoPtProperty
Dalam XML, ini adalah elemen
georss:point
. - class IM(protokol, alamat=Tidak ada)
-
Handle fitur pesan instan.
protokol adalah URL kanonis layanan fitur pesan instan. Beberapa kemungkinan nilai:
Protocol Deskripsi sip SIP/SIMPLE xmpp XMPP/Jabber http://aim.com/ AIM http://icq.com/ ICQ http://messenger.msn.com/ MSN Messenger http://messenger.yahoo.com/ Yahoo Messenger http://sametime.com/ Lotus Sametime http://gadu-gadu.pl/ Gadu-Gadu tidak diketahui Tidak diketahui atau tidak ditentukan alamat adalah alamat handle.
Properti model:
IMProperty
class MyModel(db.Model): im = db.IMProperty() m = MyModel() m.im = db.IM("http://example.com/", "Larry97")
Dalam XML, ini adalah elemen
gd:im
. - class Link(link)
-
URL yang sepenuhnya memenuhi syarat. Ini adalah subclass dari jenis
unicode
bawaan.Properti model:
LinkProperty
class MyModel(db.Model): link = db.LinkProperty() m = MyModel() m.link = db.Link("http://www.google.com/")
Dalam XML, ini adalah elemen
Link
Atom. - class PhoneNumber(ponsel)
-
Nomor telepon yang dapat dibaca manusia. Ini adalah subclass dari jenis
unicode
bawaan.Properti model:
PhoneNumberProperty
class MyModel(db.Model): phone = db.PhoneNumberProperty() m = MyModel() m.phone = db.PhoneNumber("1 (206) 555-1212")
Dalam XML, ini adalah elemen
gd.phoneNumber
. - class PostalAddress(alamat)
-
Alamat pos Ini adalah subclass dari jenis
unicode
bawaan.Properti model:
PostalAddressProperty
class MyModel(db.Model): address = db.PostalAddressProperty() m = MyModel() m.address = db.PostalAddress("1600 Ampitheater Pkwy., Mountain View, CA")
Dalam XML, ini adalah elemen
gd:postalAddress
. - class Rating(rating)
-
Rating yang diberikan pengguna untuk suatu konten, dalam bentuk bilangan bulat antara 0 dan 100. Ini adalah subclass dari jenis
long
bawaan. Class ini memvalidasi bahwa nilai berupa bilangan bulat antara 0 dan 100, serta memunculkanBadValueError
jika nilainya tidak valid.Properti model:
RatingProperty
class MyModel(db.Model): rating = db.RatingProperty() m = MyModel() m.rating = db.Rating(97)
Dalam XML, ini adalah elemen
gd:rating
.
Class Properti
Semua class properti model yang disediakan oleh google.appengine.ext.db
merupakan subclass dari class dasar
Property
,
dan mendukung semua argumen konstruktor dasar. Lihat dokumentasi class dasar untuk informasi tentang argumen tersebut.
Paket google.appengine.ext.db
menyediakan class properti model berikut:
- class BlobProperty(...)
-
Kumpulan data biner yang tidak diinterpretasikan.
Data Blob adalah string byte. Untuk data teks, yang mungkin melibatkan encoding, gunakan
TextProperty
.Jenis nilai:
Blob
- class BooleanProperty(...)
-
Nilai boolean (
True
atauFalse
).Jenis nilai:
bool
- class ByteStringProperty(verbose_name=Tidak ada, ...)
-
Nilai blob pendek ("string byte") berukuran 1.500 byte atau kurang.
Nilai
ByteStringProperty
diindeks dan dapat digunakan dalam filter dan tata urutan.Seperti
StringProperty
, kecuali bahwa nilai tersebut tidak dienkode dengan cara apa pun. Byte disimpan secara persis sama.Jika
ByteStringProperty
wajib ada, nilainya tidak boleh berupa string kosong.Jenis nilai:
ByteString
- class CategoryProperty(...)
-
Kategori atau "tag", kata atau frasa deskriptif.
Jenis nilai:
Category
- class DateProperty(verbose_name=Tidak ada, verbose_name=Salah, verbose_name=Salah, ...)
-
Tanggal tanpa waktu; lihat
DateTimeProperty
untuk informasi selengkapnya.Jenis nilai:
datetime.date
; dikonversi secara internal menjadidatetime.datetime
- class DateTimeProperty(verbose_name=Tidak ada, verbose_name=Salah, verbose_name=Salah, ...)
-
Tanggal dan waktu
Jika auto_now adalah
True
, nilai properti ditetapkan ke waktu saat ini setiap kali instance model disimpan di datastore, yang menimpa nilai properti sebelumnya. Hal ini berguna untuk melacak tanggal dan waktu "terakhir diubah" untuk instance model.Jika auto_now_add adalah
True
, nilai properti ditetapkan ke waktu saat ini saat pertama kali instance model disimpan di datastore, kecuali jika properti telah diberi nilai. Hal ini berguna untuk menyimpan tanggal dan waktu "dibuat" untuk instance model.Nilai tanggal-waktu disimpan sebagai dan ditampilkan menggunakan zona waktu UTC. Lihat
datetime.datetime
untuk pembahasan tentang cara mengelola zona waktu.Jenis nilai:
datetime.datetime
- class EmailProperty(...)
-
Alamat email.
Baik class properti maupun class nilai tidak melakukan validasi alamat email, keduanya hanya menyimpan nilai.
Jenis nilai:
Email
- class FloatProperty(...)
-
Angka floating point
Jenis nilai:
float
- class GeoPtProperty(...)
-
Titik geografis yang diwakili oleh koordinat lintang dan bujur floating point.
Jenis nilai:
GeoPt
- class IMProperty(...)
-
Handle fitur pesan instan.
Jenis nilai:
IM
- class IntegerProperty(...)
-
Nilai bilangan bulat, hingga 64 bit.
Nilai
int
Python dikonversi ke nilailong
Python sebelum penyimpanan. Nilai yang disimpan sebagaiint
akan ditampilkan sebagailong
.Jika
long
yang lebih besar dari 64 bit ditetapkan, hanya 64 bit yang paling tidak signifikan yang akan disimpan. - class LinkProperty(...)
-
URL yang sepenuhnya memenuhi syarat.
Jenis nilai:
Link
- class ListProperty(item_type, item_type=Tidak ada, item_type=Tidak ada, ...)
-
Daftar nilai jenis yang ditentukan oleh item_type.
Dalam kueri, membandingkan properti daftar dengan nilai akan menjalankan pengujian terhadap anggota daftar:
list_property
=
value
menguji apakah nilai muncul di mana pun dalam daftar,list_property
<
value
menguji apakah ada anggota daftar yang lebih kecil dari nilai yang diberikan, dan seterusnya.Kueri tidak dapat membandingkan dua nilai daftar. Tidak ada cara untuk menguji dua daftar untuk kesetaraan tanpa menguji setiap elemen untuk keanggotaan secara terpisah.
item_type adalah jenis item dalam daftar, sebagai jenis atau class Python. Semua item dalam nilai daftar harus dari jenis yang ditentukan. item_type harus merupakan salah satu jenis nilai datastore, dan tidak boleh
list
.Nilai
ListProperty
tidak bolehNone
. Namun, jenis data ini dapat berupa daftar kosong. JikaNone
ditentukan untuk argumen default (atau saat argumen default tidak ditentukan), nilai default properti adalah daftar kosong.Tips: Karena jenis agregat
ListProperty
tidak menggunakan classProperty
, fitur classProperty
seperti nilai otomatis dan validasi tidak diterapkan secara otomatis kepada anggota dari nilai daftar. Jika ingin memvalidasi nilai anggota menggunakan classProperty
, Anda dapat membuat instance class dan memanggil metodevalidate()
pada nilai.default adalah nilai default untuk properti daftar. Jika
None
, defaultnya adalah daftar kosong. Properti daftar dapat menentukan validator kustom untuk melarang daftar kosong.Lihat halaman Pemodelan Data untuk mengetahui informasi selengkapnya tentang properti dan nilai daftar.
Jenis nilai: Python
list
dari nilai yang ditentukan - class PhoneNumberProperty(...)
-
Nomor telepon yang dapat dibaca manusia.
Jenis nilai:
PhoneNumber
- class PostalAddressProperty(...)
-
Alamat pos
Jenis nilai:
PostalAddress
- class RatingProperty()
-
Rating yang diberikan pengguna untuk suatu konten, dalam bentuk bilangan bulat antara 0 dan 100.
Jenis nilai:
Rating
- class ReferenceProperty(reference_class=Tidak ada, reference_class=Tidak ada, reference_class=Tidak ada, ...)
-
Referensi ke instance model lain. Misalnya, referensi dapat menunjukkan hubungan many-to-one antara model dengan properti dan model yang dirujuk oleh properti.
reference_class adalah class model dari instance model yang dirujuk. Jika ditentukan, hanya instance model class yang dapat ditetapkan ke properti ini. Jika
None
, instance model apa pun dapat berupa nilai properti ini.collection_name adalah nama properti yang akan diberikan ke class model yang direferensikan. Nilai properti adalah
Query
untuk semua entity yang merujuk entity tersebut. Jika collection_name tidak ditetapkan,modelname_set
(dengan nama model yang dirujuk dalam huruf kecil dan_set
ditambahkan) akan digunakan.Catatan: collection_name harus ditetapkan jika ada beberapa properti dalam model yang sama yang merujuk ke class model yang sama. Jika tidak,
DuplicatePropertyError
akan dimunculkan saat nama default dibuat.ReferenceProperty
secara otomatis merujuk dan mendereferensi instance model sebagai nilai properti: instance model dapat langsung ditetapkan ke properti referensi, dan kuncinya akan digunakan. NilaiReferenceProperty
dapat digunakan seolah-olah merupakan instance model, dan entity datastore akan diambil dan instance model dibuat saat pertama kali digunakan dengan cara ini. Properti referensi yang belum tersentuh tidak mengajukan kueri untuk data yang tidak diperlukan.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()
Seperti halnya nilai
Key
, nilai properti referensi dapat merujuk ke entity data yang tidak ada. Jika entity yang dirujuk dihapus dari datastore, referensi ke entitas tidak akan diperbarui. Mengakses entity yang tidak ada akan memunculkanReferencePropertyResolveError
.Menghapus entity tidak akan menghapus entity yang dirujuk oleh properti referensi.
Jenis nilai:
db.Key
- class SelfReferenceProperty(verbose_name=Tidak ada, verbose_name=Tidak ada, ...)
-
Referensi ke instance model lain dari class yang sama (lihat
ReferenceProperty
).Jenis nilai:
db.Key
- class StringListProperty(verbose_name=Tidak ada, verbose_name=Tidak ada, ...)
-
Mirip dengan properti daftar
str
Python atau nilaiunicode
(basestring
). - class StringProperty(verbose_name=Tidak ada, verbose_name=Salah, ...)
-
String pendek. Memerlukan nilai Python
str
atauunicode
(basestring
) 1.500 byte atau kurang.Nilai
StringProperty
diindeks dan dapat digunakan dalam filter dan tata urutan.Jika multiline adalah
False
, nilai tidak dapat menyertakan karakter linefeed. Librarydjangoforms
menggunakannya untuk menerapkan perbedaan antara kolom teks dan kolom textarea dalam model data, dan library lain dapat menggunakannya untuk tujuan serupa.Jika properti string diperlukan, nilainya tidak boleh berupa string kosong.
- class TextProperty()
-
String panjang.
Tidak seperti
StringProperty
, nilaiTextProperty
dapat memiliki panjang lebih dari 1.500 byte. Namun, nilaiTextProperty
tidak diindeks dan tidak dapat digunakan dalam filter atau tata urutan.Nilai
TextProperty
menyimpan teks dengan encoding teks. Untuk data biner, gunakanBlobProperty
.Jika properti teks diperlukan, nilainya tidak boleh berupa string kosong.
Jenis nilai:
Text
- class TimeProperty(verbose_name=None, auto_now=Salah, auto_now_add=Salah, ...)
-
Waktu tanpa tanggal. Mengambil nilai
datetime.time
library standar Python; lihatDateTimeProperty
untuk informasi selengkapnya.Jenis nilai:
datetime.time
; dikonversi secara internal menjadidatetime.datetime
- class UserProperty(verbose_name=None, auto_current_user=False, auto_current_user_add=False, ...)
-
Penting: Sebaiknya jangan menyimpan
UserProperty
karena berisi alamat email dan ID unik pengguna. Jika pengguna mengubah alamat emailnya dan Anda membandingkanUser
lamanya yang tersimpan dengan nilaiUser
yang baru, nilai tersebut tidak akan cocok.Pengguna dengan Akun Google.
Jika auto_current_user adalah
True
, nilai properti ditetapkan ke pengguna yang sedang login setiap kali instance model disimpan di datastore, yang menimpa nilai properti sebelumnya. Hal ini berguna untuk melacak pengguna yang mengubah instance model.Jika auto_current_user_add adalah
True
, nilai properti akan ditetapkan ke pengguna yang sedang login saat pertama kali instance model disimpan di datastore, kecuali jika properti tersebut telah diberi nilai. Hal ini berguna untuk melacak pengguna mana yang membuat instance model, yang mungkin bukan pengguna yang sama yang mengubahnya di lain waktu.UserProperty tidak menerima nilai default. Nilai default ditetapkan saat class model pertama kali diimpor, dan dengan caching impor mungkin bukan pengguna yang login saat ini.
Jenis nilai:
users.User