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.

CATATAN: Jika Anda menjalankan algoritma grafik pada instance Spanner di region us-east1, Anda harus menentukan salah satu algoritma ini sebagai zone dalam parameter input algoritma: us-east1-b, us-east1-c, atau us-east1-d. Untuk semua wilayah lainnya, penentuan zona tidak diperlukan.

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>: Pernyataan MATCH opsional untuk menentukan elemen input algoritma.

• <call_statement>: Gunakan CALL jika Anda menghilangkan <match_clause> dan ingin mengoperasikan seluruh grafik. Gunakan CALL PER() jika <match_clause> ada dan Anda ingin mengoperasikan tabel kerja. Untuk mengetahui informasi selengkapnya, lihat PANGGILAN GQL.

• 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 Grafik Spanner.

• <algorithm_specific_output>: Output panggilan algoritma. Untuk mengetahui informasi selengkapnya, lihat output yang ditentukan dalam Algoritma Grafik Spanner dan 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 KLAUSUL GRAPH yang menghasilkan hasil kueri algoritma.

Dalam bentuknya yang paling sederhana, klausa grafik mengidentifikasi grafik, CALL sebagai algoritma yang menghasilkan output yang telah ditentukan sebelumnya, lalu menentukan apa yang harus RETURN 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 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. Hasil dipertahankan sesuai dengan export_option_list.

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

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

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 minimal satu label yang cocok yang 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 tepi. 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
zone	STRING	Tidak	(tidak ada)	Zona tempat eksekusi algoritma berlangsung. Harus berupa salah satu zona di region tempat kueri diterima.
max_idle_time	STRING	Tidak	Waktu lab	Menentukan berapa lama instance komputasi harus tetap aktif untuk digunakan kembali setelah algoritma selesai. Formatnya 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 menyimpan 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 yang dikelola Google [e-mail].

Opsi EXPORT DATA berikut didukung saat menyimpan 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	Pemisah 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 (*) dalam 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 kumpulan hasilnya 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 menjadi representasi stringnya:

• 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 menyimpan kembali hasil 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. Ini bisa berupa tabel apa pun di instance Spanner.
write_mode	STRING	Ya	Mode penulisan 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 pada update, pelanggaran indeks unik, pelanggaran batasan kunci asing). Namun, penulisan 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 dalam 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: Klausul 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. API ini mengikuti semantik setidaknya sekali. 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-rollback perubahan yang telah dilakukan 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 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 menyimpan 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 menyimpan hasil ke Cloud Storage

Contoh ini menjalankan PageRank untuk memberi peringkat Account berdasarkan Transactions yang mereka ikuti dan mempertahankan hasil ke 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 subgraf yang ditentukan oleh MATCH dan mempertahankan hasil ke grafik

Contoh ini menggunakan pola MATCH untuk mencocokkan subgrafis logis secara dinamis yang berisi semua node Account dan hanya tepi Transfer dengan jumlah kurang dari 500. Subgrafis logis ini adalah input ke 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

Jika kueri algoritma grafik berhasil diselesaikan, kueri 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	FLOAT	Estimasi persentase penyelesaian. Nilainya antara 0 dan 1, dengan 0 berarti dimulai dan 1 berarti selesai.
STATUS	STRING	Status eksekusi saat ini. Nilai yang mungkin adalah PENDING, IN_PROGRESS, OK, CANCELLED, DEADLINE_EXCEEDED, 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.