Catatan: Python 2.7 telah mencapai akhir dukungan pada 31 Januari 2024. Aplikasi Python 2.7 Anda yang sudah ada akan terus berjalan dan menerima traffic. Namun, App Engine mungkin memblokir deployment ulang aplikasi yang menggunakan runtime setelah akhir tanggal dukungannya. Sebaiknya migrasikan ke Python versi terbaru yang didukung.

Class GqlQuery

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

Class GqlQuery mewakili kueri untuk mengambil entity dari App Engine Datastore menggunakan bahasa kueri App Engine yang mirip SQL, yaitu GQL. Untuk pembahasan lengkap mengenai fitur dan sintaksis GQL, lihat Referensi GQL; lihat juga class terkait Query, yang menggunakan objek dan metode, bukan GQL, untuk menyiapkan kueri.

GqlQuery 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 kueri Datastore.

Pengantar

Aplikasi membuat objek kueri GQL dengan memanggil konstruktor GqlQuery secara langsung atau metode class gql() dari class model jenis entity. Konstruktor GqlQuery menggunakan string kueri sebagai argumen, pernyataan GQL lengkap yang dimulai denganSELECT ... FROM model-name. Nilai dalam klausa WHERE dapat berupa literal numerik atau string, atau dapat menggunakan binding parameter untuk nilai. Parameter dapat di-bind menggunakan argumen posisional atau kata kunci:

q = GqlQuery("SELECT * FROM Song WHERE composer = 'Lennon, John'")

q = GqlQuery("SELECT __key__ FROM Song WHERE composer = :1", "Lennon, John")

q = GqlQuery("SELECT * FROM Song WHERE composer = :composer", composer="Lennon, John")

Untuk memudahkan, class Model dan Expando memiliki metode class gql() yang menampilkan instance GqlQuery. Metode ini menggunakan string kueri GQL tanpa awalan model-name SELECT ... FROM, yang tersirat:

q = Song.gql("WHERE composer = 'Lennon, John'")

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 class GqlQuery ditentukan sebagai berikut:

class GqlQuery (query_string, *args, **kwds)

Membuat instance class GqlQuery untuk mengambil entity dari App Engine Datastore menggunakan bahasa kueri GQL.

Argumen

query_string: String yang berisi pernyataan GQL lengkap.
args: Nilai parameter posisional.
kwds: Nilai parameter kata kunci.

Metode Instance

Instance class GqlQuery memiliki metode berikut:

bind (*args, **kwds)

Mem-binding ulang parameter value kueri. Kueri yang diubah akan dieksekusi saat hasil pertama diakses setelah parameternya dikembalikan.

Melakukan binding ulang parameter ke objek GqlQuery yang ada akan lebih cepat daripada membuat objek GqlQuery baru, karena string kueri tidak perlu diurai lagi.

Argumen

args: Nilai parameter posisi baru.
kwds: Nilai parameter kata kunci baru.

proyeksi ()

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:

Mengambil dan menghapus jumlah hasil yang ditentukan oleh argumen offset.
Mengambil dan menampilkan hingga jumlah hasil maksimum 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 harus dilewati sebelum menampilkan hasil pertama.

limit

Jumlah hasil maksimum yang akan ditampilkan. Jika parameter ini dihilangkan, nilai yang ditentukan dalam klausa LIMIT dari string kueri GQL akan digunakan. Jika ditetapkan secara eksplisit ke None, semua hasil yang tersedia akan diambil.

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. Maksimal satu hasil diambil dari Datastore; klausa LIMIT dari string kueri GQL, jika ada, akan diabaikan.

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

offset

Jumlah hasil yang harus 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

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):

Mengambil dan menghapus jumlah hasil yang ditentukan oleh argumen offset.
Mengambil dan menampilkan hingga jumlah hasil maksimum 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

offset

Jumlah hasil yang harus 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

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

offset

Jumlah hasil yang perlu dilewati sebelum menghitung hasil pertama.

limit

Jumlah hasil maksimum yang akan dihitung.

Catatan: Jika ditentukan secara eksplisit, parameter ini akan menggantikan nilai apa pun yang ditetapkan dalam klausa LIMIT string kueri GQL. Namun, jika parameter dihilangkan, nilai default 1000 tidak akan menggantikan klausa LIMIT kueri GQL dan hanya berlaku jika tidak ada klausa LIMIT yang ditentukan.

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.GqlQuery(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

kursor ()

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.