Menjalankan algoritma Spanner Graph

Pratinjau — Algoritma Spanner Graph

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Catatan: Fitur ini tersedia di edisi Spanner Enterprise dan Enterprise Plus. Untuk mengetahui informasi selengkapnya, lihat Ringkasan edisi Spanner.

Dokumen ini menjelaskan cara menjalankan algoritma di Spanner Graph.

Struktur kueri algoritma Spanner Graph

Kueri algoritma Spanner Graph memiliki struktur berikut:

EXPORT DATA OPTIONS (export_option_list) AS
GRAPH graph_name
match_clause
call_statement algorithm_name(common_input, algorithm_specific_input)
  YIELD algorithm_specific_output
RETURN results

• export_option_list: Opsi yang menentukan cara mempertahankan hasil kueri algoritma. Lihat Opsi Cloud Storage dan Opsi Spanner.

• graph_name: Nama grafik.

• match_clause: Opsional MATCH pernyataan untuk menentukan elemen input algoritma.

• call_statement: Gunakan pernyataan CALL saat Anda menghilangkan variabel match_clause dan ingin mengoperasikan seluruh grafik. Gunakan pernyataan CALL PER() saat variabel match_clause ada dan Anda ingin beroperasi pada tabel kerja. Untuk mengetahui informasi selengkapnya, lihat GQL CALL.

• algorithm_name: Nama algoritma yang akan dijalankan. Untuk algoritma yang tersedia, lihat Algoritma Spanner Graph.

• common_input: Parameter input bernama yang umum untuk semua kueri algoritma. Untuk mengetahui informasi selengkapnya, lihat parameter input algoritma umum.

• algorithm_specific_input: Parameter input bernama untuk algoritma. Untuk mengetahui informasi selengkapnya, lihat parameter input yang ditentukan dalam Algoritma Spanner Graph.

• algorithm_specific_output: Output panggilan algoritma. Untuk mengetahui informasi selengkapnya, lihat output yang ditentukan dalam algoritma Spanner Graph dan klausa YIELD dalam pernyataan CALL.

• results: Menentukan apa yang akan ditampilkan dalam hasil kueri.

Kueri terdiri dari pernyataan EXPORT DATA, yang menentukan cara mempertahankan hasil, dan GRAPH CLAUSE yang menghasilkan hasil kueri algoritma.

Dalam bentuknya yang paling sederhana, klausa grafik mengidentifikasi grafik, menggunakan pernyataan CALL untuk memanggil algoritma yang menghasilkan output yang telah ditentukan sebelumnya, lalu menggunakan pernyataan RETURN untuk menentukan apa yang akan ditampilkan dari output algoritma.

Secara opsional, klausa grafik dapat menggunakan pernyataan MATCH yang didukung untuk memilih elemen yang diinginkan. Dalam hal ini, gunakan klausa PER () untuk mengelompokkan semua baris yang ditampilkan oleh pernyataan MATCH sebagai input ke algoritma. Algoritma ini beroperasi pada subgrafik logis yang terdiri dari kumpulan unik node dan tepi yang dipilih.

Kueri tidak menampilkan data apa pun. Variabel export_option_list menentukan cara hasil dipertahankan.

Untuk mengetahui informasi selengkapnya tentang kueri algoritma Spanner Graph, lihat bagian berikut dalam dokumen ini:

• Parameter input algoritma umum
• Menangani output algoritma
• Menjalankan contoh kueri algoritma

Parameter input algoritma umum

Tentukan parameter input bernama ini dalam format berikut: NAME => VALUE, ....

Nama	Jenis Nilai	Wajib	Nilai Default	Deskripsi
node_labels	ARRAY	Tidak	(tidak ada)	Hanya didukung saat CALL digunakan. Daftar label node yang akan disertakan dalam input algoritma. Jika ditentukan, hanya node dengan setidaknya satu label yang cocok yang akan disertakan.
edge_labels	ARRAY	Tidak	(tidak ada)	Hanya didukung saat CALL digunakan. Daftar label tepi yang akan disertakan dalam input algoritma. Jika ditentukan, hanya tepi dengan setidaknya satu label yang cocok yang disertakan.
edge_weight_property	STRING	Tidak	(tidak ada)	Nama properti tepi yang berisi bobot. Jika tidak ditentukan, sistem akan menetapkan bobot default 1 ke semua edge. Jenis nilai properti harus berupa angka.
machine_category	STRING	Tidak	default	Kategori mesin yang akan digunakan untuk eksekusi algoritma. Nilai yang didukung adalah: default, large
fallback_compute_region	STRING	Tidak	(tidak ada)	Region penggantian tempat eksekusi algoritma dilakukan jika region asal mengalami batasan kapasitas. Harus berada di yurisdiksi yang sama dengan region asal instance Spanner (misalnya, us-central1 jika region asalnya adalah us-east1).
max_idle_time	STRING	Tidak	Waktu lab	Menentukan durasi instance komputasi harus tetap aktif untuk digunakan kembali setelah algoritma selesai. Format adalah urutan angka desimal, masing-masing dengan akhiran satuan, seperti 4m, 1.5h atau 1h45m. Satuan waktu yang valid adalah ns, us (atau µs), ms, s, m, h.

Menangani output algoritma

Anda harus mempertahankan hasil kueri algoritma sebelum dapat memeriksanya. Gunakan export_data_option untuk menjelaskan cara mempertahankan hasil. Anda dapat mempertahankan hasil ke Cloud Storage atau kembali ke instance Spanner yang sama tempat kueri berasal.

Mempertahankan hasil ke Cloud Storage

Untuk menggunakan opsi ini, pastikan peran Storage Object Admin (roles/storage.objectAdmin) diberikan ke akun layanan Spanner [e-mail] yang dikelola Google.

Opsi EXPORT DATA berikut didukung saat mempertahankan hasil ke Cloud Storage. Tentukan opsi dalam format berikut: NAME=VALUE, ....

Nama	Jenis Nilai	Wajib	Deskripsi
uri	STRING	Ya	URI tujuan untuk ekspor, dalam format gs://bucket/path/file. Jika Anda mengekspor data dalam jumlah besar, gunakan karakter pengganti di uri untuk mengekspor data ke beberapa file. Misalnya, gs://bucket/path/file_*.csv.
format	STRING	Ya	Format data yang diekspor. Nilai yang didukung: CSV, PARQUET, AVRO.
header	BOOL	Tidak	Jika true, sistem akan mencetak header kolom untuk baris pertama setiap file data. Defaultnya adalah false. Hanya berlaku untuk CSV.
overwrite	BOOL	Tidak	Jika true, sistem akan menimpa file yang ada dengan URI yang sama. Jika tidak, jika file dengan URI yang sama ada, pernyataan akan menampilkan error. Defaultnya adalah false.
field_delimiter	STRING	Tidak	Pembatas yang memisahkan kolom. Default: , (koma). Hanya berlaku untuk CSV.
compression	STRING	Tidak	Menentukan format kompresi. Jika Anda tidak menentukan format kompresi, file akan tetap tidak dikompresi. Untuk CSV, nilai yang didukung adalah GZIP. Untuk PARQUET, nilai yang didukung adalah: SNAPPY, GZIP, ZSTD. Untuk AVRO, nilai yang didukung adalah: DEFLATE, SNAPPY.

Nama kolom dalam klausa RETURN menentukan nama kolom dalam file output Cloud Storage.

Mengekspor data ke satu atau beberapa file

Kueri Spanner Graph mendukung satu operator karakter pengganti (*) di uri. Karakter pengganti dapat muncul di komponen nama file, tetapi tidak di nama bucket, nama folder, atau ekstensi file. Penggunaan operator karakter pengganti menginstruksikan Spanner Graph untuk membuat beberapa file shard berdasarkan pola yang Anda berikan jika set hasil berukuran besar. Sistem mengganti operator karakter pengganti dengan angka, dimulai dari nol, dengan padding kiri hingga 12 digit. Misalnya, URI gs://my-bucket/file-*.csv membuat file seperti gs://my-bucket/file-000000000000.csv, gs://my-bucket/file-000000000001.csv, dan file serupa.

Jika Anda menggunakan uri tanpa karakter pengganti, hasilnya adalah satu file, seperti gs://my-bucket/file.csv.

Jenis data

Saat Anda mengekspor data, jenis data grafik Spanner akan dikonversi sebagai berikut, bergantung pada formatnya:

CSV

Semua jenis data dikonversi ke representasi string-nya:

• Nilai BOOL dikonversi menjadi true atau false.
• Nilai BYTES dienkode base64.
• Nilai TIMESTAMP diformat sebagai YYYY-MM-DD HH:MM:SS.ffffff UTC.
• Nilai NULL muncul sebagai string kosong.

Anda tidak dapat mengekspor data bertingkat dan berulang dalam format CSV.

Avro

Jenis data Spanner	Jenis data Avro
BOOL	BOOLEAN
INT64	LONG
FLOAT	FLOAT
DOUBLE	DOUBLE
NUMERIC	BYTES dengan jenis logika DECIMAL(38,9)
STRING	STRING
BYTES	BYTES
TIMESTAMP	LONG (mikrodetik sejak epoch)
NULL	null

Parquet

Jenis data Spanner	Jenis data Parquet
BOOL	BOOLEAN
INT64	INT64
FLOAT	FLOAT
DOUBLE	DOUBLE
NUMERIC	DECIMAL(38,9)
STRING	STRING
BYTES	BYTE_ARRAY
TIMESTAMP	TIMESTAMP_MICROS
NULL	null

Mempertahankan hasil ke Spanner

Opsi EXPORT DATA berikut didukung saat mempertahankan hasil kembali ke instance Spanner sumber Anda. Tentukan opsi dalam format berikut: NAME=VALUE, ....

Nama	Jenis Nilai	Wajib	Deskripsi
format	STRING	Ya	Format data yang diekspor. Harus berupa CLOUD_SPANNER.
table	STRING	Ya	Nama tabel Spanner tujuan untuk menulis hasil. Tabel ini dapat berupa tabel apa pun di instance Spanner.
write_mode	STRING	Ya	Mode tulis yang akan digunakan. Nilai yang didukung adalah: update_ignore_all: Memperbarui baris yang ada di tabel tujuan. upsert_ignore_all: Menyisipkan baris baru atau memperbarui baris yang ada di tabel tujuan. Dalam kedua mode, Spanner akan melewati semua data yang akan menyebabkan pelanggaran batasan (misalnya, kunci yang tidak ada saat update, pelanggaran indeks unik, pelanggaran batasan kunci asing). Namun, penulisan akan gagal untuk error pelanggaran non-batasan (misalnya, ketidakcocokan jenis kolom, nilai yang tidak ada untuk kolom NOT NULL).

Persyaratan

Saat Anda menyimpan hasil algoritma kembali ke Spanner, kueri algoritma Anda harus memenuhi persyaratan berikut:

• Tabel tujuan harus ada.
• Kolom harus ada dengan jenis yang cocok: Semua nama kolom yang ditentukan dalam klausa RETURN harus sudah ada di tabel tujuan dengan jenis data yang cocok. Gunakan alias untuk mencocokkan nama kolom tabel tujuan jika diperlukan. Contoh: RETURN node.id AS person_id.
• Sertakan semua kolom kunci utama: Klausa RETURN harus menyertakan semua kolom kunci utama tabel tujuan.

Semantik penulisan

Mempertahankan hasil kembali ke Spanner adalah operasi non-transaksional. Fitur ini menyediakan atomisitas tingkat baris. Artinya, sistem akan berhasil menulis semua kolom dari baris yang sama atau tidak menulis satu pun. Layanan ini mengikuti semantik setidaknya satu kali. Artinya, baris dapat ditulis beberapa kali. Membaca dari tabel tujuan saat eksekusi sedang berlangsung dapat menghasilkan hasil yang tidak lengkap.

Jika eksekusi keseluruhan gagal, sistem tidak akan me-roll back perubahan yang telah di-commit. Proses penulisan gagal pada error pertama yang tidak dapat dicoba lagi. Jika terjadi kegagalan penulisan, ERROR_MESSAGE di GRAPH_OPERATION_EXECUTION_STATUS menunjukkan kunci utama baris yang gagal beserta alasan spesifik kegagalan tersebut.

Sistem akan menulis hasil algoritma kembali ke Spanner Graph menggunakan MEDIUM prioritas.

Menjalankan kueri algoritma contoh

Bagian ini menunjukkan contoh kueri algoritma Spanner Graph yang dapat Anda jalankan di instance pengujian. Untuk mengetahui daftar lengkap algoritma yang didukung Spanner Graph, lihat Algoritma Spanner Graph.

Sebelum memulai

Untuk menjalankan contoh kueri algoritma Spanner Graph, Anda harus menyelesaikan langkah-langkah berikut terlebih dahulu:

1. Ikuti Menyiapkan dan membuat kueri Spanner Graph untuk membuat Spanner Graph.
2. Pastikan Anda memiliki izin yang diperlukan.
3. Opsional: Tambahkan skema Spanner Graph jika Anda mempertahankan output ke Spanner.

Tambahkan kolom baru bernama page_rank ke tabel Account. Spanner menulis hasil algoritma ke kolom baru ini. Kemudian, muat ulang definisi grafik agar Anda dapat mengakses page_rank sebagai properti node.

-- Add `page_rank` as a column. Data type of this column matches the data type defined in `PageRank` output signature.
ALTER TABLE Account ADD COLUMN page_rank FLOAT64;

-- Rerun the graph definition DDL to pickup `page_rank` as a new property.
CREATE OR REPLACE PROPERTY GRAPH FinGraph
  NODE TABLES (`Account`, `Person`)
  EDGE TABLES (
    `PersonOwnAccount`
      SOURCE KEY (id) REFERENCES `Person` (id)
      DESTINATION KEY (account_id) REFERENCES `Account` (id)
      LABEL `Owns`,
    `AccountTransferAccount`
      SOURCE KEY (id) REFERENCES `Account` (id)
      DESTINATION KEY (to_id) REFERENCES `Account` (id)
      LABEL `Transfers`
  );

Menjalankan algoritma pada grafik lengkap dengan filter label dan mempertahankan hasil ke Cloud Storage

Contoh ini menjalankan pernyataan PageRank untuk memberi peringkat akun berdasarkan transfer yang mereka ikuti. Hasil kueri dipertahankan ke bucket Cloud Storage dalam format CSV sebagai my-bucket-name/my-output.csv.

EXPORT DATA OPTIONS (
  uri = "gs://my-bucket-name/my-output.csv",
  format = "csv"
) AS
GRAPH FinGraph
CALL PageRank(node_labels => ['Account'], edge_labels => ['Transfers']) YIELD node, score
RETURN node.id, score AS page_rank

Di Cloud Storage, Anda akan melihat file CSV dengan dua kolom (id dan page_rank) saat kueri ini berhasil diselesaikan.

Menjalankan algoritma pada subgrafik yang ditentukan oleh MATCH dan mempertahankan hasil ke grafik

Contoh ini menggunakan pola MATCH untuk mencocokkan subgrafik logis secara dinamis yang berisi semua node Account dan hanya edge Transfer dengan jumlah kurang dari 500. Subgrafik logis ini adalah input untuk algoritma PageRank. Spanner menyimpan hasil algoritma kembali ke tabel Account.

EXPORT DATA OPTIONS (
  format = "CLOUD_SPANNER",
  table = "Account",
  write_mode = 'update_ignore_all'
) AS
GRAPH FinGraph
MATCH (n:Account)
RETURN n
FULL UNION ALL
MATCH -[e:Transfers WHERE e.amount < 500]->
RETURN e
NEXT
CALL PER () PageRank() YIELD node, score
RETURN node.id, score AS page_rank

Setelah kueri berhasil diselesaikan, jalankan kueri berikut:

GRAPH FinGraph
MATCH (n:Account)
RETURN n.id, ROUND(n.page_rank, 2) AS page_rank
ORDER BY page_rank DESC, id ASC

Anda akan melihat hasil yang mirip dengan berikut ini:

id	page_rank
20	0,49
16	0,46
7	0,05

Memeriksa status eksekusi algoritma

Saat kueri algoritma grafik berhasil diselesaikan, kueri tersebut akan menampilkan nol baris dan status Success. Bergantung pada ukuran grafik input dan konfigurasi algoritma tertentu, eksekusi algoritma mungkin memerlukan waktu beberapa saat untuk diselesaikan. Anda dapat memeriksa progres dan status eksekusi kueri algoritma grafik di tabel SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS. Tabel ini menyimpan informasi selama 30 hari.

Skema GRAPH_OPERATION_EXECUTION_STATUS

Nama kolom	Jenis	Deskripsi
QUERY_ID	STRING	ID untuk kueri algoritma grafik.
QUERY_TEXT	STRING	Teks pernyataan kueri.
START_TIMESTAMP	TIMESTAMP	Waktu saat kueri mulai dieksekusi.
LAST_UPDATE_TIMESTAMP	TIMESTAMP	Waktu saat status terakhir diperbarui.
PROGRESS	FLOAT64	Perkiraan persentase penyelesaian. Nilainya antara 0 dan 1, dengan 0 berarti dimulai dan 1 berarti selesai.
STATUS	STRING	Status eksekusi saat ini. Nilai yang mungkin mencakup PENDING, IN_PROGRESS, OK, atau kode status error seperti CANCELLED, DEADLINE_EXCEEDED, INVALID_ARGUMENT, FAILED_PRECONDITION, RESOURCE_EXHAUSTED, UNAVAILABLE, atau UNKNOWN.
ERROR_MESSAGE	STRING	Pesan error jika eksekusi kueri gagal.

Contoh kueri berikut mencantumkan kueri grafik yang belum berhasil diselesaikan:

SELECT
  query_id,
  query_text,
  start_timestamp,
  last_update_timestamp,
  progress,
  status,
  error_message
FROM
  SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS
WHERE
  status != "OK"
ORDER BY
  start_timestamp DESC;

Membatalkan eksekusi algoritma

Untuk membatalkan kueri algoritma grafik yang sedang berjalan, temukan query_id dari tabel SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS, lalu panggil cancel_query untuk query_id tersebut.

Langkah berikutnya

• Katalog algoritma Spanner Graph.
• Persyaratan skema algoritma Spanner Graph dan kompatibilitas fitur.

• Praktik terbaik algoritma Spanner Graph.