Edisi Cloud Firestore Enterprise dalam mode Native kini sudah tersedia. Pelajari lebih lanjut.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Membaca data real-time dengan aliran data perubahan

Aliran Data Perubahan untuk Firestore dengan kompatibilitas MongoDB memungkinkan aplikasi mengakses perubahan real-time (penyisipan, pembaruan, dan penghapusan) yang dilakukan pada koleksi atau seluruh database. Aliran data perubahan mengurutkan pembaruan berdasarkan waktu modifikasi.

Aliran Data Perubahan dapat diakses melalui API yang kompatibel dengan MongoDB dan Driver MongoDB tradisional. Implementasi Aliran Data Perubahan Firestore dengan kompatibilitas MongoDB dapat menangani throughput penulisan dan pembacaan apa pun melalui implementasi unik partisi otomatis pada penulisan dan paralelisme pembacaan. Hal ini memungkinkan Anda membuat workload dengan throughput tinggi. Anda juga dapat meningkatkan infrastruktur migrasi dan sinkronisasi data antara Cloud Firestore dan solusi penyimpanan lainnya.

Selain kompatibilitas dengan driver MongoDB, Anda dapat menggunakan Cloud Firestore untuk membaca Aliran Data Perubahan secara paralel. Hal ini memungkinkan Anda membuat workload pembacaan paralel dengan throughput tinggi. Setiap aliran data mewakili partisi hasil yang terdistribusi dengan baik.

Aliran Data Perubahan mendukung fitur berikut:

Aliran data perubahan yang dapat dikonfigurasi dengan cakupan database atau koleksi.
Durasi retensi untuk aliran data perubahan yang ditentukan saat pembuatan. Retensi default adalah 7 hari dan retensi minimum adalah 1 hari. Retensi harus kelipatan 1 hari, hingga maksimum 7 hari. Durasi retensi tidak dapat diubah setelah pembuatan. Untuk mengubah periode retensi, Anda harus menghapus dan membuat ulang aliran data perubahan.
Peristiwa perubahan delete, insert, update, dan drop yang dapat diamati menggunakan db.collection.watch() dan db.watch().
updateDescription.updatedFields berisi perbedaan pembaruan.
Semua opsi fullDocument dan fullDocumentBeforeChange.
- Mencari dokumen lengkap untuk pembaruan.
- Gambar awal dokumen sebelum diganti, diperbarui, atau dihapus.
- Gambar akhir dokumen setelah diganti atau diperbarui.
- Gambar awal dan akhir yang lebih lama dari satu jam memerlukan pengaktifan pemulihan point-in-time (PITR).
Semua opsi melanjutkan, termasuk resumeAfter dan startAfter.
Saat menggunakan watch() untuk mengamati perubahan, Anda dapat menggabungkan tahap agregasi seperti $addFields, $match, $project, $replaceRoot, $replaceWith, $set, dan $unset.

Mengonfigurasi Aliran Data Perubahan

Untuk membuat, menghapus, atau melihat Aliran Data Perubahan yang ada untuk database, gunakan Google Cloud Console.

Peran dan izin

Untuk membuat, menghapus, dan mencantumkan Aliran Data Perubahan, pokok memerlukan izin Identity and Access Management (IAM) datastore.schemas.create, datastore.schemas.delete, dan datastore.schemas.list, masing-masing.

Misalnya, peran Admin Indeks Datastore (roles/datastore.indexAdmin) memberikan izin ini.

Membuat aliran data perubahan

Sebelum dapat membuka kursor aliran data perubahan yang sesuai, Anda harus membuat aliran data perubahan. Pengaktifan aliran data perubahan otomatis saat pembuatan koleksi atau database tidak didukung.

Untuk membuat aliran data perubahan, gunakan Google Cloud Console.

Di Google Cloud Console, buka halaman Databases.

Buka Databases
Dari daftar, pilih database Firestore dengan kompatibilitas MongoDB. Panel Firestore Studio akan terbuka.
Di panel Explorer, temukan node Change streams, klik More actions, lalu pilih Create change stream.
Masukkan nama, cakupan, dan periode retensi aliran data perubahan yang unik, lalu klik Save

Melihat Aliran Data Perubahan

Anda dapat melihat detail tentang Aliran Data Perubahan di Google Cloud Console.

Di Google Cloud Console, buka halaman Databases.

Buka Databases
Dari daftar, pilih database Firestore dengan kompatibilitas MongoDB. Panel Firestore Studio akan terbuka.
Di panel Explorer, temukan node Change streams.
Untuk membuka atau menutup node, klik Toggle node.

Menghapus aliran data perubahan

Untuk menghapus aliran data perubahan, gunakan Google Cloud Console.

Di Google Cloud Console, buka halaman Databases.

Buka Databases
Dari daftar, pilih database Firestore dengan kompatibilitas MongoDB. Panel Firestore Studio akan terbuka.
Di panel Explorer, temukan node Change streams.
Untuk membuka atau menutup node, klik Toggle node.
Di Explorer, temukan aliran data perubahan yang ingin Anda hapus.
Klik More actions , lalu pilih Delete change stream.
Di dialog, masukkan nama aliran data perubahan untuk mengonfirmasi penghapusan, lalu klik Delete.

Membuka atau melanjutkan kursor aliran data perubahan

Contoh berikut menunjukkan cara membuat, melanjutkan, dan mengonfigurasi kursor aliran data perubahan.

Sebelum membuat kursor aliran data perubahan, Anda harus secara eksplisit membuat aliran data perubahan untuk database atau koleksi.

Membuat kursor aliran data perubahan

Untuk membuat kursor aliran data perubahan baru, gunakan metode watch di driver MongoDB. Untuk memproses semua perubahan pada database, buat aliran data perubahan cakupan database dan panggil metode watch pada objek db.

let cursor = db.watch()

Untuk membuat kursor yang dicakup ke koleksi, Anda harus membuat aliran data perubahan untuk koleksi tersebut terlebih dahulu. Kemudian, panggil metode watch pada koleksi yang sesuai.

let cursor = db.my_collection.watch()

Setelah membuat kursor aliran data perubahan, Anda dapat mulai melakukan streaming. Misalnya, jika Anda menyisipkan dokumen dan memanggil tryNext pada kursor, Anda akan melihat perubahan muncul di aliran data perubahan.

let doc = db.my_collection.insertOne({value: "hello world"})
console.log(cursor.tryNext())

Jika Anda memperbarui dan menghapus dokumen, Anda akan melihat perubahan tersebut muncul di aliran data perubahan:

db.my_collection.updateOne({"_id": doc.insertedId}, {$set: {value: "hello world!"}})
db.my_collection.deleteOne({"_id": doc.insertedId}})

// Prints the update event
console.log(cursor.tryNext())

// Prints the delete event
console.log(cursor.tryNext())

Melanjutkan aliran data perubahan

Untuk melanjutkan aliran data perubahan, gunakan opsi resumeAfter atau startAfter. Untuk menentukan tempat melanjutkan dari resumeAfter dan startAfter di log perubahan, gunakan token resume.

// Create a cursor and add one event to the change stream.
let cursor = db.my_collection.watch();
db.my_collection.insertOne({value: "hello world"});
let event = cursor.tryNext();

// Get the resume token from the event.
let resumeToken = event._id;

// Add a new event to the change stream.
db.my_collection.insertOne({value: "foobar"});

// Create a new cursor by using the resume token as a starting point.
let newCursor = db.my_collection.watch({resumeAfter: resumeToken})

// Log the change event containing the "foobar" value.
console.log(newCursor.tryNext())

Untuk menggunakan startAfter:

// Start after the resume token.
let startAfterCursor = db.my_collection.watch({startAfter: resumeToken})

Menyertakan gambar awal dan akhir dalam pembaruan dan penghapusan

Jika diperlukan, Anda dapat menyertakan gambar awal dan akhir dokumen dalam peristiwa perubahan pembaruan dan penghapusan. Ketersediaan gambar tunduk pada periode pemulihan point-in-time (PITR), dan untuk membaca gambar dokumen yang lebih lama dari satu jam, Anda harus mengaktifkan PITR.

Aliran Data Perubahan memanfaatkan periode PITR untuk memberikan tampilan dokumen sebelum dan setelah peristiwa perubahan tertentu. Secara default, peristiwa pembaruan berisi kolom updateDescription yang merupakan delta kolom yang diubah oleh operasi pembaruan.

Untuk menyertakan gambar awal dan akhir dalam peristiwa perubahan, Anda harus menentukan opsi fullDocumentBeforeChange dan fullDocument dalam kueri aliran data perubahan.

let cursor = db.my_collection.watch({
  "fullDocument": "required",
  "fullDocumentBeforeChange": "required"
})

Jika kueri mencoba membaca dokumen di luar periode retensi PITR atau jika PITR tidak diaktifkan, nilai required akan menampilkan pesan error sisi server.

Sebagai alternatif untuk menampilkan error, Anda dapat menggunakan nilai whenAvailable untuk menampilkan nilai null jika gambar tidak lagi tersedia.

let cursor = db.my_collection.watch({
  "fullDocument": "whenAvailable",
  "fullDocumentBeforeChange": "whenAvailable"
})

Menyertakan gambar saat ini dalam pembaruan

Secara default, peristiwa pembaruan berisi kolom updateDescription yang merupakan delta kolom yang diubah oleh operasi pembaruan. Untuk mencari versi dokumen yang paling baru, gunakan nilai updateLookup dalam opsi fullDocument.

Fitur ini tidak memerlukan PITR dan melakukan pencarian untuk dokumen.

let cursor = db.my_collection.watch({
  "fullDocument": "updateLookup",
})

Operasi Baca Paralel

Untuk meningkatkan throughput, Anda dapat menggunakan opsi firestoreWorkerConfig untuk membagi kueri aliran data perubahan di beberapa pekerja. Setiap pekerja bertanggung jawab untuk menyajikan perubahan untuk kumpulan dokumen yang berbeda. Anda harus membuat kursor paralel melalui kueri runCommand atau aggregate.

Misalnya, Anda dapat mendistribusikan aliran data perubahan di 3 pekerja seperti berikut:

let cursor1 = db.my_collection.aggregate([{
    "$changeStream": {
        "firestoreWorkerConfig": {numWorkers: 3, workerId: 0 }}
  }]);

let cursor2 = db.my_collection.aggregate([{
    "$changeStream": {
        "firestoreWorkerConfig": {numWorkers: 3, workerId: 1 }}
  }]);

let cursor3 = db.my_collection.aggregate([{
    "$changeStream": {
        "firestoreWorkerConfig": {numWorkers: 3, workerId: 2 }}
  }]);

Aliran Data Perubahan dan pencadangan

Konfigurasi aliran data perubahan maupun data aliran data perubahan tidak tersedia dalam operasi pemulihan pencadangan. Jika Anda memulihkan database dengan Aliran Data Perubahan, Anda harus membuat ulang aliran data perubahan tersebut di database tujuan untuk membuka kursor ke database tersebut.

Penagihan

Aliran Data Perubahan dikenai biaya unit baca dan penyimpanan. Lihat harga aliran data perubahan.
Untuk menyertakan gambar awal dan akhir yang lebih lama dari 1 jam pada waktu permintaan baca, Anda harus mengaktifkan PITR yang dikenai biaya PITR.

Perbedaan perilaku

Bagian berikut menjelaskan perbedaan Aliran Data Perubahan antara Firestore dengan kompatibilitas MongoDB dan MongoDB.

`updateDescription`

updateDescription adalah dokumen dalam peristiwa update yang menjelaskan kolom yang diperbarui atau dihapus oleh operasi pembaruan. Di Cloud Firestore, perbedaan pentingnya adalah:

Di updateDescription, kolom truncatedArrays dan disambiguatedPaths tidak diisi.
updateDescription.updatedFields mewakili perbedaan kanonis antara gambar awal dan akhir dokumen sebelum dan setelah mutasi diterapkan.

Pertimbangkan status awal dokumen berikut:

db.my_collection.insertOne({
  _id: 1,
  root: {
    array: [{a: 1}, {b: 2}, {c: 3}]
  }
})

Skenario 1: hanya mengubah elemen pertama array.

Dalam skenario ini, Cloud Firestore perilaku cocok dengan MongoDB.

db.my_collection.updateOne(
  {_id: 1},
  {'$set': {"root.array.0.a": 100}}
)

{
  updatedFields: {"root.array.0.a": 100},
  removedFields: []
}

Skenario 2: menimpa dengan seluruh array

Dalam skenario ini, operasi hanya memperbarui kolom array pertama, tetapi menimpa seluruh array.

Perbedaan pembaruan Cloud Firestore tidak membedakan kedua skenario ini dan menampilkan updateDescription.updatedFields yang sama untuk keduanya:

db.my_collection.updateOne(
  {_id: 1},
  {'$set': {"root.array": [{a: 100}, {b: 2}, {c: 3}]}}
)

// In other implementations, updatedFields reflects the mutation itself
{
  updatedFields: {
    "root.array": [{a: 100}, {b: 2}, {c: 3}]
  },
  removedFields: []
}

// Firestore updatedFields is the diff between the before and after versions of the document
{
  updatedFields: {"root.array.0.a": 100},
  removedFields: []
}