Firestore dalam mode Datastore menggunakan indeks untuk setiap kueri yang dibuat aplikasi Anda.
Indeks ini diperbarui setiap kali entity berubah, sehingga hasilnya dapat
ditampilkan dengan cepat saat aplikasi membuat kueri. Mode Datastore menyediakan indeks bawaan secara otomatis, tetapi perlu mengetahui indeks komposit yang akan diperlukan aplikasi terlebih dahulu. Anda menentukan indeks komposit yang diperlukan aplikasi Anda dalam file konfigurasi. Emulator Datastore dapat
menghasilkan konfigurasi indeks gabungan mode Datastore secara otomatis saat Anda menguji
aplikasi. Alat command line gcloud
menyediakan perintah untuk memperbarui
indeks yang tersedia untuk database mode Datastore produksi Anda.
Persyaratan sistem
Untuk menggunakan gcloud CLI, Anda harus menginstal Google Cloud CLI.
Tentang index.yaml
Setiap kueri mode Datastore yang dibuat oleh aplikasi memerlukan indeks yang sesuai.
Indeks untuk kueri sederhana, seperti kueri atas satu properti, dibuat secara otomatis. Indeks komposit untuk kueri kompleks harus ditentukan dalam file konfigurasi bernama index.yaml
. File ini diupload dengan aplikasi untuk membuat
indeks komposit dalam database mode Datastore.
Emulator Datastore akan otomatis menambahkan item ke file ini saat aplikasi mencoba menjalankan kueri yang memerlukan indeks gabungan yang tidak memiliki entri yang sesuai dalam file konfigurasi. Anda dapat menyesuaikan indeks gabungan atau membuat indeks baru secara manual dengan mengedit file. index.yaml
terletak di
folder <project-directory>/WEB-INF/
. Secara default, direktori data yang
berisi WEB-INF/appengine-generated/index.yaml
adalah
~/.config/gcloud/emulators/datastore/
. Lihat
direktori project emulator Datastore untuk detail tambahan.
Berikut adalah contoh file index.yaml
:
indexes:
- kind: Task
ancestor: no
properties:
- name: done
- name: priority
direction: desc
- kind: Task
properties:
- name: collaborators
direction: asc
- name: created
direction: desc
- kind: TaskList
ancestor: yes
properties:
- name: percent_complete
direction: asc
- name: type
direction: asc
Sintaksis index.yaml
adalah format YAML. Untuk mengetahui informasi selengkapnya tentang sintaksis ini, lihat situs YAML.
Definisi Indeks Gabungan
index.yaml
memiliki satu elemen daftar yang disebut indexes
. Setiap elemen dalam
daftar mewakili indeks komposit untuk aplikasi.
Elemen indeks dapat memiliki elemen berikut:
kind
- Jenis entity untuk kueri. Elemen ini bersifat wajib.
properties
Daftar properti yang akan disertakan sebagai kolom indeks komposit, yang akan diurutkan: properti yang digunakan dalam filter kesetaraan terlebih dahulu, diikuti dengan properti yang digunakan dalam filter ketidaksetaraan, lalu tata urutan dan arahnya.
Setiap elemen dalam daftar ini memiliki elemen berikut:
name
- Nama mode Datastore properti.
direction
- Arah dalam mengurutkan,
asc
untuk menaik ataudesc
untuk menurun. Ini hanya diperlukan untuk properti yang digunakan dalam tata urutan kueri, dan harus sesuai dengan arah yang digunakan oleh kueri. Defaultnya adalahasc
.
ancestor
yes
jika kueri memiliki klausa ancestor. Defaultnya adalahno
.
Indeks komposit otomatis dan manual
Saat emulator Datastore menambahkan definisi indeks komposit yang dihasilkan ke
index.yaml
, emulator akan melakukannya di bawah baris berikut, menyisipkannya jika perlu:
# AUTOGENERATED
Emulator menganggap semua definisi indeks komposit di bawah baris ini bersifat otomatis, dan dapat memperbarui definisi yang ada di bawah baris ini saat aplikasi membuat kueri.
Semua definisi indeks komposit di atas baris ini dianggap berada di bawah kontrol manual,
dan tidak diupdate oleh emulator. Emulator hanya akan
membuat perubahan di bawah baris, dan hanya akan melakukannya jika file index.yaml
lengkap tidak mendeskripsikan indeks gabungan yang memperhitungkan kueri yang dijalankan oleh
aplikasi. Untuk mengontrol definisi indeks komposit otomatis, pindahkan ke atas baris ini.
Memperbarui indeks komposit
Perintah datastore indexes create
melihat konfigurasi indeks komposit Datastore lokal Anda (file index.yaml
), dan jika konfigurasi indeks komposit menentukan indeks komposit yang belum ada dalam database mode Datastore produksi, database Anda akan membuat indeks komposit baru. Lihat alur kerja pengembangan menggunakan gcloud CLI untuk mengetahui contoh cara menggunakan indexes create
.
Untuk membuat indeks gabungan, database harus menyiapkan indeks gabungan, lalu mengisi ulang indeks gabungan dengan data yang ada. Waktu pembuatan indeks komposit adalah jumlah waktu penyiapan dan waktu pengisian ulang:
Menyiapkan indeks komposit memerlukan waktu beberapa menit. Waktu pembuatan minimum untuk indeks komposit adalah beberapa menit, meskipun untuk database yang kosong.
Waktu pengisian ulang bergantung pada jumlah data yang ada dalam indeks komposit baru. Semakin banyak nilai properti yang termasuk dalam indeks komposit, semakin lama waktu yang diperlukan untuk mengisi ulang indeks komposit.
Jika aplikasi menjalankan kueri yang memerlukan indeks gabungan yang belum selesai di-build, kueri akan menampilkan pengecualian. Untuk mencegah hal ini, Anda harus berhati-hati saat men-deploy versi baru aplikasi yang memerlukan indeks komposit sebelum indeks komposit baru selesai di-build.
Anda dapat memeriksa status indeks gabungan dari halaman Indexes di konsol Google Cloud.
Menghapus indeks komposit yang tidak digunakan
Saat Anda mengubah atau menghapus indeks komposit dari konfigurasi indeks komposit, indeks komposit asli tidak akan otomatis dihapus dari database mode Datastore. Hal ini memberi Anda kesempatan untuk membiarkan aplikasi versi lama tetap berjalan saat indeks komposit baru sedang dibuat, atau segera kembali ke versi lama jika ada masalah pada versi yang lebih baru.
Setelah yakin bahwa indeks komposit lama tidak lagi diperlukan, Anda dapat menghapusnya
menggunakan perintah datastore indexes cleanup
. Perintah ini menghapus semua indeks gabungan untuk instance mode Datastore produksi yang tidak disebutkan dalam index.yaml
versi lokal. Lihat alur kerja pengembangan menggunakan gcloud CLI untuk mengetahui contoh cara menggunakan indexes cleanup
.
Argumen command line
Untuk mengetahui detail tentang argumen command line untuk membuat dan membersihkan indeks komposit, lihat
datastore indexes create
dan datastore indexes cleanup
,
masing-masing. Untuk mengetahui detail tentang argumen command line untuk gcloud CLI, lihat
referensi gcloud CLI.
Mengelola operasi yang berjalan lama
Build indeks komposit adalah operasi yang berjalan lama dan dapat memerlukan waktu yang cukup lama untuk diselesaikan.
Setelah Anda memulai build indeks komposit, mode Datastore akan menetapkan nama unik untuk operasi tersebut. Nama operasi diawali dengan projects/[PROJECT_ID]/databases/(default)/operations/
, misalnya:
projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg
Namun, Anda dapat tidak menyertakan awalan saat menentukan nama operasi untuk perintah describe
.
Mencantumkan semua operasi yang berjalan lama
Untuk mencantumkan operasi yang berjalan lama, gunakan perintah gcloud datastore operations list. Perintah ini mencantumkan operasi yang sedang berlangsung dan yang baru saja selesai. Operasi tercantum selama beberapa hari setelah selesai:
gcloud
gcloud datastore operations list
istirahat
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- project-id: project ID Anda
Metode HTTP dan URL:
GET https://datastore.googleapis.com/v1/projects/project-id/operations
Untuk mengirim permintaan, perluas salah satu opsi berikut:
Lihat informasi tentang respons di bawah.
Misalnya, build indeks komposit yang baru saja selesai menampilkan informasi berikut:
{ "operations": [ { "name": "projects/project-id/operations/S01vcFVpSmdBQ0lDDCoDIGRiNTdiZDQNmE4YS0yMTVmNWUzZSQadGx1YWZlZAcSMXRzYWVzdS1yZXhlZG5pLW5pbWRhFQpWEg", "done": true, "metadata": { "@type": "type.googleapis.com/google.datastore.admin.v1.IndexOperationMetadata", "common": { "endTime": "2020-06-23T16:55:29.923562Z", "operationType": "CREATE_INDEX", "startTime": "2020-06-23T16:55:10Z", "state": "SUCCESSFUL" }, "indexId": "CICAJiUpoMK", "progressEntities": { "workCompleted": "2193027", "workEstimated": "2198182" } }, "response": { "@type": "type.googleapis.com/google.datastore.admin.v1.Index", "ancestor": "NONE", "indexId": "CICAJiUpoMK", "kind": "Task", "projectId": "project-id", "properties": [ { "direction": "ASCENDING", "name": "priority" }, { "direction": "ASCENDING", "name": "done" }, { "direction": "DESCENDING", "name": "created" } ], "state": "READY" } }, ] }
Menjelaskan satu operasi
Alih-alih mencantumkan semua operasi yang berjalan lama, Anda dapat mencantumkan detail satu operasi:
gcloud
Gunakan perintah operations describe
untuk menampilkan status build indeks komposit.
gcloud datastore operations describe operation-name
istirahat
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- project-id: project ID Anda
Metode HTTP dan URL:
GET https://datastore.googleapis.com/v1/projects/project-id/operations
Untuk mengirim permintaan, perluas salah satu opsi berikut:
Lihat informasi tentang respons di bawah.
Memperkirakan waktu penyelesaian
Saat operasi berjalan, lihat nilai kolom state
untuk mengetahui status operasi secara keseluruhan.
Permintaan untuk status operasi yang berjalan lama juga menampilkan metrik workEstimated
dan workCompleted
. Metrik ini ditampilkan untuk jumlah entity. workEstimated
menunjukkan perkiraan jumlah total entitas yang akan diproses oleh operasi, berdasarkan statistik database. workCompleted
menunjukkan jumlah entitas yang diproses sejauh ini. Setelah operasi selesai, workCompleted
mencerminkan jumlah total entity yang sebenarnya diproses yang mungkin berbeda dari nilai workEstimated
.
Bagilah workCompleted
dengan workEstimated
untuk mengetahui perkiraan kasar dari progresnya. Perkiraan ini mungkin tidak akurat karena tergantung pada pengumpulan statistik yang tertunda.
Misalnya, berikut adalah status progres build indeks komposit:
{ "operations": [ { "name": "projects/project-id/operations/AyAyMDBiM2U5NTgwZDAtZGIyYi0zYjc0LTIzYWEtZjg1ZGdWFmZWQHEjF0c2Flc3UtcmV4ZWRuaS1uaW1kYRUKSBI", "metadata": { "@type": "type.googleapis.com/google.datastore.admin.v1.IndexOperationMetadata", "common": { "operationType": "CREATE_INDEX", "startTime": "2020-06-23T16:52:25.697539Z", "state": "PROCESSING" }, "progressEntities": { "workCompleted": "219327", "workEstimated": "2198182" } }, }, ...
Saat operasi selesai, deskripsi operasi akan berisi "done":
true
. Lihat nilai kolom state
untuk menemukan hasil operasi. Jika kolom done
tidak ditetapkan dalam respons, maka nilainya adalah false
. Jangan bergantung pada keberadaan nilai done
untuk operasi yang sedang berlangsung.