Entity, Properti, dan Kunci

Catatan: Developer yang membangun aplikasi baru sangat dianjurkan untuk menggunakan Library Klien NDB, yang memiliki beberapa manfaat jika dibandingkan dengan library klien ini, seperti caching entity otomatis melalui Memcache API. Jika saat ini Anda menggunakan Library Klien DB versi lama, baca Panduan Migrasi DB ke NDB

Objek data di Datastore disebut sebagai entity. Entity memiliki satu atau beberapa properti yang telah diberi nama, yang masing-masing dapat memiliki satu atau beberapa nilai. Entity dari jenis yang sama tidak harus memiliki properti yang sama, dan nilai suatu entity untuk properti tertentu tidak semuanya harus memiliki jenis data yang sama. (Jika perlu, aplikasi dapat membuat dan menerapkan pembatasan tersebut dalam model datanya sendiri.)

Datastore mendukung berbagai jenis data untuk nilai properti. Hal ini mencakup, antara lain:

• Bilangan bulat
• Angka floating-point
• String
• Tanggal
• Data biner

Untuk mengetahui daftar lengkap jenis, lihat Jenis nilai dan properti.

Setiap entity dalam Datastore memiliki kunci yang secara unik mengidentifikasinya. Kunci ini terdiri dari komponen berikut:

• Namespace entity, yang memungkinkan multitenancy
• Jenis entity, yang mengategorikannya untuk tujuan kueri Datastore
• ID untuk masing-masing entity, yang dapat berupa
  • string nama kunci
  • ID numerik bilangan bulat
• Jalur ancestor opsional yang mencari entity dalam hierarki Datastore

Jangan menamai properti sebagai "key". Nama ini dikhususkan untuk properti khusus yang digunakan untuk menyimpan kunci Model. Meskipun dapat berfungsi secara lokal, properti yang bernama "key" akan mencegah deployment ke App Engine.

Aplikasi dapat mengambil setiap entity dari Datastore menggunakan kunci entity, atau mengambil satu atau beberapa entity dengan mengeluarkan kueri berdasarkan kunci entity atau nilai properti.

Python App Engine SDK menyertakan library pemodelan data untuk menampilkan entity Datastore sebagai instance class Python, serta untuk menyimpan dan mengambil instance tersebut di Datastore.

Datastore sendiri tidak menerapkan batasan apa pun pada struktur entity, seperti apakah properti tertentu memiliki nilai dari jenis tertentu; tugas ini diserahkan ke aplikasi dan library pemodelan data.

Jenis dan ID

Setiap entity Datastore memiliki jenis tertentu, yang mengategorikan entity untuk tujuan kueri: misalnya, aplikasi sumber daya manusia mungkin mewakili setiap karyawan di sebuah perusahaan dengan entity jenis Employee. Di Python Datastore API, jenis entity ditentukan oleh class modelnya, yang Anda tentukan dalam aplikasi sebagai subclass dari class library pemodelan data db.Model. Nama class model menjadi jenis entity yang termasuk di dalamnya. Semua nama jenis yang dimulai dengan dua garis bawah (__) dicadangkan dan tidak dapat digunakan.

Contoh berikut membuat entity jenis Employee, mengisi nilai propertinya, dan menyimpannya ke Datastore:

import datetime
from google.appengine.ext import db

class Employee(db.Model):
  first_name = db.StringProperty()
  last_name = db.StringProperty()
  hire_date = db.DateProperty()
  attended_hr_training = db.BooleanProperty()

employee = Employee(first_name='Antonio',
                    last_name='Salieri')

employee.hire_date = datetime.datetime.now().date()
employee.attended_hr_training = True

employee.put()

Class Employee mendeklarasikan empat properti untuk model data: first_name, last_name, hire_date, dan attended_hr_training. Superclass Model memastikan bahwa atribut objek Employee sesuai dengan model ini: misalnya, upaya untuk menetapkan nilai string ke atribut hire_date akan menghasilkan error runtime karena model data untuk hire_date dideklarasikan sebagai db.DateProperty.

Selain jenis, setiap entity memiliki ID, yang ditetapkan saat entity dibuat. Karena ID tersebut merupakan bagian dari kunci entity, ID-nya dikaitkan secara permanen dengan entity dan tidak dapat diubah. ID tersebut dapat ditetapkan dengan salah satu dari dua cara berikut:

• Aplikasi Anda dapat menentukan string key name-nya sendiri untuk entity.
• Anda dapat meminta Datastore untuk menetapkan ID numerik bilangan bulat ke entity secara otomatis.

Untuk menetapkan nama kunci entity, berikan argumen bernama key_name ke konstruktor class model saat Anda membuat entity:

# Create an entity with the key Employee:'asalieri'.
employee = Employee(key_name='asalieri')

Catatan:

• Nama kunci tidak boleh diawali dan diakhiri dengan dua garis bawah (__*__)
• Selain argumen seperti key_name, konstruktor Model menerima nilai awal untuk properti sebagai argumen kata kunci. Oleh karena itu, memiliki properti bernama key_name akan mempersulit Anda.

Untuk informasi selengkapnya, lihat Nama Properti yang Tidak Diizinkan.

Agar Datastore menetapkan ID numerik secara otomatis, hilangkan argumen key_name:

# Create an entity with a key such as Employee:8261.
employee = Employee()

Menetapkan ID

Datastore dapat dikonfigurasi untuk menghasilkan ID otomatis menggunakan dua kebijakan ID otomatis yang berbeda:

• Kebijakan default menghasilkan urutan acak dari ID yang tidak digunakan yang kira-kira didistribusikan secara seragam. Setiap ID dapat memiliki maksimal 16 digit desimal.
• Kebijakan legacy membuat urutan ID bilangan bulat yang lebih kecil dan tidak berurutan.

Jika Anda ingin menampilkan ID entity kepada pengguna, dan/atau bergantung pada urutannya, sebaiknya Anda menggunakan alokasi manual.

Catatan: Daripada menggunakan string nama kunci atau menghasilkan ID numerik secara otomatis, aplikasi lanjutan terkadang ingin menetapkan ID numerik-nya sendiri secara manual ke entity yang dibuatnya. Namun, perhatikan bahwa tidak ada yang dapat mencegah Datastore menetapkan salah satu ID numerik manual Anda ke entity lain. Satu-satunya cara untuk menghindari konflik tersebut adalah dengan membuat aplikasi Anda mendapatkan blok ID dengan metode allocate_ids() atau allocate_ids_async(). Generator ID otomatis Datastore akan mencatat ID yang telah dialokasikan dengan metode ini dan akan menghindari penggunaannya kembali untuk entity lain, sehingga Anda dapat menggunakan ID tersebut dengan aman tanpa terjadi duplikasi.

Datastore menghasilkan urutan acak dari ID yang tidak digunakan yang kira-kira didistribusikan secara seragam. Setiap ID dapat memiliki maksimal 16 digit desimal.

Jalur ancestor

Entity dalam Cloud Datastore membentuk ruang yang terstruktur secara hierarkis, yang menyerupai struktur direktori sistem file. Saat membuat entity, Anda dapat memilih untuk menetapkan entity lain sebagai parent;; entity barunya adalah parent; dari parent entity tersebut (perlu diperhatikan bahwa tidak seperti dalam sistem file, parent entity tidak harus benar-benar ada). Entity tanpa parent adalah root entity. Kaitan entity dan induknya bersifat permanen, dan tidak dapat diubah setelah entity tersebut dibuat. Cloud Datastore tidak akan pernah menetapkan ID numerik yang sama ke dua entity dengan parent yang sama, atau ke dua root entity (yang tidak memiliki parent).

Induk, induk dari induk, dan seterusnya dari suatu entity secara rekursif adalah ancestor-nya; turunannya, turunan dari turunannya, dan seterusnya adalah turunannya. Root entity dan semua turunannya termasuk dalam entity group yang sama. Urutan entity yang dimulai dengan root entity dan berlanjut dari parent ke turunan, yang mengarah ke entity tertentu, merupakan jalur ancestor entity tersebut. Kunci lengkap yang mengidentifikasi entity terdiri dari urutan pasangan jenis-ID yang menentukan jalur ancestor-nya dan berakhir dengan entity itu sendiri:

[Person:GreatGrandpa, Person:Grandpa, Person:Dad, Person:Me]

Untuk root entity, jalur ancestor kosong dan kuncinya hanya terdiri dari jenis dan ID entity itu sendiri:

[Person:GreatGrandpa]

Konsep ini diilustrasikan oleh diagram berikut:

Untuk menetapkan parent entity, gunakan argumen parent ke konstruktor class model saat membuat entity turunan. Nilai argumen ini dapat berupa parent entity itu sendiri atau kuncinya; Anda bisa mendapatkan kunci dengan memanggil metode key() parent entity. Contoh berikut membuat entity jenis Address dan menunjukkan dua cara menetapkan entity Employee sebagai parent-nya:

# Create Employee entity
employee = Employee()
employee.put()

# Set Employee as Address entity's parent directly...
address = Address(parent=employee)

# ...or using its key
e_key = employee.key()
address = Address(parent=e_key)

# Save Address entity to datastore
address.put()

Transaksi dan entity group

Setiap upaya untuk membuat, memperbarui, atau menghapus entity terjadi dalam konteks transaksi. Satu transaksi dapat mencakup sejumlah operasi tersebut. Untuk menjaga konsistensi data, transaksi tersebut memastikan bahwa semua operasi yang ada di dalamnya diterapkan ke Datastore sebagai unit atau, jika salah satu operasi gagal, bahwa tidak ada satu pun operasi yang diterapkan. Selain itu, semua pembacaan dengan konsistensi kuat (kueri atau pembacaan ancestor) yang dilakukan dalam transaksi yang sama akan melihat snapshot data yang konsisten.

Catatan: Jika aplikasi Anda menerima pengecualian saat mencoba meng-commit transaksi, bukan berarti transaksi tersebut gagal. Anda dapat menerima pengecualian Timeout, TransactionFailedError, atau InternalError meskipun transaksi telah di-commit dan pada akhirnya akan berhasil diterapkan. Jika memungkinkan, susun transaksi Datastore Anda sehingga hasil akhirnya tidak akan terpengaruh saat transaksi yang sama diterapkan lebih dari sekali.

Seperti yang telah disebutkan di atas, entity group adalah serangkaian entity yang terhubung melalui ancestry ke elemen root yang sama. Pengaturan data ke dalam entity group dapat membatasi transaksi yang dapat dilakukan:

• Semua data yang diakses oleh transaksi harus berada dalam maksimal 25 entity group.
• Jika Anda ingin menggunakan kueri dalam transaksi, data Anda harus diatur ke dalam entity group sedemikian rupa sehingga Anda dapat menentukan filter ancestor yang akan cocok dengan data yang tepat.
• Ada batas throughput operasi tulis sekitar satu transaksi per detik dalam satu entity group. Batasan ini diberikan karena Datastore melakukan replikasi sinkron tanpa master untuk setiap entity group di area geografis yang luas guna memberikan keandalan dan fault tolerance yang tinggi.

Dalam banyak penerapan, Anda dapat menggunakan konsistensi tertunda (yaitu kueri non-ancestor yang mencakup beberapa entity group, yang terkadang menampilkan data yang sedikit usang) saat mengambil pandangan yang luas tentang data yang tidak terkait, kemudian menggunakan konsistensi yang kuat (kueri ancestor atau get dari satu entity) saat melihat atau mengedit satu set data yang sangat terkait. Dalam penerapan semacam itu, sebaiknya Anda menggunakan entity group yang terpisah untuk setiap set data yang sangat terkait. Untuk informasi selengkapnya, lihat Membuat Struktur untuk Konsistensi Kuat.

Catatan: Jangan menyimpan informasi sensitif di kunci entity group. Kunci entity group dapat dipertahankan setelah entity group dihapus untuk memberikan layanan yang cepat dan andal di seluruh Datastore.

Properti dan jenis nilai

Nilai data yang terkait dengan entity terdiri dari satu atau beberapa properti. Setiap properti memiliki nama dan satu atau beberapa nilai. Properti dapat memiliki nilai yang berisi lebih dari satu jenis, dan dua entity dapat memiliki nilai dari jenis yang berbeda untuk properti yang sama. Properti dapat diindeks atau tidak diindeks (kueri yang mengurutkan atau memfilter pada properti P akan mengabaikan entity jika P tidak diindeks). Entity dapat memiliki maksimal 20.000 properti yang diindeks.

Catatan: Properti dengan beberapa nilai dapat berguna, misalnya, saat menjalankan kueri dengan filter kesetaraan: entity memenuhi kueri jika salah satu nilainya untuk properti cocok dengan nilai yang ditentukan di filter. Untuk mengetahui detail selengkapnya tentang properti multi-nilai, termasuk masalah yang harus Anda ketahui, lihat halaman Kueri Datastore.

Jenis nilai berikut ini didukung:

Jenis nilai	Jenis Python	Tata urutan	Notes
Bilangan Bulat	int long	Angka	Bilangan bulat 64-bit, ditandai
Angka floating-point	float	Angka	Presisi ganda 64-bit, IEEE 754
Boolean	bool	False<True
String teks (singkat)	str unicode	Unicode (str diperlakukan sebagai ASCII)	Hingga 1.500 byte
String teks (panjang)	db.Text	Tidak ada	Hingga 1 megabyte Tidak diindeks
String byte (pendek)	db.ByteString	Urutan byte	Hingga 1.500 byte
String byte (panjang)	db.Blob	Tidak ada	Hingga 1 megabyte Tidak diindeks
Tanggal dan waktu	datetime.date datetime.time datetime.datetime	Kronologis
Titik geografis	db.GeoPt	Berdasarkan lintang, lalu bujur
Alamat pos	db.PostalAddress	Unicode
Nomor telepon	db.PhoneNumber	Unicode
Alamat email	db.Email	Unicode
Pengguna Akun Google	users.User	Alamat email berdasarkan urutan Unicode
Handle fitur pesan instan	db.IM	Unicode
Link	db.Link	Unicode
Kategori	db.Category	Unicode
Rating	db.Rating	Angka
Kunci Datastore	db.Key	Menurut elemen jalur (jenis, ID, jenis, ID...)
Kunci Blobstore	blobstore.BlobKey	Urutan byte
Null	NoneType	Tidak ada

Penting: Sebaiknya jangan menyimpan UserProperty karena berisi alamat email dan ID unik pengguna. Jika pengguna mengubah alamat emailnya dan Anda membandingkan User lamanya yang tersimpan dengan nilai User yang baru, nilai tersebut tidak akan cocok.

Untuk string teks dan data biner yang tidak dienkode (string byte), Datastore mendukung dua jenis nilai:

• String pendek (hingga 1.500 byte) diindeks dan dapat digunakan dalam kondisi filter kueri dan tata urutan.
• String panjang (hingga 1 megabyte) tidak diindeks serta tidak dapat digunakan dalam filter kueri dan tata urutan.

Catatan: Jenis string byte panjang diberi nama Blob di Datastore API. Jenis ini tidak terkait dengan blob seperti yang digunakan dalam Blobstore API.

Jika kueri melibatkan properti dengan nilai jenis campuran, Datastore akan menggunakan pengurutan deterministik berdasarkan representasi internal:

1. Nilai null
2. Angka fixed-point
   • Bilangan bulat
   • Tanggal dan waktu
   • Rating
3. Nilai boolean
4. Urutan byte
   • String byte
   • String Unicode
   • Kunci Blobstore
5. Angka floating-point
6. Titik geografis
7. Pengguna Akun Google
8. Kunci Datastore

Karena string teks panjang dan string byte panjang tidak diindeks, maka pengurutan tidak ditentukan.

Catatan: Bilangan bulat dan angka floating-point dianggap sebagai jenis terpisah dalam Datastore. Jika suatu entity menggunakan campuran bilangan bulat dan float untuk properti yang sama, semua bilangan bulat akan diurutkan sebelum semua float: misalnya,

7 < 3.2

Bekerja dengan entity

Aplikasi dapat menggunakan Datastore API untuk membuat, mengambil, memperbarui, dan menghapus entity. Jika aplikasi mengetahui kunci lengkap untuk suatu entity (atau dapat memperolehnya dari kunci, jenis, dan ID parent-nya), aplikasi dapat menggunakan kunci tersebut untuk beroperasi secara langsung pada entity. Aplikasi juga bisa memperoleh kunci entity sebagai hasil dari kueri Datastore; lihat halaman Kueri Datastore untuk informasi selengkapnya.

Membuat entity

Di Python, Anda membuat entity baru dengan membuat instance class model, mengisi propertinya jika perlu, dan memanggil metode put() untuk menyimpannya ke Datastore. Anda dapat menetapkan nama kunci entity dengan meneruskan argumen key_name ke konstruktor:

employee = Employee(key_name='asalieri',
                    first_name='Antonio',
                    last_name='Salieri')

employee.hire_date = datetime.datetime.now().date()
employee.attended_hr_training = True

employee.put()

Jika Anda tidak memberikan nama kunci, Datastore akan otomatis menghasilkan ID numerik untuk kunci entity tersebut:

employee = Employee(first_name='Antonio',
                    last_name='Salieri')

employee.hire_date = datetime.datetime.now().date()
employee.attended_hr_training = True

employee.put()

Mengambil entity

Untuk mengambil entity yang diidentifikasi oleh kunci tertentu, teruskan objek Key sebagai argumen ke fungsi db.get(). Anda dapat menghasilkan objek Key menggunakan metode class Key.from_path(). Jalur lengkap adalah urutan entity di jalur ancestor, dengan setiap entity diwakili oleh jenisnya (string), diikuti dengan ID-nya (nama kunci atau ID numerik):

address_k = db.Key.from_path('Employee', 'asalieri', 'Address', 1)
address = db.get(address_k)

db.get() menampilkan instance class model yang sesuai. Pastikan Anda telah mengimpor class model untuk entity yang diambil.

Memperbarui entity

Untuk memperbarui entity yang ada, ubah atribut objek, lalu panggil metode put(). Data objek akan menimpa entity yang ada. Seluruh objek dikirim ke Datastore pada setiap panggilan ke put().

Catatan: Datastore API tidak membedakan antara membuat entity baru dan mengupdate yang sudah ada. Jika kunci objek mewakili entity yang sudah ada, metode put() akan menimpa entity yang sudah ada. Anda dapat menggunakan transaksi untuk menguji apakah entity dengan kunci tertentu sudah ada sebelum membuatnya. Lihat juga metode Model.get_or_insert().

Untuk menghapus properti, hapus atribut dari objek Python:

del address.postal_code

kemudian simpan objek tersebut.

Menghapus entity

Dengan kunci entity, Anda dapat menghapus entity dengan fungsi db.delete()

address_k = db.Key.from_path('Employee', 'asalieri', 'Address', 1)
db.delete(address_k)

atau dengan memanggil metode delete() entity sendiri:

employee_k = db.Key.from_path('Employee', 'asalieri')
employee = db.get(employee_k)

# ...

employee.delete()

Operasi batch

Fungsi db.put(), db.get(), dan db.delete() (beserta fungsi asinkronnya db.put_async(), db.get_async(), dan db.delete_async()) dapat menerima argumen daftar untuk bertindak pada beberapa entity dalam satu panggilan Datastore:

# A batch put.
db.put([e1, e2, e3])

# A batch get.
entities = db.get([k1, k2, k3])

# A batch delete.
db.delete([k1, k2, k3])

Operasi batch tidak mengubah biaya Anda. Anda akan dikenai biaya untuk setiap kunci dalam operasi batch, terlepas dari apakah setiap kunci ada atau tidak. Ukuran entity yang terlibat dalam operasi tidak memengaruhi biaya.

Catatan: Panggilan batch ke db.put() atau db.delete() mungkin berhasil untuk beberapa entitas, tetapi tidak untuk yang lainnya. Jika panggilan harus berhasil sepenuhnya atau gagal sepenuhnya, Anda harus menggunakan transaksi, dan semua entity yang terpengaruh harus berada dalam entity group yang sama.

Menghapus entity secara massal

Jika Anda perlu menghapus entity dalam jumlah besar, sebaiknya gunakan Dataflow untuk menghapus entity secara massal.

Menggunakan daftar kosong

Untuk antarmuka NDB, Datastore secara historis menulis daftar kosong sebagai properti yang dihilangkan untuk properti statis dan dinamis. Untuk mempertahankan kompatibilitas mundur, perilaku ini akan terus menjadi default. Untuk menggantinya baik secara global atau per ListProperty, tetapkan argumen write_empty_list ke true di class Properti Anda; daftar kosong kemudian ditulis ke Datastore dan dapat dibaca sebagai daftar kosong.

Untuk antarmuka DB, penulisan daftar kosong secara historis tidak diizinkan sama sekali jika properti bersifat dinamis: jika Anda mencobanya, Anda akan mendapatkan error. Artinya, tidak ada perilaku default yang perlu dipertahankan untuk kompatibilitas mundur bagi properti dinamis DB, sehingga Anda dapat menulis dan membaca daftar kosong dalam model dinamis tanpa perlu mengubah apa pun.

Namun, untuk properti statis DB, daftar kosong ditulis sebagai properti yang dihilangkan, dan perilaku ini berlanjut secara default untuk kompatibilitas mundur. Jika Anda ingin mengaktifkan daftar kosong untuk properti statis DB, gunakan argumen write_empty_list ke true di class Properti Anda; daftar kosong tersebut kemudian ditulis ke Datastore.