Class Kueri

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

Query class mewakili kueri untuk mengambil entity dari App Engine Datastore. (Lihat juga GqlQuery class terkait, yang menentukan kueri menggunakan GQL, bahasa kueri yang mirip SQL.)

Query ditentukan dalam modul google.appengine.ext.db.

Catatan: Mekanisme kueri berbasis indeks mendukung berbagai kueri dan cocok untuk sebagian besar aplikasi. Namun, mekanisme ini tidak mendukung beberapa jenis kueri yang umum digunakan dalam teknologi database lainnya: khususnya, join dan kueri agregat tidak didukung dalam mesin kueri Datastore. Lihat halaman Kueri Datastore untuk mengetahui batasan pada kueri Datastore.

Pengantar

Aplikasi membuat objek kueri untuk jenis entity tertentu dengan memanggil konstruktor Query secara langsung

class Song(db.Model):
  title = db.StringProperty()
  composer = db.StringProperty()
  date = db.DateTimeProperty()

q = db.Query(Song)

atau metode class all() dari class model jenis:

q = Song.all()

Tanpa modifikasi lebih lanjut, instance calss Query yang dihasilkan akan mengambil semua entity yang ada dari jenis yang ditentukan. Panggilan metode pada objek kemudian dapat digunakan untuk menyesuaikan kueri dengan kriteria filter tambahan, kondisi ancestor, dan tata urutan:

q.filter('title =', 'Imagine')
q.ancestor(ancestor_key)
q.order('-date')

Demi kemudahan, semua metode ini menampilkan objek kueri itu sendiri sehingga dapat digunakan berturut-turut dalam satu pernyataan:

q.filter('title =', 'Imagine').ancestor(key).order('-date')

Selanjutnya, aplikasi dapat mengeksekusi kueri dan mengakses hasilnya dengan salah satu cara berikut:

  • Memperlakukan objek kueri sebagai iterable, untuk memproses entity yang cocok satu per satu:

    for song in q:
  print song.title

    Hal ini secara implisit memanggil metode run() dari kueri untuk menghasilkan entity yang cocok. Dengan demikian sama dengan

    for song in q.run():
  print song.title

    Anda dapat menetapkan batas jumlah hasil yang akan diproses dengan argumen kata kunci limit:

    for song in q.run(limit=5):
  print song.title

    Antarmuka iterator tidak menyimpan hasil dalam cache, sehingga membuat iterator baru dari objek kueri akan mengulangi kueri yang sama dari awal.

  • Panggil metode get() kueri untuk mendapatkan satu entity cocok pertama yang ditemukan di Datastore:

    song = q.get()
print song.title

  • Panggil metode fetch() dari kueri untuk mendapatkan daftar semua entity yang cocok hingga jumlah hasil yang ditentukan:

    results = q.fetch(limit=5)
for song in results:
  print song.title

    Seperti halnya run(), objek kueri tidak meng-cache hasil, jadi memanggil fetch() untuk kedua kalinya akan mengeluarkan kembali kueri yang sama.

    Catatan: Anda seharusnya jarang menggunakan metode ini; sering kali lebih baik untuk menggunakan run().

Konstruktor

Konstruktor untuk Query class ditentukan sebagai berikut:

class Query (model_class=None, keys_only=False, cursor=None, namespace=None, projection=None, distinct=False)

Membuat instance Query class untuk mengambil entity dari App Engine Datastore.

Tanpa modifikasi lebih lanjut, objek kueri yang dihasilkan akan mengambil semua entity yang ada dari jenis yang ditentukan oleh model_class. Metode instance filter(), ancestor(),, dan order() kemudian dapat digunakan untuk menyesuaikan kueri dengan kriteria filter tambahan, kondisi ancestor, serta tata urutan.

Argumen

model_class
Class model (atau Expando) mewakili jenis entity tempat kueri diterapkan.
keys_only
Jika true, maka hanya akan menampilkan kunci, bukan entity lengkap. Kueri khusus kunci lebih cepat dan lebih murah daripada kueri yang menampilkan entity lengkap.
cursor
Posisi kursor untuk melanjutkan kueri.
namespace
Namespace yang akan digunakan untuk kueri.
projection
Daftar atau tuple nama properti yang akan ditampilkan. Hanya entity dengan properti yang ditentukan yang akan ditampilkan. Jika tidak ditentukan, seluruh entity akan ditampilkan secara default. Kueri proyeksi lebih cepat dan lebih murah daripada kueri yang menampilkan entity lengkap.

Catatan: Menentukan parameter ini dapat mengubah persyaratan indeks kueri.

distinct
Pada kasus Kueri proyeksi, distinct=True menentukan bahwa hanya hasil yang benar-benar unik yang akan ditampilkan dalam set hasil. Tindakan ini hanya akan menampilkan hasil pertama untuk entity yang memiliki nilai yang sama untuk properti yang sedang diproyeksikan.
True
Hanya menampilkan hasil pertama untuk setiap set nilai yang berbeda untuk properti dalam proyeksi.
False
Semua hasil ditampilkan.

Metode Instance

Instance Query class memiliki metode berikut:

filter (property_operator, value)

Menambahkan filter properti ke kueri. Kueri hanya akan menampilkan entity yang propertinya memenuhi semua filternya.

Argumen

property_operator
String yang terdiri dari nama properti dan operator perbandingan opsional (=, !=, <, <=, >, >=, IN ), dipisahkan dengan spasi: misalnya, 'age >'. Jika hanya nama properti yang ditentukan tanpa operator perbandingan, filter akan secara default membandingkan menggunakan operator sama dengan (=).
value
Nilai yang akan dibandingkan dengan nilai properti. Contoh:

q.filter('height >', 42).filter('city =', 'Seattle')
q.filter('user =', users.get_current_user())

Nilai perbandingan yang ditentukan harus memiliki jenis nilai yang sama dengan properti yang dibandingkan.

ancestor (ancestor)

Menambahkan filter ancestor ke kueri. Kueri hanya akan menampilkan entity dengan ancestor yang ditentukan.

Argumen

ancestor
Entity atau kunci ancestor.
order (properti)

Menambahkan urutan pengurutan ke kueri. Jika ada lebih dari satu tata urutan yang ditambahkan, tata urutan tersebut akan diterapkan sesuai dengan urutan penentuan tata urutan tersebut.

Argumen

properti
String yang memberikan nama properti yang akan diurutkan, secara opsional diikuti dengan tanda hubung (-) untuk menentukan urutan menurun. Menghapus tanda hubung akan menentukan urutan menaik secara default. Contoh: 
# Order alphabetically by last name:
q.order('last_name')

# Order by height, tallest to shortest:
q.order('-height')
projection ()

Menampilkan tuple properti dalam proyeksi atau None.

is_keys_only ()

Menampilkan nilai boolean yang menunjukkan apakah kueri tersebut adalah kueri khusus kunci.

run (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, limit=None, batch_size=20, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

Menampilkan iterable untuk melakukan loop pada hasil kueri. Ini memungkinkan Anda untuk menentukan operasi kueri dengan setelan parameter dan mengakses hasilnya secara iteratif:

  1. Mengambil dan menghapus jumlah hasil yang ditentukan oleh argumen offset.
  2. Mengambil dan menampilkan hingga jumlah maksimum hasil yang ditentukan oleh argumen limit.

Dengan demikian, performa loop akan diskalakan secara linear dengan jumlah offset + limit. Jika mengetahui jumlah hasil yang ingin diambil, Anda harus selalu menetapkan nilai limit yang eksplisit.

Metode ini menggunakan pengambilan data asinkron untuk meningkatkan performa. Secara default, ID ini mengambil hasilnya dari Datastore dalam batch kecil, sehingga memungkinkan aplikasi menghentikan iterasi dan menghindari pengambilan hasil lebih dari yang diperlukan.

Tips: Untuk mengambil semua hasil yang tersedia saat angkanya tidak diketahui, tetapkan batch_size ke nilai yang besar, seperti 1000.

Tips: Jika tidak perlu mengubah nilai argumen default, Anda dapat menggunakan objek kueri secara langsung sebagai iterable untuk mengontrol loop. Ini secara implisit memanggil run() dengan argumen default.

Argumen

read_policy
Baca kebijakan yang menentukan tingkat konsistensi data yang diinginkan:
STRONG_CONSISTENCY
Menjamin hasil terbaru, tetapi terbatas pada satu entity group.
EVENTUAL_CONSISTENCY
Dapat mencakup beberapa entity group, tetapi terkadang dapat menampilkan hasil yang usang. Secara umum, kueri dengan konsistensi tertunda berjalan lebih cepat daripada kueri dengan konsistensi kuat, tetapi hal ini tidak selalu berlaku.

Catatan: Kueri global (non-ancestor) mengabaikan argumen ini.

deadline
Waktu maksimum, dalam detik, untuk menunggu Datastore menampilkan hasil sebelum membatalkan dengan error. Menerima nilai berupa bilangan bulat atau floating point. Tidak dapat ditetapkan lebih tinggi dari nilai default (60 detik), tetapi dapat disesuaikan dengan mengurangi nilainya untuk memastikan operasi tertentu gagal dengan cepat (misalnya, untuk memberikan respons yang lebih cepat kepada pengguna, mencoba kembali operasi tersebut, mencoba operasi yang berbeda, atau menambahkan operasi ke task queue).
offset
Jumlah hasil yang akan dilewati sebelum menampilkan hasil pertama.
limit
Jumlah hasil maksimum yang akan ditampilkan. Jika dihilangkan atau ditetapkan ke None, semua hasil yang tersedia akan diambil secara default.
batch_size
Jumlah hasil yang dicoba diambil per batch. Jika limit ditetapkan, maka secara default akan mengikuti batas yang telah ditentukan; jika tidak, maka secara default adalah 20.
keys_only
Jika true, maka hanya akan menampilkan kunci, bukan entity lengkap. Kueri khusus kunci lebih cepat dan lebih murah daripada kueri yang menampilkan entity lengkap.
projection
Daftar atau tuple nama properti yang akan ditampilkan. Hanya entity dengan properti yang ditentukan yang akan ditampilkan. Jika tidak ditentukan, seluruh entity akan ditampilkan secara default. Kueri proyeksi lebih cepat dan lebih murah daripada kueri yang menampilkan entity lengkap.

Catatan: Menentukan parameter ini dapat mengubah persyaratan indeks kueri.

start_cursor
Posisi kursor untuk memulai kueri.
end_cursor
Posisi kursor untuk mengakhiri kueri.
get (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

Menjalankan kueri dan menampilkan hasil pertama, atau None jika tidak ada hasil yang ditemukan.

Argumen

read_policy
Baca kebijakan yang menentukan tingkat konsistensi data yang diinginkan:
STRONG_CONSISTENCY
Menjamin hasil terbaru, tetapi terbatas pada satu entity group.
EVENTUAL_CONSISTENCY
Dapat mencakup beberapa entity group, tetapi terkadang dapat menampilkan hasil yang usang. Secara umum, kueri dengan konsistensi tertunda berjalan lebih cepat daripada kueri dengan konsistensi kuat, tetapi hal ini tidak selalu berlaku.

Catatan: Kueri global (non-ancestor) mengabaikan argumen ini.

deadline
Waktu maksimum, dalam detik, untuk menunggu Datastore menampilkan hasil sebelum membatalkan dengan error. Menerima nilai berupa bilangan bulat atau floating point. Tidak dapat ditetapkan lebih tinggi dari nilai default (60 detik), tetapi dapat disesuaikan dengan mengurangi nilainya untuk memastikan operasi tertentu gagal dengan cepat (misalnya, untuk memberikan respons yang lebih cepat kepada pengguna, mencoba kembali operasi tersebut, mencoba operasi yang berbeda, atau menambahkan operasi ke task queue).
offset
Jumlah hasil yang akan dilewati sebelum menampilkan hasil pertama.
keys_only
Jika true, maka hanya akan menampilkan kunci, bukan entity lengkap. Kueri khusus kunci lebih cepat dan lebih murah daripada kueri yang menampilkan entity lengkap.
projection
Daftar atau tuple nama properti yang akan ditampilkan. Hanya entity dengan properti yang ditentukan yang akan ditampilkan. Jika tidak ditentukan, seluruh entity akan ditampilkan secara default. Kueri proyeksi lebih cepat dan lebih murah daripada kueri yang menampilkan entity lengkap.

Catatan: Menentukan parameter ini dapat mengubah persyaratan indeks kueri.

start_cursor
Posisi kursor untuk memulai kueri.
end_cursor
Posisi kursor untuk mengakhiri kueri.
fetch (limit, read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, keys_only=False, projection=None, start_cursor=None, end_cursor=None)

Menjalankan kueri dan menampilkan daftar hasil (yang mungkin kosong):

  1. Mengambil dan menghapus jumlah hasil yang ditentukan oleh argumen offset.
  2. Mengambil dan menampilkan hingga jumlah maksimum hasil yang ditentukan oleh argumen limit.

Dengan demikian, performa metode akan diskalakan secara linear dengan jumlah offset + limit.

Catatan: Metode ini hanya berupa wrapper tipis di sekitar metode run(), dan kurang efisien serta lebih intensif memori dibandingkan dengan menggunakan run() secara langsung. Seharusnya Anda tidak perlu terlalu sering menggunakan fetch(); metode ini disediakan utamanya untuk memudahkan Anda ketika perlu mengambil daftar lengkap hasil kueri dalam memori.

Tips: Metode fetch() dirancang untuk hanya mengambil jumlah hasil yang ditentukan oleh argumen limit. Untuk mengambil semua hasil kueri yang tersedia saat jumlahnya tidak diketahui, gunakan run() dengan ukuran batch yang besar, seperti run(batch_size=1000), bukan fetch().

Argumen

limit
Jumlah hasil maksimum yang akan ditampilkan. Jika ditetapkan ke None, semua hasil yang tersedia akan diambil.
read_policy
Baca kebijakan yang menentukan tingkat konsistensi data yang diinginkan:
STRONG_CONSISTENCY
Menjamin hasil terbaru, tetapi terbatas pada satu entity group.
EVENTUAL_CONSISTENCY
Dapat mencakup beberapa entity group, tetapi terkadang dapat menampilkan hasil yang usang. Secara umum, kueri dengan konsistensi tertunda berjalan lebih cepat daripada kueri dengan konsistensi kuat, tetapi hal ini tidak selalu berlaku.

Catatan: Kueri global (non-ancestor) mengabaikan argumen ini.

deadline
Waktu maksimum, dalam detik, untuk menunggu Datastore menampilkan hasil sebelum membatalkan dengan error. Menerima nilai berupa bilangan bulat atau floating point. Tidak dapat ditetapkan lebih tinggi dari nilai default (60 detik), tetapi dapat disesuaikan dengan mengurangi nilainya untuk memastikan operasi tertentu gagal dengan cepat (misalnya, untuk memberikan respons yang lebih cepat kepada pengguna, mencoba kembali operasi tersebut, mencoba operasi yang berbeda, atau menambahkan operasi ke task queue).
offset
Jumlah hasil yang akan dilewati sebelum menampilkan hasil pertama.
keys_only
Jika true, maka hanya akan menampilkan kunci, bukan entity lengkap. Kueri khusus kunci lebih cepat dan lebih murah daripada kueri yang menampilkan entity lengkap.
projection
Daftar atau tuple nama properti yang akan ditampilkan. Hanya entity dengan properti yang ditentukan yang akan ditampilkan. Jika tidak ditentukan, seluruh entity akan ditampilkan secara default. Kueri proyeksi lebih cepat dan lebih murah daripada kueri yang menampilkan entity lengkap.

Catatan: Menentukan parameter ini dapat mengubah persyaratan indeks kueri.

start_cursor
Posisi kursor untuk memulai kueri.
end_cursor
Posisi kursor untuk mengakhiri kueri.
count (read_policy=STRONG_CONSISTENCY, deadline=60, offset=0, limit=1000, start_cursor=None, end_cursor=None)

Menampilkan jumlah hasil yang cocok dengan kueri. Proses ini lebih cepat dengan faktor konstan dibandingan dengan mengambil semua hasil, tetapi waktu berjalan masih diskalakan secara linear seiring dengan penambahan offset + limit. Kecuali jika jumlah hasilnya diperkirakan kecil, sebaiknya tentukan argumen limit; jika tidak, metode tersebut akan berlanjut sampai selesai menghitung atau waktu habis.

Argumen

read_policy
Baca kebijakan yang menentukan tingkat konsistensi data yang diinginkan:
STRONG_CONSISTENCY
Menjamin hasil terbaru, tetapi terbatas pada satu entity group.
EVENTUAL_CONSISTENCY
Dapat mencakup beberapa entity group, tetapi terkadang dapat menampilkan hasil yang usang. Secara umum, kueri dengan konsistensi tertunda berjalan lebih cepat daripada kueri dengan konsistensi kuat, tetapi hal ini tidak selalu berlaku.

Catatan: Kueri global (non-ancestor) mengabaikan argumen ini.

deadline
Waktu maksimum, dalam detik, untuk menunggu Datastore menampilkan hasil sebelum membatalkan dengan error. Menerima nilai berupa bilangan bulat atau floating point. Tidak dapat ditetapkan lebih tinggi dari nilai default (60 detik), tetapi dapat disesuaikan dengan mengurangi nilainya untuk memastikan operasi tertentu gagal dengan cepat (misalnya, untuk memberikan respons yang lebih cepat kepada pengguna, mencoba kembali operasi tersebut, mencoba operasi yang berbeda, atau menambahkan operasi ke task queue).
offset
Jumlah hasil yang perlu dilewati sebelum menghitung hasil pertama.
limit
Jumlah hasil maksimum yang akan dihitung.
start_cursor
Posisi kursor untuk memulai kueri.
end_cursor
Posisi kursor untuk mengakhiri kueri.
index_list ()

Menampilkan daftar indeks yang digunakan oleh kueri yang dieksekusi, termasuk indeks properti utama, komposit, jenis, dan properti tunggal.

Perhatian: Memanggil metode ini pada kueri yang belum dieksekusi akan memunculkan pengecualian AssertionError.

Catatan: Fitur ini tidak sepenuhnya didukung pada server pengembangan. Saat digunakan dengan server pengembangan, hasilnya adalah daftar kosong atau daftar yang berisi hanya satu indeks komposit.

Misalnya, kode berikut mencetak berbagai informasi tentang indeks yang digunakan oleh kueri:

# other imports ...
import webapp2
from google.appengine.api import users
from google.appengine.ext import db

class Greeting(db.Model):
  author = db.StringProperty()
  content = db.StringProperty(multiline=True)
  date = db.DateTimeProperty(auto_now_add=True)

class MainPage(webapp2.RequestHandler):
  def get(self):
    user = users.get_current_user()
    q = db.Query(Greeting)
    q.filter("author =", user.user_id())
    q.order("-date")
    q.fetch(100)
    index_list = q.index_list()
    for ix in index_list:
      self.response.out.write("Kind: %s" % ix.kind())
      self.response.out.write("<br />")
      self.response.out.write("Has ancestor? %s" % ix.has_ancestor())
      self.response.out.write("<br />")
      for name, direction in ix.properties():
        self.response.out.write("Property name: "+name)
        self.response.out.write("<br />")
        if direction == db.Index.DESCENDING:
          self.response.out.write("Sort direction: DESCENDING")
        else:
          self.response.out.write("Sort direction: ASCENDING")
        self.response.out.write("<br />")

Tindakan ini menghasilkan output seperti berikut untuk setiap indeks:

Kind: Greeting
Has ancestor? False
Property name: author
Sort direction: ASCENDING
Property name: date
Sort direction: DESCENDING
cursor ()

Menampilkan string kursor dalam format Base64 yang menunjukkan posisi dalam set hasil kueri setelah hasil terakhir yang diambil. String kursor aman digunakan dalam parameter HTTP GET dan POST, serta dapat disimpan di Datastore atau Memcache. Pemanggilan kueri yang sama di masa mendatang dapat memberikan string ini melalui parameter start_cursor atau metode with_cursor() untuk melanjutkan pengambilan hasil dari posisi ini.

Perhatian: Memanggil metode ini pada kueri yang belum dieksekusi akan memunculkan pengecualian AssertionError.

Catatan: Tidak semua kueri kompatibel dengan kursor; lihat halaman Datastore Queries untuk mengetahui informasi selengkapnya.

with_cursor (start_cursor, end_cursor=None)

Menentukan posisi akhir (opsional) dan awal dalam set hasil kueri yang digunakan untuk mengambil hasil. String kursor yang menunjukkan posisi awal dan akhir dapat diperoleh dengan memanggil cursor() setelah pemanggilan kueri sebelumnya. Kueri saat ini harus sama dengan pemanggilan sebelumnya, termasuk jenis entity, filter properti, filter ancestor, dan tata urutan.

Argumen

start_cursor
String kursor dalam format Base64 yang menentukan tempat untuk memulai kueri.
end_cursor
String kursor dalam format Base64 yang menentukan tempat untuk mengakhiri kueri.