Membuat dan Menggunakan Kunci Entity

Setiap entity diidentifikasi oleh kunci yang unik dalam instance Datastore aplikasi, dan terdiri dari ID berikut:

  • jenis. Jenis biasanya merupakan nama class model tempat entity berada, tetapi Anda dapat mengubahnya menjadi beberapa string lain dengan mengganti classmethod _get_kind().
  • ID. Anda menentukan nama kunci Anda sendiri sebagai ID atau biarkan Datastore menghasilkan ID numerik bilangan bulat secara otomatis.

Menentukan nama kunci Anda sendiri

Contoh berikut secara implisit membuat kunci dengan ID string menggunakan parameter bernama id:

account = Account(
    username='Sandy', userid=1234, email='sandy@example.com',
    id='sandy@example.com')

return account.key.id()  # returns 'sandy@example.com'

Atau, Anda dapat menetapkan nama kunci secara langsung:

account.key = ndb.Key('Account', 'sandy@example.com')

# You can also use the model class object itself, rather than its name,
# to specify the entity's kind:
account.key = ndb.Key(Account, 'sandy@example.com')

Mengizinkan Datastore membuat ID untuk digunakan sebagai kunci

Kode ini menunjukkan cara menggunakan ID yang dibuat secara otomatis sebagai kunci:

# note: no id kwarg
account = Account(username='Sandy', userid=1234, email='sandy@example.com')
account.put()
# account.key will now have a key of the form: ndb.Key(Account, 71321839)
# where the value 71321839 was generated by Datastore for us.

Menggunakan jalur ancestor dalam kunci

Urutan entity yang dimulai dengan root entity dan berlanjut dari induk ke turunan, yang mengarah ke entity tertentu, merupakan jalur ancestor entity tersebut. Secara rekursif, suatu entity, induknya, induk dari induknya, dan seterusnya merupakan ancestor entity. Entity dalam Datastore membentuk ruang kunci hierarkis yang mirip dengan struktur direktori hierarkis pada sistem file.

Kunci lengkap yang mengidentifikasi entity terdiri dari urutan pasangan jenis-ID yang menentukan jalur ancestor-nya dan berakhir dengan entity itu sendiri. Metode konstruktor untuk class Key menerima urutan jenis dan ID tersebut, serta menampilkan objek yang mewakili kunci untuk entity yang sesuai.

Contoh berikut menunjukkan layanan blogging yang menyimpan pesan berdasarkan revisi. Pesan diatur dalam akun, dan revisi diatur dalam pesan.

class Revision(ndb.Model):
    message_text = ndb.StringProperty()
... 
ndb.Key('Account', 'sandy@example.com', 'Message', 123, 'Revision', '1')
ndb.Key('Account', 'sandy@example.com', 'Message', 123, 'Revision', '2')
ndb.Key('Account', 'larry@example.com', 'Message', 456, 'Revision', '1')
ndb.Key('Account', 'larry@example.com', 'Message', 789, 'Revision', '2')

Dalam contoh, ('Account', 'sandy@example.com'), ('Message', 123), dan ('Revision', '1') adalah contoh pasangan jenis-ID.

Perhatikan bahwa Message bukan class model dan hanya digunakan sebagai cara untuk mengelompokkan revisi, bukan untuk menyimpan data.

Seperti yang ditunjukkan dalam kode contoh, jenis entity ditentukan oleh pasangan nama-jenis terakhir dalam daftar: ndb.Key('Revision', '1').

Menggunakan parameter bernama

Anda dapat menggunakan parameter bernama parent untuk menentukan entity apa pun di jalur ancestor secara langsung. Semua notasi berikut mewakili kunci yang sama:

ndb.Key('Account', 'sandy@example.com', 'Message', 123, 'Revision', '1')

ndb.Key('Revision', '1', parent=ndb.Key(
    'Account', 'sandy@example.com', 'Message', 123))

ndb.Key('Revision', '1', parent=ndb.Key(
    'Message', 123, parent=ndb.Key('Account', 'sandy@example.com')))

Menentukan root entity

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

sandy_key = ndb.Key(Account, 'sandy@example.com')

Menentukan entity dengan ancestor

Untuk menyisipkan pesan baru dengan kunci induk

account_key = ndb.Key(Account, 'sandy@example.com')

# Ask Datastore to allocate an ID.
new_id = ndb.Model.allocate_ids(size=1, parent=account_key)[0]

# Datastore returns us an integer ID that we can use to create the message
# key
message_key = ndb.Key('Message', new_id, parent=account_key)

# Now we can put the message into Datastore
initial_revision = Revision(
    message_text='Hello', id='1', parent=message_key)
initial_revision.put()

Untuk kunci yang dibuat dengan suatu induk, metode parent() akan menampilkan kunci yang mewakili parent entity:

message_key = initial_revision.key.parent()

Menggunakan ID Kunci Numerik

Anda dapat membuat entity tanpa menentukan ID, dalam hal ini penyimpanan data akan otomatis menghasilkan ID numerik. Jika Anda memilih untuk menentukan beberapa ID lalu mengizinkan Datastore membuat beberapa ID secara otomatis, Anda dapat melanggar persyaratan untuk kunci unik. Untuk menghindari hal ini, cadangkan rentang angka yang akan digunakan untuk memilih ID atau gunakan ID string untuk menghindari masalah ini sepenuhnya.

Untuk mencadangkan rentang ID, gunakan metode class allocate_ids():

  • untuk mengalokasikan ID dalam jumlah tertentu
  • untuk mengalokasikan semua ID hingga nilai maksimum yang ditentukan.

Mengalokasikan ID

Untuk mengalokasikan 100 ID ke class model MyModel tertentu:

first, last = MyModel.allocate_ids(100)

Untuk mengalokasikan 100 ID ke entity dengan kunci induk p:

first, last = MyModel.allocate_ids(100, parent=p)

Nilai yang ditampilkan, first dan last, adalah ID pertama dan terakhir (inklusif) yang dialokasikan. Anda dapat menggunakan ini untuk membuat kunci seperti berikut:

keys = [ndb.Key(MyModel, id) for id in range(first, last+1)]

Kunci ini dijamin tidak akan ditampilkan sebelumnya oleh generator ID internal penyimpanan data, dan tidak akan ditampilkan oleh panggilan mendatang ke generator ID internal. Namun, metode allocate_ids() tidak memeriksa apakah ID yang ditampilkan ada di penyimpanan data; metode ini hanya berinteraksi dengan generator ID.

Untuk mengalokasikan semua ID hingga nilai maksimum yang ditentukan:

first, last = MyModel.allocate_ids(max=N)

Formulir ini memastikan bahwa semua ID yang kurang dari atau sama dengan N dianggap telah dialokasikan. Nilai yang ditampilkan, first dan last, menunjukkan rentang ID yang dicadangkan oleh operasi ini. Mencoba mencadangkan ID yang sudah dialokasikan bukanlah suatu kesalahan; jika terjadi, first menunjukkan ID pertama yang belum dialokasikan dan last adalah ID terakhir yang dialokasikan.