Pustaka GDS

Neo4j Graph Data Science (GDS) adalah pustaka prosedur algoritma graf yang ditambahkan ke server Neo4j dalam bentuk plugin. Topik ini membahas apa yang ditambahkan pustaka tersebut, konsep proyeksi graf (graph projection) dalam memori, dan siklus kerja tiga langkah untuk menjalankan algoritma, yaitu memproyeksikan graf, menjalankan algoritma atas proyeksi tersebut, lalu menyingkirkan proyeksinya. Seluruh contoh dijalankan pada server Neo4j 2026.10 dengan plugin GDS 2026.10.0 dan dataset jaringan transportasi milik modul ini. Setelah topik ini dibaca, sebuah proyeksi dapat dibuat, digunakan oleh satu algoritma, dan disingkirkan kembali.

Pustaka GDS dan pemasangannya#

GDS menambahkan ratusan prosedur Cypher yang seluruhnya berawalan gds.. Prosedur gds.graph.* mengelola katalog proyeksi, sedangkan prosedur algoritma seperti gds.degree.* dan gds.dijkstra.* menjalankan komputasi atas sebuah proyeksi. Algoritma tidak berjalan langsung pada basis data, melainkan pada salinan graf yang dimuat ke memori, sehingga beban analitik terpisah dari kueri biasa.

Pustaka ini didistribusikan sebagai plugin berupa satu berkas jar (jar), yakni arsip Java yang memuat seluruh kode pustakanya. Pada instalasi server Community, pemasangan dilakukan dengan menyalin berkas jar tersebut ke folder plugins, menambahkan entri izin prosedur pada neo4j.conf, kemudian memulai ulang server. Server hanya memuat plugin pada saat mulai berjalan, sehingga penyalinan berkas tanpa memulai ulang tidak berdampak apa pun.

# tidak-dijalankan
# menyalin berkas jar GDS dari folder products ke folder plugins (jalur relatif terhadap folder instalasi)
cp products/neo4j-graph-data-science-2026.10.0.jar plugins/
# menambahkan izin prosedur GDS pada konfigurasi server
echo 'dbms.security.procedures.unrestricted=gds.*' >> conf/neo4j.conf
# memulai ulang server agar plugin dimuat
bin/neo4j restart

Setelah server berjalan kembali, pemasangan diverifikasi dengan fungsi gds.version() yang mengembalikan versi pustaka yang aktif. Nilai yang dikembalikan sebaiknya cocok dengan versi server Neo4j, sebab plugin yang dibundel bersama satu distribusi server selalu kompatibel dengan distribusi tersebut.

RETURN gds.version();

gds.version()
"2026.10.0"

Dataset contoh#

Seluruh contoh pada modul ini menggunakan jaringan transportasi kecil yang sama, yaitu delapan pemberhentian bernama Mangga, Melati, Cemara, Kenanga, Cempaka, Anggrek, Flamboyan, dan Bougenvil. Pemberhentian tersimpan sebagai node :Pemberhentian dengan properti name, sedangkan relasi :KE menghubungkan dua pemberhentian yang dilayani satu rute. Relasi tersebut membawa properti jarak berupa bilangan bulat dalam kilometer dan berarah, sehingga jaringannya menggambarkan arah perjalanan dari satu pemberhentian menuju pemberhentian berikutnya. Jaringannya berbentuk satu lingkar rute dengan empat jalur pintas antar pemberhentian, memuat dua belas relasi dengan jarak antara dua sampai sembilan kilometer.

Dataset dimuat dari berkas setup.cypher berikut yang idempoten (idempotent), artinya aman dijalankan berulang kali. Isinya identik dengan berkas setup.cypher pada topik lain dalam modul ini. Sintaksnya dibahas pada modul Fundamental Cypher, sehingga berkas ini cukup dijalankan apa adanya. Menjalankan skrip ini kembali memastikan node dan relasi dasar modul tersedia dalam bentuk yang tetap. Delapan node dengan dua belas relasi memberikan keluaran yang pendek, tetapi masih cukup beragam untuk memperlihatkan perilaku prosedur GDS.

// Dataset contoh modul Algoritma graf dengan GDS: jaringan transportasi mini
// dengan delapan pemberhentian dan relasi KE berbobot jarak.
// Skrip ini idempoten (idempotent), artinya aman dijalankan berulang kali.

// Node pemberhentian: label :Pemberhentian dengan properti name.
MERGE (:Pemberhentian {name: "Mangga"});
MERGE (:Pemberhentian {name: "Melati"});
MERGE (:Pemberhentian {name: "Cemara"});
MERGE (:Pemberhentian {name: "Kenanga"});
MERGE (:Pemberhentian {name: "Cempaka"});
MERGE (:Pemberhentian {name: "Anggrek"});
MERGE (:Pemberhentian {name: "Flamboyan"});
MERGE (:Pemberhentian {name: "Bougenvil"});

// Relasi KE berarah antar pemberhentian, dengan properti jarak dalam kilometer.
MATCH (a:Pemberhentian {name: "Mangga"}), (b:Pemberhentian {name: "Melati"})
  MERGE (a)-[r:KE]->(b)
  SET r.jarak = 3;
MATCH (a:Pemberhentian {name: "Melati"}), (b:Pemberhentian {name: "Cemara"})
  MERGE (a)-[r:KE]->(b)
  SET r.jarak = 2;
MATCH (a:Pemberhentian {name: "Cemara"}), (b:Pemberhentian {name: "Kenanga"})
  MERGE (a)-[r:KE]->(b)
  SET r.jarak = 4;
MATCH (a:Pemberhentian {name: "Kenanga"}), (b:Pemberhentian {name: "Cempaka"})
  MERGE (a)-[r:KE]->(b)
  SET r.jarak = 2;
MATCH (a:Pemberhentian {name: "Cempaka"}), (b:Pemberhentian {name: "Anggrek"})
  MERGE (a)-[r:KE]->(b)
  SET r.jarak = 5;
MATCH (a:Pemberhentian {name: "Anggrek"}), (b:Pemberhentian {name: "Flamboyan"})
  MERGE (a)-[r:KE]->(b)
  SET r.jarak = 3;
MATCH (a:Pemberhentian {name: "Flamboyan"}), (b:Pemberhentian {name: "Bougenvil"})
  MERGE (a)-[r:KE]->(b)
  SET r.jarak = 2;
MATCH (a:Pemberhentian {name: "Bougenvil"}), (b:Pemberhentian {name: "Mangga"})
  MERGE (a)-[r:KE]->(b)
  SET r.jarak = 4;
MATCH (a:Pemberhentian {name: "Melati"}), (b:Pemberhentian {name: "Anggrek"})
  MERGE (a)-[r:KE]->(b)
  SET r.jarak = 6;
MATCH (a:Pemberhentian {name: "Cemara"}), (b:Pemberhentian {name: "Anggrek"})
  MERGE (a)-[r:KE]->(b)
  SET r.jarak = 9;
MATCH (a:Pemberhentian {name: "Kenanga"}), (b:Pemberhentian {name: "Bougenvil"})
  MERGE (a)-[r:KE]->(b)
  SET r.jarak = 7;
MATCH (a:Pemberhentian {name: "Cempaka"}), (b:Pemberhentian {name: "Melati"})
  MERGE (a)-[r:KE]->(b)
  SET r.jarak = 8;

# tidak-dijalankan
# memuat dataset contoh dari berkas setup.cypher ke dalam basis data
cat setup.cypher | cypher-shell -u neo4j

Proyeksi graf dalam memori#

GDS tidak menjalankan algoritma pada basis data secara langsung. Setiap komputasi ditujukan kepada proyeksi graf, yaitu salinan graf yang dimuat ke memori server dalam format ringkas untuk analitik. Proyeksi dibuat melalui prosedur gds.graph.project dan tersimpan dalam katalog atas nama yang diberikan, sehingga algoritma berikutnya cukup memanggil nama tersebut. Definisi proyeksi menentukan label node yang diambil, tipe relasi yang diambil, orientasi relasi, yaitu asli, dibalik, atau tak berarah, serta properti mana yang dibawa sebagai bobot. Properti jarak dibawa ke dalam proyeksi agar algoritma berbobot seperti Dijkstra dapat menggunakannya.

Prosedur gds.graph.project menggunakan bentuk proyeksi yang disebut native projection, yaitu proyeksi yang menyebut label dan tipe relasi secara langsung. Kueri berikut memproyeksikan label Pemberhentian dan tipe relasi KE ke dalam proyeksi bernama jalur-m7. Konfigurasi relationshipProperties menyatakan properti relasi yang dimuat bersama relasinya, sedangkan nilai yang dikembalikan memperlihatkan jumlah node dan jumlah relasi yang tertampung.

CALL gds.graph.project(
  'jalur-m7',
  'Pemberhentian',
  'KE',
  {relationshipProperties: 'jarak'}
)
YIELD graphName, nodeCount, relationshipCount
RETURN graphName, nodeCount, relationshipCount;

graphName, nodeCount, relationshipCount
"jalur-m7", 8, 12

Isi katalog dapat diperiksa kapan saja dengan gds.graph.list. Prosedur ini menerima nama proyeksi sebagai argumen opsional. Apabila nama diberikan, daftar hanya memuat proyeksi tersebut, sedangkan tanpa argumen seluruh proyeksi ditampilkan. Keluaran di bawah ini menegaskan bahwa proyeksi jalur-m7 benar-benar terbentuk.

CALL gds.graph.list('jalur-m7')
YIELD graphName, nodeCount, relationshipCount
RETURN graphName, nodeCount, relationshipCount;

graphName, nodeCount, relationshipCount
"jalur-m7", 8, 12

Mode stream, write, dan stats#

Setiap algoritma GDS tersedia dalam beberapa mode eksekusi yang ditandai akhiran nama prosedurnya, yaitu stream, stats, dan write. Mode menentukan ke mana hasil komputasi dikirim, sedangkan konfigurasi algoritmanya sama pada setiap mode. Tabel berikut membandingkan ketiganya.

Mode stream digunakan apabila hasil hanya ditampilkan atau diolah lebih lanjut oleh kueri yang sama. Mode stats berguna untuk menilai hasil komputasi tanpa menulis apa pun dan tanpa mengirim baris per node. Mode write digunakan apabila skor perlu digunakan kembali oleh kueri lain, dan nama properti hasilnya ditentukan melalui konfigurasi writeProperty. Pola penamaan tiga akhiran tersebut berlaku seragam di seluruh pustaka, sehingga mode dapat ditukar tanpa mengubah konfigurasi lainnya dan perhitungan yang dikerjakan tetap sama.

Siklus kerja tiga langkah#

Penggunaan GDS mengikuti siklus kerja yang tetap, yaitu memproyeksikan graf, menjalankan algoritma atas proyeksi tersebut, lalu menyingkirkan proyeksinya. Algoritma sentralitas derajat digunakan sebagai contoh penerapannya, sedangkan rumus dan penafsiran skornya tidak dibahas di sini karena menjadi isi topik sentralitas. Langkah-langkahnya adalah sebagai berikut.

1. Proyeksikan graf dengan gds.graph.project, dengan label Pemberhentian dan tipe relasi KE pada dataset contoh.
2. Jalankan algoritma mode stream atas proyeksi jalur-m7.
3. Singkirkan proyeksi dengan gds.graph.drop setelah hasilnya selesai digunakan.

Kueri berikut menjalankan langkah kedua. Prosedur gds.util.asNode menerjemahkan id node pada hasil stream menjadi node aslinya, sehingga nama pemberhentian dapat ditampilkan. Hasil diurutkan menurun menurut skor lalu menaik menurut nama, sehingga urutannya pasti.

CALL gds.degree.stream('jalur-m7')
YIELD nodeId, score
RETURN gds.util.asNode(nodeId).name AS nama, score AS skor
ORDER BY skor DESC, nama ASC;

nama, skor
"Cemara", 2.0
"Cempaka", 2.0
"Kenanga", 2.0
"Melati", 2.0
"Anggrek", 1.0
"Bougenvil", 1.0
"Flamboyan", 1.0
"Mangga", 1.0

Empat pemberhentian memperoleh skor dua karena masing-masing menjadi asal dua relasi KE, sedangkan empat pemberhentian lainnya memperoleh skor satu. Proyeksi selanjutnya disingkirkan agar memorinya dilepaskan kembali, dan daftar proyeksi menegaskan katalog kembali kosong. Pada proyeksi berukuran besar, kebiasaan menyingkirkan proyeksi ini menentukan berapa lama memori analitik tetap terpakai.

CALL gds.graph.drop('jalur-m7')
YIELD graphName, nodeCount, relationshipCount
RETURN graphName, nodeCount, relationshipCount;

graphName, nodeCount, relationshipCount
"jalur-m7", 8, 12

CALL gds.graph.list()
YIELD graphName
RETURN count(graphName) AS jumlahProyeksi;

jumlahProyeksi
0

Kesalahan umum#

Empat kesalahan berikut paling sering muncul saat topik ini dipraktikkan.

1. Prosedur gds.* dipanggil sebelum plugin dimuat. Server menolak prosedurnya dengan pesan error bahwa prosedur tidak terdaftar. Perbaikannya adalah memastikan berkas jar berada di folder plugins, menambahkan entri izin prosedur, lalu memulai ulang server dan mengulangi gds.version().
2. Label atau tipe relasi salah eja pada gds.graph.project. Proyeksi atas label yang tidak memiliki node apa pun ditolak, dan pesan errornya menyebut label yang tidak ditemukan, misalnya Invalid node projection, one or more labels not found: 'PemberhentianXX'. Perbaikannya adalah menyamakan ejaan label dan tipe relasi dengan isi basis data, sebagaimana diperiksa lewat MATCH.
3. Algoritma dijalankan atas nama proyeksi yang sudah disingkirkan. Pesan errornya menyatakan bahwa proyeksi dengan nama tersebut tidak ada pada basis data. Perbaikannya adalah memproyeksikan ulang graf atau memeriksa katalog dengan gds.graph.list() terlebih dahulu.
4. Proyeksi dibiarkan terpasang setelah analitik selesai. Memori server tetap dipegang proyeksi tersebut meskipun tidak pernah digunakan lagi. Perbaikannya adalah menjadikan gds.graph.drop sebagai penutup tetap setiap sesi analitik, atau memantau katalog dengan gds.graph.list().

Ringkasan#

• GDS adalah plugin berkas jar yang menambahkan prosedur gds.* ke server Neo4j, dipasang pada folder plugins, dan aktif setelah server dimulai ulang.
• Algoritma GDS berjalan atas proyeksi graf dalam memori, yaitu salinan bernama yang menentukan label node, tipe relasi, orientasi, dan bobot yang diambil.
• Hasil algoritma dikirim sesuai mode eksekusinya, yaitu stream sebagai baris ke klien, stats sebagai ringkasan agregat, atau write sebagai properti node pada basis data.
• Siklus kerja GDS terdiri atas gds.graph.project untuk memproyeksikan, pemanggilan algoritma atas nama proyeksi, dan gds.graph.drop untuk menyingkirkan proyeksinya.

Referensi#

• Installation — Neo4j Docs — Langkah pemasangan plugin GDS pada server, penyalinan jar ke folder plugins, dan verifikasi dengan gds.version().
• Native projection — Neo4j Docs — Sintaks gds.graph.project beserta konfigurasi relationshipProperties untuk membawa bobot relasi.
• Degree Centrality — Neo4j Docs — Mode eksekusi stream, stats, dan write beserta definisi skor derajat pada proyeksi berarah.