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.

Referensi GQL untuk Python NDB/DB

GQL adalah bahasa yang mirip SQL dengan fungsi untuk mengambil entity dan kunci. Sintaksis untuk kueri GQL mirip dengan SQL. Halaman ini merupakan referensi untuk menggunakan GQL dengan library klien Python NDB dan DB.

GQL dipetakan secara kasar ke SQL: Anda dapat menganggap kind GQL sebagai tabel SQL, entity GQL sebagai baris SQL, dan property GQL sebagai kolom SQL. Namun, pencarian baris-kolom SQL adalah nilai tunggal, sedangkan di GQL, nilai properti dapat berupa daftar.

Versi GQL

Anda memerlukan versi GQL yang berbeda, bergantung pada tempat Anda menjalankan kueri. Ada dua referensi GQL:

Referensi GQL untuk Python NDB/DB, untuk tata bahasa GQL yang digunakan dalam library klien NDB dan DB (gunakan referensi di halaman ini).
Referensi GQL, untuk tata bahasa GQL yang digunakan dalam Datastore API saat ini dan Viewer Datastore konsol Google Cloud.

Sintaksis

Sintaksis GQL untuk Python NDB/DB dapat dirangkum sebagai berikut:

SELECT [DISTINCT] [* | <property list> | __key__]
  [FROM <kind>]
  [WHERE <condition> [AND <condition> ...]]
  [ORDER BY <property> [ASC | DESC] [, <property> [ASC | DESC] ...]]
  [LIMIT [<offset>,]<count>]
  [OFFSET <offset>]

  <property list> := <property> [, <property> ...]
  <condition> := <property> {< | <= | > | >= | = | != } <value>
  <condition> := <property> IN <list>
  <condition> := ANCESTOR IS <entity or key>
  <list> := (<value> [, <value> ...]])

Seperti halnya SQL, kata kunci GQL tidak peka pada huruf besar/kecil. Nama jenis dan properti peka pada huruf besar/kecil.

GQL hanya mendukung pernyataan SELECT.

Kueri GQL menampilkan nol atau beberapa entity, entity yang diproyeksikan, atau kunci dari jenis yang diminta. Setiap kueri GQL selalu dimulai dengan SELECT *, SELECT __key__, atau SELECT <property list>, dengan property adalah daftar yang dipisahkan koma yang berisi satu atau beberapa properti entity yang akan ditampilkan dari kueri. (Kueri GQL tidak dapat menjalankan kueri "join" seperti SQL.)

Tips: Kueri SELECT __key__ or SELECT <property list> lebih cepat dan menggunakan lebih sedikit waktu CPU daripada kueri SELECT *.

Klausa DISTINCT^{(eksperimental)} opsional menentukan bahwa hanya hasil yang benar-benar unik yang akan ditampilkan dalam kumpulan hasil. Tindakan ini hanya akan menampilkan hasil pertama untuk entity yang memiliki nilai yang sama untuk properti yang sedang diproyeksikan.

Klausa FROM opsional membatasi hasil yang ditetapkan pada entity dari jenis tertentu. Kueri tanpa klausa FROM disebut sebagai kueri yang tidak serupa dan hanya dapat memiliki WHERE yang menentukan properti __key__.

Klausa WHERE opsional membatasi hasil yang ditetapkan pada entity yang memenuhi satu atau beberapa kondisi. Setiap kondisi membandingkan properti entity dengan nilai menggunakan operator perbandingan. Jika beberapa kondisi diberikan dengan kata kunci AND, entity harus memenuhi semua kondisi yang akan ditampilkan oleh kueri. GQL tidak memiliki operator OR. Namun, metode ini memiliki operator IN, yang menyediakan bentuk OR terbatas.

Operator IN membandingkan nilai properti dengan setiap item dalam daftar. Operator IN setara dengan banyak kueri =, satu untuk setiap nilai, yang digabungkan dengan OR. Entity yang nilainya untuk properti tertentu sama dengan salah satu nilai dalam daftar dapat ditampilkan untuk kueri.

Catatan: Operator IN dan != menggunakan beberapa kueri di balik layar. Misalnya, operator IN mengeksekusi kueri datastore dasar secara terpisah untuk setiap item dalam daftar. Entity yang ditampilkan adalah hasil silang dari semua kueri datastore yang mendasarinya dan dihapus duplikatnya. Maksimum 30 kueri datastore diizinkan untuk setiap kueri GQL.

Suatu kondisi juga dapat menguji apakah suatu entity memiliki entity tertentu sebagai ancestor, menggunakan operator ANCESTOR IS. Nilainya adalah instance model atau kunci untuk entity ancestor. Untuk informasi selengkapnya tentang ancestor, lihat Kunci dan Grup Entity.

Sisi kiri perbandingan selalu berupa nama properti. Nama properti standar terdiri dari karakter alfanumerik yang secara opsional dicampur dengan garis bawah dan titik. Dengan kata lain, nilai tersebut cocok dengan ekspresi reguler [a-zA-Z0-9_]+(\.[a-zA-Z0-9_]+)*.

Perhatian: Nama properti yang berisi karakter lain yang dapat dicetak harus diberi tanda kutip dengan tanda kutip ganda. Contoh: "first-name". Spasi atau karakter yang tidak dapat dicetak dalam nama properti tidak didukung.

Sisi kanan perbandingan dapat berupa salah satu dari berikut ini (sesuai dengan jenis data properti):

literal str, sebagai string dengan tanda kutip tunggal. Karakter tanda kutip tunggal dalam string harus di-escape sebagai ''. Contoh: 'Joe''s Diner'
bilangan bulat atau literal angka floating point. Contoh: 42.7
literal Boolean, seperti TRUE atau FALSE.
literal NULL, yang mewakili nilai null (None di Python).
tanggal, waktu, atau literal waktu, dengan nilai numerik atau representasi string, dalam bentuk berikut:
- DATETIME(year, month, day, hour, minute, second)
- DATETIME('YYYY-MM-DD HH:MM:SS')
- DATE(year, month, day)
- DATE('YYYY-MM-DD')
- TIME(hour, minute, second)
- TIME('HH:MM:SS')
literal kunci entity, dengan kunci yang dienkode ke string atau jalur lengkap dari berbagai jenis dan nama/ID kunci:
- KEY('encoded key')
- KEY('kind', 'name'/ID [, 'kind', 'name'/ID...])
literal objek Pengguna, dengan alamat email pengguna:
USER('email-address')
literal GeoPt, dengan lintang dan bujur sebagai nilai floating point:
GEOPT(lat, long)
nilai parameter terikat. Dalam string kueri, parameter posisi direferensikan oleh angka: title = :1. Parameter kata kunci direferensikan berdasarkan nama: title = :mytitle

Catatan: kondisi bentuk property = NULL periksa apakah nilai null disimpan secara eksplisit dalam datastore untuk properti tersebut atau tidak. Hal ini berbeda dengan memeriksa apakah entity tidak memiliki nilai untuk properti! Kueri Datastore yang merujuk ke properti tidak pernah menampilkan entity yang tidak memiliki nilai untuk properti tersebut.

Parameter terikat dapat diikat sebagai argumen posisi atau argumen kata kunci yang diteruskan ke konstruktor GqlQuery atau class model metode gql(). Jenis data properti yang tidak memiliki sintaksis literal nilai yang sesuai harus ditentukan menggunakan binding parameter, termasuk jenis data daftar. Binding parameter dapat diikat kembali dengan nilai baru selama masa aktif instance GqlQuery (misalnya untuk menggunakan kembali kueri secara efisien) menggunakan metode bind() tersebut.

Klausa ORDER BY opsional menunjukkan bahwa hasil harus ditampilkan berdasarkan properti yang ditentukan, dalam urutan menaik (ASC) atau menurun (DESC). Klausa ORDER BY dapat menentukan beberapa tata urutan sebagai daftar yang dipisahkan koma, yang dievaluasi dari kiri ke kanan. Jika arah tidak ditentukan, nilai defaultnya adalah ASC. Jika tidak ada klausa ORDER BY yang ditentukan, urutan hasilnya tidak akan ditentukan dan dapat berubah dari waktu ke waktu.

Klausa LIMIT opsional menyebabkan kueri berhenti menampilkan hasil setelah entity <count> pertama. Klausa LIMIT juga dapat menyertakan <offset>, untuk melewati banyak hasil tersebut guna menemukan hasil pertama yang akan ditampilkan. Klausa OFFSET opsional dapat menentukan <offset>, jika tidak ada klausa LIMIT.

Catatan: Seperti parameter offset untuk metode fetch(), OFFSET dalam string kueri GQL tidak akan mengurangi jumlah entity yang diambil dari datastore. Hal ini hanya memengaruhi hasil mana yang ditampilkan oleh metode fetch(). Kueri dengan offset memiliki karakteristik performa yang sesuai secara linear dengan ukuran offset ditambah ukuran batas.

Untuk mengetahui informasi tentang cara menjalankan kueri GQL, parameter binding, dan mengakses hasil, baca class GqlQuery, dan metode class Model.gql().

Contoh

from google.appengine.ext import db

class Person(db.Model):
  name = db.StringProperty()
  age = db.IntegerProperty()

# We use a unique username for the Entity's key.
amy = Person(key_name='amym', name='Amy', age=48)
amy.put()
Person(key_name='bettyd', name='Betty', age=42).put()
Person(key_name='charliec', name='Charlie', age=32).put()
Person(key_name='charliek', name='Charlie', age=29).put()
Person(key_name='eedna', name='Edna', age=20).put()
Person(key_name='fredm', name='Fred', age=16, parent=amy).put()
Person(key_name='georgemichael', name='George').put()

Untuk menemukan semua entity dari jenis Person yang usianya antara 18 dan 35 tahun (yaitu Charlies dan Edna), gunakan kueri ini:

SELECT * FROM Person WHERE age >= 18 AND age <= 35

Untuk menemukan tiga entity dari jenis Person yang usianya paling tinggi (yaitu Amy, Betty, dan Charlie), gunakan kueri ini:

SELECT * FROM Person ORDER BY age DESC LIMIT 3

Untuk menemukan entity jenis Person yang namanya adalah salah satu dari "Betty" atau "Charlie", gunakan kueri ini:

SELECT * FROM Person WHERE name IN ('Betty', 'Charlie')

Untuk menampilkan hanya nilai name bagi setiap Person, gunakan kueri ini:

SELECT name FROM Person

Untuk menampilkan nilai name saja bagi setiap Person, yang diurutkan berdasarkan age, gunakan kueri ini:

SELECT name FROM Person ORDER BY age

Untuk menemukan kunci entity dari jenis Person yang memiliki usia None (yaitu KEY('Person', 'georgemichael')), gunakan kueri ini:

SELECT __key__ FROM Person WHERE age = NULL

Untuk menemukan semua entity, terlepas dari jenisnya, yang ada dalam grup entity Amy (yaitu Amy dan Fred), gunakan kueri ini:

SELECT * WHERE __key__ HAS ANCESTOR KEY(Person, 'Amy')

Untuk mencocokkan berdasarkan Kunci, kita dapat menggunakan __key__ di sisi kiri kondisi. Misalnya, kita dapat menggunakan ini untuk mendapatkan semua entity Person yang memiliki nama pengguna yang dimulai dengan "a".

SELECT * FROM Person WHERE __key__ >= KEY('Person', 'a') AND __key__ < KEY('Person', 'b')

Catatan: Jika Anda pernah membuat kueri dengan kesetaraan di __key__, sebaiknya gunakan get() untuk mengambil entity secara langsung.