Kueri Datastore

Kueri Datastore mengambil entity dari Cloud Datastore yang memenuhi kumpulan kondisi tertentu.

Kueri tipikal mencakup hal berikut:

  • Jenis entity yang menerapkan kueri
  • Filter opsional berdasarkan nilai properti, kunci, dan ancestor entity
  • Tata urutan opsional untuk mengurutkan hasil
Saat dieksekusi, kueri mengambil semua entity dari jenis tertentu yang memenuhi semua filter yang diberikan, yang diurutkan dalam urutan yang ditentukan. Kueri dijalankan sebagai hanya baca.

Halaman ini menjelaskan struktur dan jenis kueri yang digunakan dalam App Engine untuk mengambil data dari Cloud Datastore.

Filter

Filter kueri menetapkan batasan pada properti, kunci, dan ancestor dari entity yang akan diambil.

Filter properti

Filter properti menentukan

  • Nama properti
  • Operator perbandingan
  • Nilai properti
Contoh:

q := datastore.NewQuery("Person").Filter("Height <=", maxHeight)

Nilai properti harus diberikan oleh aplikasi; ini tidak bisa merujuk ke atau dihitung dari segi properti lainnya. Entity memenuhi filter jika memiliki properti dengan nama tertentu yang nilainya dibandingkan dengan nilai yang ditentukan dalam filter dengan cara yang dijelaskan oleh operator perbandingan.

Operator perbandingan dapat berupa salah satu dari yang berikut:

Operator Arti
= Sama dengan
< Kurang dari
<= Kurang dari atau sama dengan
> Lebih dari
>= Lebih dari atau sama dengan

Filter utama

Untuk memfilter nilai kunci entity, gunakan properti khusus __key__:

q := datastore.NewQuery("Person").Filter("__key__ >", lastSeenKey)

Saat membandingkan ketidaksetaraan, kunci diurutkan berdasarkan kriteria berikut secara berurutan:

  1. Jalur ancestor
  2. Jenis entity
  3. ID (nama kunci atau ID numerik)

Elemen jalur ancestor dibandingkan dengan cara serupa: berdasarkan jenis (string), lalu menurut nama kunci atau ID numerik. Jenis dan nama kunci merupakan string dan diurutkan berdasarkan nilai byte; ID numerik adalah bilangan bulat dan diurutkan secara numerik. Jika entity dengan induk dan jenis yang sama menggunakan campuran string nama kunci dan ID numerik, entity dengan ID numerik akan mendahului nama kunci tersebut.

Kueri pada kunci menggunakan indeks seperti kueri pada properti dan memerlukan indeks kustom dalam kasus yang sama, dengan beberapa pengecualian: filter ketidaksetaraan atau tata urutan menaik pada kunci tidak memerlukan indeks kustom, tetapi adanya tata urutan menurun pada kunci. Seperti halnya semua kueri, server web pengembangan membuat entri yang sesuai dalam file konfigurasi indeks saat kueri yang membutuhkan indeks kustom diuji.

Filter ancestor

Anda dapat memfilter kueri Datastore ke ancestor yang ditentukan sehingga hasil yang ditampilkan hanya akan menyertakan entity yang diturunkan dari ancestor tersebut:

q := datastore.NewQuery("Person").Ancestor(ancestorKey)

Jenis kueri khusus

Beberapa jenis kueri tertentu perlu disebutkan secara khusus:

Kueri tanpa jenis

Kueri tanpa jenis dan filter ancestor mengambil semua entity aplikasi dari Datastore. Ini termasuk entity yang dibuat dan dikelola oleh fitur App Engine lainnya, seperti entity statistik dan entity metadata Blobstore (jika ada). Kueri tanpa jenis tersebut tidak boleh menyertakan filter atau tata urutan pada nilai properti. Namun, kueri tersebut dapat memfilter kunci entity dengan menentukan __key__ sebagai nama properti:

q := datastore.NewQuery("").Filter("__key__ >", lastSeenKey)

Kueri ancestor

Kueri dengan filter ancestor membatasi hasilnya ke entity yang ditentukan dan turunannya:

// Create two Photo entities in the datastore with a Person as their ancestor.
tomKey := datastore.NewKey(ctx, "Person", "Tom", 0, nil)

wPhoto := Photo{URL: "http://example.com/some/path/to/wedding_photo.jpg"}
wKey := datastore.NewKey(ctx, "Photo", "", 0, tomKey)
_, err := datastore.Put(ctx, wKey, wPhoto)
// check err

bPhoto := Photo{URL: "http://example.com/some/path/to/baby_photo.jpg"}
bKey := datastore.NewKey(ctx, "Photo", "", 0, tomKey)
_, err = datastore.Put(ctx, bKey, bPhoto)
// check err

// Now fetch all Photos that have tomKey as an ancestor.
// This will populate the photos slice with wPhoto and bPhoto.
q := datastore.NewQuery("Photo").Ancestor(tomKey)
var photos []Photo
_, err = q.GetAll(ctx, &photos)
// check err
// do something with photos

Kueri ancestor tanpa jenis

Kueri tanpa jenis yang menyertakan filter ancestor akan mengambil ancestor yang ditentukan dan semua turunannya, apa pun jenisnya. Jenis kueri ini tidak memerlukan indeks kustom. Seperti semua kueri tanpa jenis, kueri tidak dapat menyertakan filter atau tata urutan pada nilai properti, tetapi dapat memfilter kunci entity:

q := datastore.NewQuery("").Ancestor(ancestorKey).Filter("__key__ >", lastSeenKey)

Contoh berikut menggambarkan cara mengambil semua entity yang merupakan turunan dari ancestor tertentu:

tomKey := datastore.NewKey(ctx, "Person", "Tom", 0, nil)

weddingPhoto := &Photo{URL: "http://example.com/some/path/to/wedding_photo.jpg"}
_, err := datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Photo", tomKey), weddingPhoto)

weddingVideo := &Video{URL: "http://example.com/some/path/to/wedding_video.avi"}
_, err = datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Video", tomKey), weddingVideo)

// The following query returns both weddingPhoto and weddingVideo,
// even though they are of different entity kinds.
q := datastore.NewQuery("").Ancestor(tomKey)
t := q.Run(ctx)
for {
	var x interface{}
	_, err := t.Next(&x)
	if err == datastore.Done {
		break
	}
	if err != nil {
		log.Errorf(ctx, "fetching next Photo/Video: %v", err)
		break
	}
	// Do something (e.g. switch on types)
	doSomething(x)
}

Kueri khusus kunci

Kueri khusus kunci hanya menampilkan kunci entity hasil, bukan entity itu sendiri, dengan latensi dan biaya yang lebih rendah daripada mengambil seluruh entity:

q := datastore.NewQuery("Person").KeysOnly()

Sering kali lebih ekonomis untuk melakukan kueri khusus kunci terlebih dahulu, lalu mengambil subset entity dari hasil, daripada menjalankan kueri umum yang dapat mengambil lebih banyak entity daripada yang sebenarnya Anda butuhkan.

Perhatikan bahwa kueri khusus kunci dapat menampilkan lebih dari 1000 hasil, tetapi GetAll hanya dapat mengambil 1000 kunci sekaligus, dan akan gagal dengan error jika dipanggil pada hasil yang lebih besar. Oleh karena itu, sebaiknya tambahkan batas 1000 kunci ke kueri.

Kueri proyeksi

Terkadang yang sangat Anda perlukan dari hasil kueri adalah nilai dari beberapa properti tertentu. Dalam kasus seperti itu, Anda dapat menggunakan kueri proyeksi untuk mengambil properti yang benar-benar Anda minati saja, dengan latensi dan biaya yang lebih rendah daripada mengambil seluruh entity; lihat halaman Kueri Proyeksi untuk mengetahui detailnya.

Tata urutan

Tata urutan kueri menentukan

  • Nama properti
  • Arah pengurutan (menaik atau menurun)

Di Go, tata urutan menurun dilambangkan dengan tanda hubung (-) sebelum nama properti; menghilangkan tanda hubung untuk menentukan urutan naik secara default. Contoh:

// Order alphabetically by last name:
q := datastore.NewQuery("Person").Order("LastName")

// Order by height, tallest to shortest:
q = datastore.NewQuery("Person").Order("-Height")

Jika kueri menyertakan beberapa tata urutan, maka akan diterapkan dalam urutan yang ditentukan. Contoh berikut mengurutkan nama belakang secara menaik, lalu mengurutkan tinggi secara menurun:

q := datastore.NewQuery("Person").Order("LastName").Order("-Height")

Jika tidak ada tata urutan yang ditentukan, hasilnya akan ditampilkan sesuai urutan pengambilannya dari Datastore.

Catatan: Karena cara Datastore mengeksekusi kueri, jika kueri menentukan filter ketidaksetaraan di properti dan tata urutan di properti lain, properti yang digunakan dalam filter ketidaksetaraan harus diurutkan sebelum properti lainnya.

Indeks

Setiap kueri Datastore menghitung hasilnya menggunakan satu atau beberapa indeks, yang berisi kunci entity dalam urutan yang ditentukan oleh properti indeks dan, secara opsional, ancestor entity. Indeks diperbarui secara bertahap untuk mencerminkan setiap perubahan yang dilakukan aplikasi pada entity-nya, sehingga hasil yang benar dari semua kueri tersedia tanpa perlu komputasi lebih lanjut.

App Engine menentukan terlebih dahulu indeks sederhana di setiap properti entity. Aplikasi App Engine dapat menentukan indeks kustom lebih lanjut dalam file konfigurasi indeks bernama index.yaml. Server pengembangan secara otomatis menambahkan saran ke file ini karena menemukan kueri yang tidak dapat dijalankan dengan indeks yang ada. Anda dapat menyesuaikan indeks secara manual dengan mengedit file sebelum mengupload aplikasi.

Contoh antarmuka kueri

Go Datastore API menyediakan Jenis kueri untuk menyiapkan dan menjalankan kueri.

type Person struct {
	FirstName string
	LastName  string
	City      string
	BirthYear int
	Height    int
}

func handle(w http.ResponseWriter, r *http.Request) {
	ctx := appengine.NewContext(r)

	// The Query type and its methods are used to construct a query.
	q := datastore.NewQuery("Person").
		Filter("LastName =", "Smith").
		Filter("Height <=", maxHeight).
		Order("-Height")

	// To retrieve the results,
	// you must execute the Query using its GetAll or Run methods.
	var people []Person
	if _, err := q.GetAll(ctx, &people); err != nil {
		// Handle error.
	}
	// ...
}

Apa langkah selanjutnya?