NDB Functions

Functions

ndb.add_flow_exception(exc)
Tentukan bahwa pengecualian tidak boleh dicatat, tetapi hanya boleh menjadi bagian dari alur program normal. (Biasanya, memunculkan pengecualian akan menulis pesan peringatan ke log aplikasi.)

Argumen

exc
Class pengecualian yang tidak boleh dicatat.

Secara default, pengecualian berikut tidak dicatat:

  • webob.exc.HTTPException (dan subclass-nya)
  • ndb.Rollback
ndb.delete_multi(keys, **ctx_options)
Menghapus entity yang diidentifikasi oleh urutan kunci yang diteruskan.

Argumen

keys
Urutan kunci
**ctx_options
Opsi konteks
ndb.delete_multi_async(keys, **ctx_options)
Menghapus entity secara asinkron yang diidentifikasi oleh urutan kunci yang diteruskan.

Argumen

keys
Urutan kunci
**ctx_options
Opsi konteks

Menampilkan daftar objek Future. Setiap hasil berikutnya akan menjadi None.

ndb.get_multi(keys, **ctx_options)
Mengambil entity yang diidentifikasi oleh urutan kunci yang diteruskan.

Argumen

keys
Urutan kunci
**ctx_options
Opsi konteks

Menampilkan daftar. Setiap item daftar adalah instance Model atau None jika kunci tidak ditemukan.

ndb.get_multi_async(keys, **ctx_options)
Mengambil entity yang diidentifikasi secara asinkron oleh urutan kunci yang diteruskan.

Argumen

keys
Urutan kunci
**ctx_options
Opsi konteks

Menampilkan daftar objek Future. Setiap hasil berikutnya adalah instance Model atau None jika kuncinya tidak ditemukan.

ndb.in_transaction()
Menampilkan Boolean yang menunjukkan apakah transaksi saat ini aktif.
@ndb.non_transactional
@ndb.non_transactional(allow_existing=True)
Dekorator untuk memastikan bahwa fungsi berjalan di luar transaksi.

Argumen:

allow_existing
Jika True (default) dan jika fungsi yang didekorasi dipanggil oleh kode dalam transaksi, fungsi ini akan berjalan secara independen dari transaksi tersebut. Jika False dan jika fungsi yang didekorasi dipanggil oleh kode dalam transaksi, fungsi tersebut akan memunculkan pengecualian.
ndb.put_multi(entities, **ctx_options)
Menyimpan urutan instance Model.

Argumen

entities
Urutan instance Model
**ctx_options
Opsi konteks

Menampilkan daftar dengan kunci yang disimpan.

ndb.put_multi_async(entities, **ctx_options)
Menyimpan urutan instance Model secara asinkron.

Argumen

entities
Urutan instance Model
**ctx_options
Opsi konteks

Menampilkan daftar objek Future. Setiap hasil berikutnya akan menjadi kunci yang disimpan.

ndb.transaction(callback, **ctx_options)
Menjalankan callback dalam transaksi.

Argumen

callback
Fungsi atau tasklet yang akan dipanggil
**ctx_options
Opsi transaksi

Menunjukkan callback apa pun yang ditampilkan. Menampilkan callback apa pun yang muncul atau pengecualian TransactionFailedError jika transaksi gagal.

Untuk meneruskan argumen ke fungsi callback, gunakan lambda. Misalnya, 

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))
ndb.transaction_async(callback, **ctx_options)
Menjalankan callback secara asinkron dalam transaksi.

Argumen

callback
Fungsi atau tasklet yang akan dipanggil
**ctx_options
Opsi transaksi

Menampilkan Future. Kode future ini menunjukkan callback apa pun yang ditampilkan, atau memunculkan callback apa pun atau TransactionFailedError jika transaksi gagal.

Untuk meneruskan argumen ke fungsi callback, gunakan lambda. Misalnya, 

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))
@ndb.transactional
@ndb.transactional(**ctx_options)
Dekorator untuk membuat fungsi secara otomatis berjalan dalam transaksi.

Argumen:

Dekorator ini dapat memiliki opsi transaksi.

Opsi Konteks, Opsi Transaksi

Opsi konteks memungkinkan Anda menjalankan operasi datastore tertentu dengan konfigurasi yang berbeda. Misalnya, Anda mungkin ingin memvariasikan kebijakan baca atau batas waktu RPC untuk setiap permintaan. Anda dapat melakukannya dengan meneruskan opsi konteks ke hampir semua operasi. Beberapa fungsi terkait transaksi menggunakan opsi transaksi, yang mencakup opsi tambahan selain serangkaian opsi konteks.

Berikut beberapa contoh penggunaan opsi konteks. Untuk menetapkan batas waktu RPC ke 1 detik saat membaca entity, Anda dapat menggunakan: 

key.get(deadline=1)

Untuk menetapkan waktu tunggu memcache ke 30 detik saat menulis entity, Anda dapat menggunakan: 

ent.put(ndb_memcache_timeout=30)

Untuk menghapus item yang telah di-cache dan memaksanya dimuat ulang, Anda dapat menggunakan: 

key.delete(use_datastore=False)

Argumen kata kunci khusus options dan config (yang memiliki arti identik untuk alasan historis) memungkinkan seseorang menentukan beberapa opsi sebagai objek Konfigurasi. Ini dapat berupa objek ndb.ContextOptions atau (untuk fungsi dan dekorator transaksional) objek ndb.TransactionOptions. Misalnya, key.get(options=ndb.ContextOptions(use_cache=True)) setara dengan key.get(use_cache=True). Opsi yang ditetapkan dalam objek opsi tersebut dapat diganti oleh parameter kata kunci.

Tersedia opsi konteks berikut:

Opsi Jenis Deskripsi
deadline float Batas waktu panggilan datastore, ditetapkan sebagai jumlah detik. (Secara default, panggilan hanya diganggu oleh batas waktu pengendali permintaan.)
read_policy ndb.EVENTUAL_CONSISTENCY Tetapkan ini ke ndb.EVENTUAL_CONSISTENCY jika, alih-alih menunggu Datastore menyelesaikan penerapan perubahan ke semua hasil yang ditampilkan, Anda ingin mendapatkan hasil yang mungkin bukan hasil terkini lebih cepat.
force_writes bool Menentukan apakah permintaan tulis akan berhasil meskipun aplikasi bersifat hanya baca. (Ini hanya berlaku untuk periode hanya baca yang dikontrol pengguna.)
use_cache bool Menentukan apakah akan menyimpan entity pada cache dalam proses; mengganti kebijakan cache dalam proses untuk operasi ini.
use_memcache bool Menentukan apakah akan menyimpan entity dalam memcache; menggantikan kebijakan memcache untuk operasi ini.
use_datastore bool Menentukan apakah akan menyimpan entity di Datastore; menggantikan kebijakan Datastore untuk operasi ini.
memcache_timeout int Masa pakai maksimum untuk entity dalam memcache; menggantikan kebijakan waktu tunggu memcache untuk operasi ini.
max_memcache_items int Ukuran batch maksimum untuk fitur pembuatan batch otomatis metode memcache Konteks. Misalnya, dengan ukuran default max_memcache_items (100), hingga 100 operasi yang ditetapkan memcache akan digabungkan menjadi satu operasi set_multi.

Untuk beberapa fungsi terkait transaksi, opsi transaksi berikut tersedia (beserta opsi konteks yang diwariskan yang tercantum di atas):

Opsi Jenis Deskripsi
xg bool Izinkan transaksi lintas grup (XG). False secara default.
propagation int

NDB memberikan dukungan terbatas untuk transaksi dalam transaksi, yang dikenal sebagai "transaksi bertingkat".

Parameter penerapan mengontrol hal yang terjadi jika kode Anda mencoba memulai transaksi bertingkat.

Kebijakan penerapan untuk @ndb.transactional ditetapkan secara default ke ALLOWED.

Kebijakan penerapan untuk ndb.transaction() ditetapkan secara default ke NESTED. Kebijakan NESTED tidak didukung oleh NDB sehingga kode Anda akan menampilkan pengecualian BadRequestError. Dalam hal ini, NDB menetapkan nilai default yang tidak didukung sehingga programmer mengetahui secara eksplisit batasan transaksi bertingkat.

Parameter penerapan dapat berupa salah satu nilai berikut:

ndb.TransactionOptions.NESTED
Kebijakan penerapan NESTED akan meng-commit semua perubahan pada transaksi luar dan dalam secara bersamaan saat kebijakan luar di-commit. Namun, jika pengecualian ditampilkan dalam transaksi internal, semua perubahan akan dihapus, tetapi memungkinkan transaksi luar dapat dipulihkan dan dilanjutkan secara opsional. Kebijakan NESTED tidak didukung. Jika menggunakan kebijakan ini, kode Anda akan menampilkan pengecualian BadRequestError.
ndb.TransactionOptions.MANDATORY
Selalu menerapkan transaksi yang sudah ada; memberikan pengecualian jika tidak ada transaksi yang ada. Jika fungsi yang menggunakan kebijakan ini menampilkan pengecualian, mungkin tidak aman untuk menangkap pengecualian tersebut dan meng-commit transaksi luar; fungsi tersebut mungkin telah meninggalkan transaksi luar dalam kondisi buruk.
ndb.TransactionOptions.ALLOWED
Jika sudah ada transaksi, terapkan transaksi tersebut. Jika fungsi yang menggunakan kebijakan ini menampilkan pengecualian, mungkin tidak aman untuk menangkap pengecualian tersebut dan meng-commit transaksi luar; fungsi tersebut mungkin telah meninggalkan transaksi luar dalam kondisi buruk.
ndb.TransactionOptions.INDEPENDENT
Selalu gunakan transaksi baru, "menjeda" transaksi yang sudah ada. Fungsi yang menggunakan kebijakan ini tidak boleh menampilkan entity apa pun yang dibaca dalam transaksi baru, karena entity tersebut tidak konsisten secara transaksi dengan transaksi pemanggil.
retries int Jumlah percobaan ulang secara otomatis jika terjadi kegagalan transaksi. Nol berarti mencoba sekali, tetapi bukan mencoba lagi.

Dalam beberapa kasus, opsi diabaikan karena penyimpanan dalam cache. Misalnya, jika Anda menentukan batas waktu RPC untuk operasi baca yang terpenuhi dari cache dalam konteks, batas waktu tersebut akan diabaikan. Di sisi lain, opsi yang tidak dikenal menyebabkan TypeError dimunculkan.

Operasi dengan berbagai opsi dikelompokkan bersama saat pembuatan batch otomatis diterapkan. Misalnya, jika Anda menggunakan put_async() untuk menulis beberapa entity dengan deadline = 5 dan beberapa entity tanpa menentukan batas waktu, dan semuanya memenuhi syarat untuk pembuatan batch otomatis, batcher otomatis akan membuat dua panggilan RPC terpisah—satu untuk grup entity dengan deadline = 5 dan satu untuk grup lainnya—meskipun batas waktu RPC default juga 5. Hal ini berlaku meskipun opsi yang ditentukan tidak relevan dengan operasi RPC (misalnya ndb_should_cache).