Pengantar stream

Stream adalah tipe data Redis yang menyimpan log append-only, yaitu catatan yang hanya menerima penambahan di akhir dan tidak diubah lagi setelah tertulis. Setiap entri membawa ID yang naik secara monoton beserta beberapa pasangan field-nilai, sehingga satu entri memuat peristiwa lebih kaya daripada satu nilai string. Topik ini membahas penambahan entri dengan XADD menggunakan ID eksplisit dan ID otomatis, penghitungan jumlah entri dengan XLEN, pembacaan rentang dengan XRANGE dan XREVRANGE, serta pembacaan entri baru dengan XREAD dari posisi tertentu. Bagian akhir membandingkan stream dengan list sebagai penyimpan log peristiwa. Dengan mengikuti contoh pada topik ini, log peristiwa sederhana dapat dibangun pada Redis dan dibaca kembali dari posisi mana pun.

Stream sebagai log append-only#

Stream menyimpan entri secara berurutan, dan penambahan entri selalu terjadi di akhir log. Entri adalah satuan catatan yang terdiri atas ID dan beberapa pasangan field-nilai, misalnya field kegiatan dengan nilai login dan field pengguna dengan nilai budi. Urutan entri mengikuti urutan ID-nya, sehingga pembacaan selalu mengembalikan entri dalam urutan yang sama dengan urutan penambahannya.

ID stream terdiri atas dua bagian yang dipisahkan tanda hubung, yaitu bilangan milidetik dan nomor sekuens, contohnya 1730123456789-0. Bagian milidetik lazim diambil dari waktu server, sedangkan nomor sekuens menyelesaikan benturan ketika beberapa entri ditambahkan pada milidetik yang sama. Aturan yang berlaku hanya satu, yaitu ID entri baru wajib lebih besar daripada ID entri terakhir. ID yang sudah terpakai tidak dapat digunakan kembali, sehingga urutan entri tidak pernah berubah.

Diagram berikut merangkum alur penambahannya. Perintah XADD menulis entri baru di akhir stream log:aktivitas, dan setiap entri membawa ID beserta pasangan field-nilainya. Arus penambahan tidak pernah menyentuh entri sebelumnya, sehingga entri lama tetap dapat dibaca dengan ID yang sama.

Menambah entri dengan XADD#

XADD menambahkan satu entri di akhir stream dan mengembalikan ID yang digunakan untuk entri tersebut. Bentuk perintahnya adalah XADD diikuti nama key, ID, lalu pasangan field-nilai yang ditulis satu per satu. Contoh berikut menggunakan ID eksplisit yang ditulis langsung pada perintahnya. Nomor kecil seperti 1-1 dan 2-1 dipilih agar keluaran contoh sama setiap kali dijalankan ulang. Syaratnya tetap sama, yaitu ID baru harus lebih besar daripada ID entri terakhir.

# menghapus stream lama agar contoh selalu dimulai dari keadaan yang sama, keluarannya diabaikan
redis-cli del log:aktivitas >/dev/null
# entri pertama ditambahkan dengan ID 1-1
redis-cli xadd log:aktivitas 1-1 kegiatan login pengguna budi
# entri kedua membawa field tambahan berkas
redis-cli xadd log:aktivitas 1-2 kegiatan unggah pengguna budi berkas laporan.odt
# entri ketiga dengan ID yang lebih besar daripada sebelumnya
redis-cli xadd log:aktivitas 2-1 kegiatan keluar pengguna budi
# menghitung jumlah entri pada stream
redis-cli xlen log:aktivitas

1-1
1-2
2-1
3

Nilai kembalian XADD persis sama dengan ID yang diminta, sehingga ID pada keluaran dapat digunakan sebagai posisi baca. XLEN menghitung jumlah entri tanpa membaca isinya. Ketiga entri membawa field kegiatan dan pengguna, sedangkan entri unggah menambahkan field berkas, dan stream menerima semuanya tanpa skema yang dinyatakan lebih dahulu.

Membaca rentang dengan XRANGE dan XREVRANGE#

XRANGE membaca entri menurut rentang ID, dan kedua batas rentangnya bersifat inklusif. Tanda - mewakili ID terkecil pada stream, tanda + mewakili ID terbesar, sehingga rentang - + mengembalikan seluruh isi log. Pembacaan dapat dimulai dari ID mana pun, sehingga memeriksa sebagian log tidak menuntut pembacaan dari awal.

# mengisi ulang stream contoh, keluaran penyiapannya diabaikan
redis-cli del log:aktivitas >/dev/null
redis-cli xadd log:aktivitas 1-1 kegiatan login pengguna budi >/dev/null
redis-cli xadd log:aktivitas 1-2 kegiatan unggah pengguna budi berkas laporan.odt >/dev/null
redis-cli xadd log:aktivitas 2-1 kegiatan keluar pengguna budi >/dev/null
# membaca seluruh entri dari ID terkecil sampai terbesar
redis-cli xrange log:aktivitas - +

1-1
kegiatan
login
pengguna
budi
1-2
kegiatan
unggah
pengguna
budi
berkas
laporan.odt
2-1
kegiatan
keluar
pengguna
budi

Setiap entri pada keluaran terdiri atas ID dan pasangan field-nilainya yang ditulis berurutan. Keluaran tampil menurut urutan ID, sehingga urutannya sama dengan urutan penambahan. XREVRANGE bekerja dengan urutan terbalik, yaitu dari ID terbesar ke terkecil, sehingga entri terbaru dapat dibaca terlebih dahulu. Argumen COUNT membatasi jumlah entri yang dikembalikan, seperti pada contoh berikut.

# mengisi ulang stream contoh, keluaran penyiapannya diabaikan
redis-cli del log:aktivitas >/dev/null
redis-cli xadd log:aktivitas 1-1 kegiatan login pengguna budi >/dev/null
redis-cli xadd log:aktivitas 1-2 kegiatan unggah pengguna budi berkas laporan.odt >/dev/null
redis-cli xadd log:aktivitas 2-1 kegiatan keluar pengguna budi >/dev/null
# entri mulai dari ID 1-2, batas bawah ikut dibaca
redis-cli xrange log:aktivitas 1-2 +
# satu entri terbaru dalam urutan terbalik
redis-cli xrevrange log:aktivitas + - count 1

1-2
kegiatan
unggah
pengguna
budi
berkas
laporan.odt
2-1
kegiatan
keluar
pengguna
budi
2-1
kegiatan
keluar
pengguna
budi

Rentang 1-2 hingga akhir stream mengembalikan dua entri karena ID 1-2 ikut dibaca. XREVRANGE dengan COUNT 1 hanya mengembalikan entri ber-ID 2-1, yaitu entri yang terakhir ditambahkan. Pembacaan rentang tidak mengubah isi stream, sehingga log dapat dibaca berulang kali tanpa kehilangan entrinya.

Membaca entri baru dengan XREAD#

XREAD membaca entri yang lebih baru daripada ID yang diberikan. Argumen STREAMS diikuti nama key dan posisi baca berupa ID terakhir yang sudah dilihat. Hasilnya dikelompokkan menurut nama key, sehingga satu pemanggilan dapat membaca beberapa stream sekaligus. Entri yang ID-nya persis sama dengan posisi baca tidak dikembalikan karena XREAD hanya mengambil entri yang lebih baru.

# mengisi ulang stream contoh, keluaran penyiapannya diabaikan
redis-cli del log:aktivitas >/dev/null
redis-cli xadd log:aktivitas 1-1 kegiatan login pengguna budi >/dev/null
redis-cli xadd log:aktivitas 1-2 kegiatan unggah pengguna budi berkas laporan.odt >/dev/null
redis-cli xadd log:aktivitas 2-1 kegiatan keluar pengguna budi >/dev/null
# entri yang lebih baru daripada ID 1-1
redis-cli xread streams log:aktivitas 1-1
# entri yang lebih baru daripada ID 1-2
redis-cli xread streams log:aktivitas 1-2

log:aktivitas
1-2
kegiatan
unggah
pengguna
budi
berkas
laporan.odt
2-1
kegiatan
keluar
pengguna
budi
log:aktivitas
2-1
kegiatan
keluar
pengguna
budi

Pemanggilan pertama mengembalikan entri 1-2 dan 2-1, sedangkan pemanggilan kedua hanya mengembalikan entri 2-1. Apabila tidak ada entri yang lebih baru daripada posisi baca, XREAD mengembalikan nil dan keluarannya kosong. Posisi baca berupa ID entri juga dapat disimpan di luar Redis dan digunakan kembali oleh proses lain yang membaca log yang sama. Pola ini menggantikan kebiasaan membaca ulang seluruh isi log pada setiap pemeriksaan.

ID otomatis dengan tanda bintang#

Tanda bintang pada posisi ID meminta Redis menentukan ID secara otomatis. Redis menyusun ID dari waktu server dalam milidetik, lalu menambahkan nomor sekuens apabila dua penambahan terjadi pada milidetik yang sama. ID yang dihasilkan tetap mengikuti aturan yang sama, yaitu lebih besar daripada ID entri terakhir. Bentuk ini paling lazim dipilih untuk log peristiwa karena aplikasi tidak perlu mengurus penomoran sama sekali.

# tidak-dijalankan
# ID otomatis ditentukan Redis berdasarkan waktu server sehingga keluarannya berubah setiap saat
redis-cli xadd log:aktivitas * kegiatan login pengguna dewi

Blok di atas sengaja tidak dieksekusi pada topik ini. ID yang dihasilkan mengandung waktu nyata, sehingga nilainya pasti berbeda pada setiap pemanggilan dan tidak dapat dicocokkan dengan keluaran yang stabil. Perilaku penolakan ID juga tetap berlaku, sehingga penambahan dengan ID eksplisit yang lebih kecil daripada ID otomatis yang sudah terpakai akan ditolak.

Stream versus list untuk log peristiwa#

Untuk log peristiwa, perbedaan list dan stream mencakup tiga aspek yang menentukan pilihan struktur data. Ketiganya berkaitan dengan isi per elemen, cara menandai posisi baca, dan keutuhan catatan yang sudah tertulis. Perbandingan berikut merangkum aspek-aspek tersebut.

Perbedaan yang paling menentukan berada pada posisi baca. List diakses menurut indeks, dan indeks bergeser setiap kali elemen ditambahkan atau dibuang, sehingga posisi yang dicatat kemarin tidak dapat dipastikan menunjuk elemen yang sama hari ini. Stream menyimpan posisi sebagai ID, dan ID entri tidak pernah berubah, sehingga beberapa pembaca dapat menyimpan posisi baca masing-masing tanpa saling mengganggu.

Perbedaan lain menyentuh keutuhan catatan. Nilai elemen list dapat ditimpa, sedangkan stream tidak menyediakan penimpaan isi entri, dan ID yang sama tidak dapat digunakan dua kali. Penghapusan entri pada stream memang tersedia melalui XDEL dan XTRIM, tetapi keduanya membuang entri dan tidak mengubah entri yang tersisa. Sifat-sifat ini menjadikan stream pilihan yang lebih tepat untuk log peristiwa yang urutannya harus tetap dapat dipercaya.

Ringkasan#

• Stream menyimpan log append-only berupa entri ber-ID beserta beberapa pasangan field-nilai, dan penambahan selalu terjadi di akhir log.
• XADD menambahkan entri dengan ID eksplisit yang wajib lebih besar daripada ID terakhir atau dengan ID otomatis dari tanda bintang, sedangkan XLEN menghitung jumlah entri.
• XRANGE dan XREVRANGE membaca rentang ID dengan batas inklusif dan COUNT sebagai pembatas, sedangkan XREAD mengembalikan entri yang lebih baru daripada posisi baca.
• Untuk log peristiwa, stream menawarkan ID yang tetap, tidak dapat ditimpa, serta posisi baca yang stabil, sedangkan list menyimpan satu string per elemen dengan indeks yang bergeser.

Referensi#

• Streams — Redis — Dokumentasi tipe data stream beserta semantik ID dan pola pembacaannya.
• XADD — Redis — Dokumentasi perintah XADD beserta aturan ID eksplisit dan otomatisnya.
• XRANGE — Redis — Dokumentasi perintah XRANGE beserta semantik rentang ID-nya.
• XREAD — Redis — Dokumentasi perintah XREAD untuk membaca entri yang lebih baru dari posisi tertentu.