Properti

Properti (property) adalah pasangan kunci-nilai (key-value pair) yang menyimpan data pada node maupun relasi, dan topik ini membahas cara properti bekerja pada model property graph Neo4j. Lingkupnya mencakup penempatan properti pada node dan relasi, daftar tipe nilai yang didukung, cara menulis dan membaca properti, serta penggunaan properti sebagai penanda fakta pada peristiwa seperti tanggal peminjaman. Seluruh contoh dijalankan pada server Neo4j dengan data contoh perpustakaan yang berisi buku, anggota, dan relasi peminjaman, dan setiap kueri disertai keluaran aslinya. Setelah membaca topik ini, sebuah fakta dapat ditempatkan pada lokasi yang tepat dengan tipe nilai yang tepat.

Properti pada node dan relasi#

Node dan relasi sama-sama dapat membawa properti. Properti terdiri atas kunci dan nilai yang ditulis dengan pola kunci: nilai, misalnya isbn: "978-0-00-000001-3". Pada node :Buku, properti judul, isbn, dan tahunTerbit mendeskripsikan buku yang bersangkutan. Pada node :Anggota, properti nomorAnggota dan nama mendeskripsikan anggotanya.

Relasi juga dapat membawa properti. Relasi tanpa properti hanya menyatakan hubungan, sedangkan relasi dengan properti menyatakan hubungan beserta fakta yang menyertainya. Relasi :MEMINJAM yang menghubungkan :Anggota dan :Buku membawa properti tanggal yang menyatakan kapan peminjaman terjadi. Skrip penyiapan berikut membangun node dan relasi yang diperlukan dengan MERGE, yaitu pola get-or-create yang mencocokkan data sebelum membuatnya, sehingga skrip dapat dijalankan berulang tanpa menimbulkan duplikasi. Pernyataan penulisan tidak mencetak baris keluaran, sehingga skrip ditutup dengan kueri RETURN yang menampilkan setiap peminjaman beserta tanggalnya.

MERGE (b:Buku {isbn: "978-0-00-000001-3"})
  SET b.judul = "Catatan Pengelana", b.tahunTerbit = 2019;
MERGE (b:Buku {isbn: "978-0-00-000002-0"})
  SET b.judul = "Rumah Pena", b.tahunTerbit = 2021;
MERGE (b:Buku {isbn: "978-0-00-000003-8"})
  SET b.judul = "Anak Muara", b.tahunTerbit = 2020;
MERGE (b:Buku {isbn: "978-0-00-000004-5"})
  SET b.judul = "Peta Angin", b.tahunTerbit = 2022;
MERGE (b:Buku {isbn: "978-0-00-000005-2"})
  SET b.judul = "Jejak Basirah", b.tahunTerbit = 2023;
MERGE (a:Anggota {nomorAnggota: 1}) SET a.nama = "Sari";
MERGE (a:Anggota {nomorAnggota: 2}) SET a.nama = "Tono";
MERGE (a:Anggota {nomorAnggota: 3}) SET a.nama = "Rina";
MERGE (a:Anggota {nomorAnggota: 4}) SET a.nama = "Wawan";
MATCH (a:Anggota {nomorAnggota: 1}), (b:Buku {judul: "Catatan Pengelana"})
  MERGE (a)-[r:MEMINJAM]->(b) SET r.tanggal = date("2026-09-01");
MATCH (a:Anggota {nomorAnggota: 2}), (b:Buku {judul: "Rumah Pena"})
  MERGE (a)-[r:MEMINJAM]->(b) SET r.tanggal = date("2026-09-05");
MATCH (a:Anggota {nomorAnggota: 3}), (b:Buku {judul: "Anak Muara"})
  MERGE (a)-[r:MEMINJAM]->(b) SET r.tanggal = date("2026-09-12");
MATCH (a:Anggota {nomorAnggota: 1}), (b:Buku {judul: "Peta Angin"})
  MERGE (a)-[r:MEMINJAM]->(b) SET r.tanggal = date("2026-09-20");
MATCH (a:Anggota {nomorAnggota: 4}), (b:Buku {judul: "Jejak Basirah"})
  MERGE (a)-[r:MEMINJAM]->(b) SET r.tanggal = date("2026-09-25");
MATCH (a:Anggota)-[r:MEMINJAM]->(b:Buku)
  RETURN a.nama AS anggota, b.judul AS judul, r.tanggal AS tanggal ORDER BY tanggal

anggota, judul, tanggal
"Sari", "Catatan Pengelana", 2026-09-01
"Tono", "Rumah Pena", 2026-09-05
"Rina", "Anak Muara", 2026-09-12
"Sari", "Peta Angin", 2026-09-20
"Wawan", "Jejak Basirah", 2026-09-25

Nilai Sari, Tono, Rina, dan Wawan pada keluaran di atas adalah properti nama yang tersimpan pada node :Anggota, sedangkan judul buku tersimpan pada node :Buku. Nilai tanggal berbeda penempatannya karena nilai itu tersimpan pada relasi :MEMINJAM yang menghubungkan keduanya, bukan pada salah satu node. Satu baris keluaran dengan demikian menggabungkan properti dari dua node dan satu relasi sekaligus, sesuai wujud datanya.

Tipe nilai yang didukung#

Cypher menerima sekumpulan tipe nilai yang baku untuk properti, dan nilai di luar tipe tersebut ditolak saat penulisan. Tabel berikut merangkum tipe yang paling sering digunakan beserta contoh penulisannya pada kueri.

Daftar lengkapnya masih memuat tipe lain seperti LOCAL DATETIME, ZONED TIME, DURATION, dan UUID. Kueri berikut menampilkan satu baris nilai contoh untuk memperlihatkan cara setiap tipe ditulis dan ditampilkan oleh cypher-shell.

RETURN "Peta Angin" AS judul, 2022 AS tahunTerbit, 4.5 AS penilaian, true AS tersedia, date("2026-09-01") AS tanggalCatat, ["fiksi", "perjalanan"] AS genre ORDER BY judul

judul, tahunTerbit, penilaian, tersedia, tanggalCatat, genre
"Peta Angin", 2022, 4.5, TRUE, 2026-09-01, ["fiksi", "perjalanan"]

Kolom penilaian ditampilkan dengan tanda desimal sehingga terbaca sebagai FLOAT, sedangkan tahunTerbit tanpa tanda desimal terbaca sebagai INTEGER. Nilai kebenaran ditampilkan dengan huruf kapital oleh cypher-shell, dan nilai DATE ditampilkan sebagai 2026-09-01 tanpa tanda kutip. Kolom genre berupa LIST yang berisi dua STRING dengan tipe yang sama, dan list seperti ini disimpan sebagai satu properti utuh. Tipe DATE dan DATETIME membawa semantik kalender, sehingga nilai bertipe ini dapat dibandingkan dan diurutkan menurut urutan waktunya.

Nilai POINT mewakili koordinat kartesian maupun geografis, dan tipe ini dipilih apabila fakta yang disimpan berdimensi ruang. Tipe DATETIME menambahkan komponen jam dan zona waktu untuk peristiwa yang memerlukan ketepatan lebih halus daripada hari kalender. Peristiwa peminjaman buku cukup ditandai dengan hari kalender, sehingga data contoh menggunakan DATE untuk tanggal peminjaman.

Menulis dan membaca properti#

Properti dibaca dengan tanda titik pada variabel, misalnya b.judul untuk properti judul pada node yang terikat variabel b, dan pola ini sudah digunakan pada setiap kueri di atas. Properti ditulis dengan pernyataan SET, dan beberapa properti dapat ditetapkan sekaligus dengan pemisah tanda koma. SET mengganti nilai lama dengan nilai baru, sehingga menjalankan ulang pernyataan dengan nilai yang sama tidak mengubah isi graf. Pernyataan berikut menambahkan dua properti baru pada satu node :Buku, lalu membacanya kembali pada kueri yang sama.

MATCH (b:Buku {judul: "Peta Angin"})
SET b.halaman = 256, b.lokasiRak = "R-07"
RETURN b.judul AS judul, b.halaman AS halaman, b.lokasiRak AS lokasiRak

judul, halaman, lokasiRak
"Peta Angin", 256, "R-07"

Properti halaman dan lokasiRak kini melekat pada node Peta Angin, sedangkan node :Buku lainnya tidak membawanya. Apabila properti yang belum pernah ditetapkan ikut dibaca, Cypher mengembalikan null, yaitu nilai kosong yang menandakan ketiadaan data, tanpa memicu error. Kueri berikut membaca lokasiRak pada seluruh :Buku untuk memperlihatkan perilaku tersebut.

MATCH (b:Buku)
RETURN b.judul AS judul, b.lokasiRak AS lokasiRak
ORDER BY judul

judul, lokasiRak
"Anak Muara", NULL
"Catatan Pengelana", NULL
"Jejak Basirah", NULL
"Peta Angin", "R-07"
"Rumah Pena", NULL

Empat buku menampilkan NULL karena properti lokasiRak belum pernah ditetapkan pada node tersebut, sedangkan Peta Angin menampilkan nilai yang baru ditulis. Pembacaan terhadap properti yang tidak ada tidak memicu error karena null memang menandakan ketiadaan data. Perilaku null pada pembacaan aman, sedangkan perilaku yang sama pada saat menulis membawa akibat yang berbeda.

Properti sebagai penanda fakta#

Penempatan sebuah fakta mengikuti wujud peristiwanya. Tanggal peminjaman bukan sifat dari anggota dan bukan pula sifat dari buku, karena satu anggota dapat meminjam banyak buku dan satu buku dapat dipinjam berkali-kali dengan tanggal berbeda. Fakta itu melekat pada peristiwa peminjaman, dan peristiwa tersebut direpresentasikan oleh relasi :MEMINJAM. Karena itu tanggal tersimpan pada relasinya, dan setiap peminjaman memperoleh relasi tersendiri dengan tanggalnya sendiri.

Tipe DATE memudahkan perbandingan karena nilainya mengikuti urutan kalender. Kueri berikut menyaring peminjaman yang tanggalnya pada atau sesudah satu tanggal tertentu, dengan literal date(...) statis ditulis langsung pada kueri.

MATCH (a:Anggota)-[r:MEMINJAM]->(b:Buku)
WHERE r.tanggal >= date("2026-09-12")
RETURN a.nama AS anggota, b.judul AS judul, r.tanggal AS tanggal
ORDER BY tanggal

anggota, judul, tanggal
"Rina", "Anak Muara", 2026-09-12
"Sari", "Peta Angin", 2026-09-20
"Wawan", "Jejak Basirah", 2026-09-25

Kueri mengembalikan tiga peminjaman terbaru karena operator >= membandingkan nilai DATE menurut urutan kalender. Perbandingan ini bekerja karena kedua sisi bertipe DATE, sehingga hasilnya tidak bergantung pada format teks yang digunakan saat menulis tanggal. Saringan seperti ini menjawab pertanyaan yang lazim pada perpustakaan, misalnya daftar peminjaman sejak awal bulan. Nilai DATE juga mendukung perhitungan durasi antartanggal, dan rincian tipe temporal ini terdapat pada dokumentasi resmi yang dicantumkan pada bagian Referensi.

Kesalahan umum#

Empat kesalahan berikut paling sering muncul saat topik ini dipraktikkan, beserta penyebab dan perbaikannya.

1. Satu properti ditulis dengan tipe berbeda antarnode. tahunTerbit yang ditulis “2021” pada satu node dan 2021 pada node lain membuat saringan WHERE b.tahunTerbit > 2020 menyembunyikan baris bertipe STRING tanpa pesan apa pun, karena perbandingan antartipe yang berbeda menghasilkan null dan bukan true. Perbaikannya adalah menetapkan satu tipe untuk satu properti dan menjaganya sejak penulisan pertama.
2. List campuran disimpan sebagai properti. Penulisan nilai seperti ["fiksi", 2022] memicu error data exception - unsupported property value type, karena list yang disimpan sebagai properti harus bertipe homogen. Perbaikannya adalah menyamakan tipe seluruh elemen list atau memecahnya menjadi beberapa properti.
3. Fakta peristiwa ditempel pada node. Properti seperti tanggalPinjamTerakhir pada node :Anggota menimpa nilai lama setiap peminjaman baru, sehingga riwayat peminjaman sebelumnya hilang. Perbaikannya adalah menyimpan tanggal pada relasi :MEMINJAM, satu relasi untuk satu peristiwa.
4. Ketiadaan properti diperlakukan sebagai error. Pembacaan properti yang belum ditetapkan menghasilkan null, dan saringan WHERE yang membandingkan null tidak pernah bernilai true, sehingga barisnya terlewat tanpa tanda. Perbaikannya adalah menguji keberadaan properti dengan IS NOT NULL apabila baris tanpa properti itu ikut diperlukan.

Ringkasan#

• Properti adalah pasangan kunci-nilai yang melekat pada node maupun relasi, dan nilainya harus bertipe yang didukung Cypher seperti STRING, INTEGER, FLOAT, BOOLEAN, DATE, DATETIME, POINT, atau LIST.
• Properti dibaca dengan tanda titik dan ditulis dengan SET, sedangkan properti yang belum ditetapkan terbaca sebagai null dan SET dengan nilai null menghapus properti tersebut.
• Fakta yang melekat pada peristiwa disimpan pada relasi peristiwanya, seperti tanggal peminjaman pada :MEMINJAM, dengan satu relasi untuk setiap peristiwa.
• Tipe DATE menyimpan tanggal menurut kalender sehingga perbandingan seperti >= terhadap literal statis date("2026-09-12") bekerja konsisten.

Referensi#

• Property, structural, and constructed values — Neo4j — Daftar tipe properti Cypher beserta aturan penyimpanan list yang homogen.
• Temporal values — Neo4j — Tipe temporal dari DATE sampai ZONED DATETIME beserta cara membuat nilai date dengan literal.
• SET — Neo4j — Sintaks SET untuk menetapkan beberapa properti sekaligus dan perilaku SET dengan nilai null.