Konfigurasi Indeks Komposit

Firestore dalam mode Datastore menggunakan indeks untuk setiap kueri yang dibuat aplikasi Anda. Indeks ini diupdate setiap kali entity berubah, sehingga hasilnya dapat ditampilkan dengan cepat saat aplikasi membuat kueri. Mode Datastore menyediakan indeks bawaan secara otomatis, tetapi perlu mengetahui terlebih dahulu indeks komposit yang diperlukan aplikasi. Anda menentukan indeks komposit yang diperlukan aplikasi Anda dalam file konfigurasi. Emulator Datastore dapat menghasilkan konfigurasi indeks komposit mode Datastore secara otomatis saat Anda menguji aplikasi. Alat command line gcloud memberikan perintah untuk mengupdate indeks yang tersedia bagi database mode Datastore produksi Anda.

Persyaratan sistem

Untuk menggunakan gcloud CLI, Anda harus sudah 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 pada 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 secara otomatis menambahkan item ke file ini saat aplikasi mencoba menjalankan kueri yang memerlukan indeks komposit yang tidak memiliki entri yang sesuai dalam file konfigurasi. Anda dapat menyesuaikan indeks komposit 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 informasi lebih lanjut tentang sintaksis ini, lihat situs YAML.

Definisi Indeks Komposit

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, dalam urutan 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 pengurutan, asc untuk naik atau desc untuk menurun. Ini hanya diperlukan untuk properti yang digunakan dalam tata urutan kueri, dan harus sesuai dengan arah yang digunakan oleh kueri. Defaultnya adalah asc.

ancestor

yes jika kueri memiliki klausa ancestor. Defaultnya adalah no.

Indeks komposit otomatis dan manual

Saat menambahkan definisi indeks komposit yang dihasilkan ke index.yaml, emulator Datastore akan melakukannya di bawah baris berikut, dan memasukkannya 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 garis, dan hanya akan melakukannya jika file index.yaml lengkap tidak menjelaskan indeks komposit yang memperhitungkan kueri yang dieksekusi 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 Anda, database Anda akan membuat indeks komposit baru. Lihat alur kerja pengembangan menggunakan gcloud CLI untuk mengetahui contoh cara menggunakan indexes create.

Untuk membuat indeks komposit, database harus menyiapkan indeks komposit, lalu mengisi ulang indeks komposit 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, bahkan 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 komposit yang belum selesai di-build, kueri akan memunculkan pengecualian. Untuk mencegah hal ini, Anda harus berhati-hati dalam men-deploy versi baru aplikasi yang memerlukan indeks komposit sebelum indeks komposit baru selesai di-build.

Anda dapat memeriksa status indeks komposit dari halaman Indexes di Google Cloud Console.

Menghapus indeks komposit yang tidak digunakan

Saat Anda mengubah atau menghapus indeks komposit dari konfigurasi indeks komposit, indeks komposit asli tidak akan dihapus dari database mode Datastore Anda secara otomatis. Hal ini memberi Anda kesempatan untuk membiarkan aplikasi versi lama tetap berjalan saat indeks komposit baru sedang di-build, atau segera kembali ke versi lama jika ada masalah dengan 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 komposit untuk instance mode Datastore produksi yang tidak disebutkan dalam versi lokal index.yaml. Lihat alur kerja pengembangan menggunakan gcloud CLI untuk mengetahui contoh cara menggunakan indexes cleanup.

Argumen command line

Untuk detail tentang argumen command line untuk membuat dan membersihkan indeks komposit, lihat masing-masing datastore indexes create dan datastore indexes cleanup. Untuk mengetahui detail tentang argumen command line untuk gcloud CLI, baca referensi gcloud CLI.

Mengelola operasi yang berjalan lama

Build indeks komposit adalah operasi yang berjalan lama dan dapat memerlukan waktu lama untuk diselesaikan.

Setelah Anda memulai build indeks komposit, mode Datastore menetapkan nama yang 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 menampilkan daftar 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:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke CLI gcloud. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Jalankan perintah berikut:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/operations"

PowerShell (Windows)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke CLI gcloud dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang aktif saat ini dengan menjalankan gcloud auth list.

Jalankan perintah berikut:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/operations" | Select-Object -Expand Content

Lihat informasi tentang responsnya di bawah ini.

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"
    }
  },
  ]
}

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

curl (Linux, macOS, atau Cloud Shell)

Jalankan perintah berikut:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/operations"

PowerShell (Windows)

Jalankan perintah berikut:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/operations" | Select-Object -Expand Content

Lihat informasi tentang responsnya di bawah ini.

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 entity yang akan diproses oleh sebuah operasi, berdasarkan statistik database. workCompleted menunjukkan jumlah entity yang diproses sejauh ini. Setelah operasi selesai, workCompleted mencerminkan jumlah total entity yang benar-benar 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.