Ringkasan skema

Dokumen ini menjelaskan komponen skema grafik dan menunjukkan cara membuat dan mengelola skema grafik.

Grafik memungkinkan Anda membuat model data terhubung yang merepresentasikan informasi sebagai jaringan node dan edge. Skema grafik terdiri dari node dan edge, beserta label yang mengklasifikasikan jenisnya, dan properti yang mendeskripsikannya. Anda menentukan skema grafik dengan memetakan baris dari tabel input ke node dan edge grafik serta menentukan label dan properti kustom. Untuk mempelajari lebih lanjut BigQuery Graph, lihat Ringkasan BigQuery Graph.

Memahami model data grafik

Grafik memungkinkan Anda memodelkan data yang terhubung sebagai jaringan node dan edge. Node merepresentasikan entitas dalam data Anda, seperti pelanggan, produk, atau lokasi. Edge merepresentasikan koneksi antara node tersebut, yang menangkap hubungan seperti pembelian, pengikut, atau lokasi.

Node dan edge dapat menyertakan informasi berikut:

  • Label: mengklasifikasikan jenis node dan edge. Misalnya, siswa di kelas mungkin memiliki label Student dan label Person. Jika Anda tidak menentukan label untuk node atau edge secara eksplisit, BigQuery Graph akan menggunakan nama tabel input sebagai label default.

  • Properti: digunakan untuk mendeskripsikan node dan edge. Misalnya, node yang mewakili seseorang mungkin memiliki properti name dengan nilai Alex dan properti id dengan nilai 1.

Contoh pada Gambar 1 menunjukkan cara mendesain grafik untuk membuat model aktivitas keuangan. Grafik ini mencakup jenis entity berikut yang dimodelkan sebagai node:

  • Person: mewakili individu yang terlibat dalam transaksi keuangan.
  • Account: mewakili rekening bank yang digunakan untuk transaksi.

Entity ini dihubungkan oleh berbagai jenis hubungan, yang direpresentasikan oleh edge terarah berikut:

  • Memiliki: seseorang memiliki satu atau beberapa akun.
  • Transfer: uang dipindahkan dari satu rekening ke rekening lain.

Setiap edge terarah menunjukkan hubungan satu arah yang mengalir dari node sumber ke node tujuan. Misalnya, edge Transfers menghubungkan Account sumber ke Account tujuan, yang menunjukkan aliran uang.

Node, edge, label, dan properti grafik keuangan.

Gambar 1. Contoh grafik dengan beberapa node dan edge terarah.

Node dan edge menyertakan informasi tambahan dalam properti.

  • Node Person mencakup properti berikut:

    • name (STRING)
    • id (INT64)

  • Edge Transfers menyertakan properti ini:

    • amount (FLOAT64)

Edge berarah dan tidak berarah

Edge terarah menunjukkan arah tertentu dalam hubungan antara entity. Misalnya, seseorang memiliki akun, tetapi akun tidak memiliki seseorang. Namun, beberapa hubungan, seperti hubungan pertemanan di jaringan sosial, bersifat tidak terarah dan merepresentasikan koneksi timbal balik. Dalam hal ini, Anda dapat memodelkan tepi tidak berarah sebagai dua tepi berarah, satu tepi di setiap arah.

Mendesain skema Anda

BigQuery Graph memungkinkan Anda menggunakan pernyataan CREATE PROPERTY GRAPH untuk membuat grafik dari tabel. Tabel yang membuat grafik disebut tabel input.

Menentukan node

Node ditentukan oleh baris dalam jenis tabel atau tampilan berikut:

  • Tabel standar
  • Tabel eksternal
  • Tabel terkelola Apache Iceberg
  • Tabel katalog REST Iceberg Lakehouse
  • Tampilan, termasuk tampilan yang diotorisasi
  • Tampilan terwujud non-inkremental

Untuk menentukan node, tambahkan definisi node dalam klausa NODE TABLES. Bentuk paling sederhana dari definisi node berisi nama tabel input dengan kunci utama. BigQuery Graph memetakan baris dari tabel input ke node grafik.

Dalam contoh berikut, Anda menggunakan klausa NODE TABLES untuk menentukan node Account dalam grafik FinGraph. Definisi node berisi tabel input Account.

-- Create an Account table.
CREATE TABLE graph_db.Account (
  id           INT64 NOT NULL,
  create_time  TIMESTAMP,
  PRIMARY KEY (id) NOT ENFORCED
);

-- Use the Account table as the input table for the Account node definition.
CREATE PROPERTY GRAPH graph_db.FinGraph
  NODE TABLES (
    graph_db.Account
  );

Secara default, BigQuery menggunakan nama tabel sebagai label dan mengekspos semua kolom dari tabel input sebagai properti.

  • Setiap node akun menggunakan label Account.
  • Setiap node akun menyertakan properti id dan create_time dari kolom tabel Account.

Kunci elemen

Definisi node juga menentukan kunci elemen, yaitu kumpulan kolom yang secara unik mengidentifikasi node grafik. Secara default, kunci elemen adalah kunci utama tabel input. Atau, Anda dapat menggunakan klausa KEY untuk menentukan kunci elemen secara eksplisit.

Contoh berikut menentukan node Account dan node Person. Node Account menggunakan kunci utama tabel Account sebagai kunci elemennya. Node Person secara eksplisit menentukan kolom id sebagai kunci elemen menggunakan klausa KEY.

CREATE TABLE graph_db.Person (
  id           INT64 NOT NULL,
  name         STRING
);

CREATE TABLE graph_db.Account (
  id           INT64 NOT NULL,
  create_time  TIMESTAMP,
  PRIMARY KEY (id) NOT ENFORCED
);

CREATE PROPERTY GRAPH graph_db.FinGraph
  NODE TABLES (
    graph_db.Person KEY (id),
    graph_db.Account
  );
  • Setiap baris dengan kunci elemen non-null dipetakan ke node unik dalam grafik yang diidentifikasi oleh kunci elemen.
  • Baris dengan kunci elemen null akan diabaikan.

Tabel input yang sama dapat digunakan dalam beberapa definisi node. Dalam hal ini, baris tertentu dalam tabel input dipetakan ke satu node untuk setiap definisi node.

Menentukan edge

Edge ditentukan oleh baris dalam jenis tabel atau tampilan berikut:

  • Tabel standar
  • Tabel eksternal
  • Tabel terkelola Apache Iceberg
  • Tabel katalog REST Iceberg Lakehouse
  • Tampilan, termasuk tampilan yang diotorisasi
  • Tampilan terwujud non-inkremental

Untuk menentukan edge, tambahkan definisi edge ke klausa EDGE TABLES. Bentuk definisi edge yang paling sederhana berisi nama tabel input dan menentukan referensi node sumber dan tujuan. BigQuery Graph menggunakan definisi ini untuk memetakan baris dari tabel input ke edge grafik.

Secara default, BigQuery menggunakan nama tabel sebagai label dan mengekspos semua kolom dari tabel input sebagai properti.

Referensi node sumber dan tujuan

Definisi edge menentukan referensi node sumber dan tujuan menggunakan klausa SOURCE KEY, DESTINATION KEY, dan REFERENCES. Anda harus menentukan node sumber dan tujuan sebelum menggunakannya dalam definisi edge.

Dalam contoh berikut, Anda membuat grafik bernama FinGraph dengan elemen berikut:

  • Node Person dan Account
  • Edge PersonOwnAccount
CREATE TABLE graph_db.Person (
  id            INT64 NOT NULL,
  name          STRING,
  PRIMARY KEY (id) NOT ENFORCED
);

CREATE TABLE graph_db.Account (
  id            INT64 NOT NULL,
  create_time   TIMESTAMP,
  PRIMARY KEY (id) NOT ENFORCED
);

CREATE TABLE graph_db.PersonOwnAccount (
  id            INT64 NOT NULL,
  account_id    INT64 NOT NULL,
  create_time   TIMESTAMP,
  FOREIGN KEY (account_id) REFERENCES graph_db.Account (id) NOT ENFORCED,
  PRIMARY KEY (id, account_id) NOT ENFORCED
);

CREATE PROPERTY GRAPH graph_db.FinGraph
  NODE TABLES (
    graph_db.Person,
    graph_db.Account
  )
  EDGE TABLES (
    PersonOwnAccount
      SOURCE KEY (id) REFERENCES Person (id)
      DESTINATION KEY (account_id) REFERENCES Account (id)
  );

Setiap edge PersonOwnAccount menghubungkan node Person (sumber) ke node Account (tujuan).

  • Node sumber dari sebuah edge adalah node Person yang properti id-nya sama dengan properti id edge.
  • Node tujuan edge adalah node Account yang properti id-nya sama dengan properti account_id edge.
  • Kunci elemen adalah kunci utama tabel PersonOwnAccount, yaitu (id, account_id).
  • Setiap edge memiliki kumpulan properti yang sama dengan kolom dari tabel PersonOwnAccount.
  • Setiap edge memiliki label PersonOwnAccount default.

Memetakan baris ke tepi

Setiap baris dalam tabel input edge dengan kunci elemen non-null biasanya dipetakan ke satu edge dalam grafik Anda. Namun, jika referensi node sumber atau tujuan cocok dengan nol atau beberapa node dalam tabel node sumber atau tujuan, baris dalam tabel input edge dapat menghasilkan nol atau beberapa edge dalam grafik Anda.

Menentukan node dan edge dalam satu tabel

Anda dapat menentukan node dan edge masuk atau keluarnya dalam satu tabel jika kolom tabel Anda menentukan hubungan ke tabel lain. Pendekatan ini mengurangi jumlah tabel, menyederhanakan pengelolaan data, dan dapat meningkatkan performa kueri dengan menghilangkan kebutuhan untuk menggabungkan ke tabel edge terpisah.

Misalnya, jika tabel Account berikut memiliki kunci utama gabungan (owner_id, account_id), kolom owner_id dapat berupa kunci asing yang mereferensikan tabel Person. Struktur ini memungkinkan tabel Account untuk mewakili node Account dan edge masuk dari node Person.

CREATE TABLE graph_db.Person (
  id INT64 NOT NULL,
  PRIMARY KEY (id) NOT ENFORCED
);

-- Assume each account has exactly one owner.
CREATE TABLE graph_db.Account (
  owner_id INT64 NOT NULL,
  account_id INT64 NOT NULL,
  FOREIGN KEY (owner_id) REFERENCES graph_db.Person(id) NOT ENFORCED,
  PRIMARY KEY (owner_id, account_id) NOT ENFORCED
);

Anda dapat menggunakan tabel Account untuk menentukan node Account dan edge Owns yang masuk. Hal ini ditunjukkan dalam pernyataan CREATE PROPERTY GRAPH berikut. Dalam klausa EDGE TABLES, Anda memberi tabel Account alias Owns. Hal ini karena setiap elemen dalam skema grafik harus memiliki nama yang unik.

CREATE PROPERTY GRAPH graph_db.FinGraph
  NODE TABLES (
    graph_db.Person,
    graph_db.Account
  )
  EDGE TABLES (
    graph_db.Account AS Owns
      SOURCE KEY (owner_id) REFERENCES Person
      DESTINATION KEY (owner_id, account_id) REFERENCES Account
  );

Menyesuaikan label dan properti

Anda dapat menggunakan klausa LABEL dan PROPERTIES untuk menyesuaikan label dan properti.

Contoh berikut menentukan node Person dengan properti kustom dan node Account dengan beberapa label:

CREATE TABLE graph_db.Person (
  id               INT64 NOT NULL,
  name             STRING,
  birthday         TIMESTAMP,
  country          STRING,
  city             STRING,
  PRIMARY KEY (id) NOT ENFORCED
);

CREATE TABLE graph_db.Account (
  id               INT64 NOT NULL,
  create_time      TIMESTAMP,
  is_blocked       BOOL,
  nick_name        STRING,
  PRIMARY KEY (id) NOT ENFORCED
);

CREATE PROPERTY GRAPH graph_db.FinGraph
  NODE TABLES (
    graph_db.Person KEY (id)
      LABEL Customer
      PROPERTIES (CONCAT(city, ", ", country) AS address)
      LABEL Entity PROPERTIES (id, name),
    graph_db.Account KEY (id)
      DEFAULT LABEL OPTIONS(description = 'A checking or savings account')
      PROPERTIES (id, create_time)
      LABEL Entity
      PROPERTIES (
        id,
        nick_name AS name OPTIONS(description = 'A user-defined account name',
                                  synonyms = ['friendly name', 'display name'],
                                  extensions = [('data_classification', 'user'), ('currency', 'USD')])
      )
  );

  • Node Person menggunakan label Customer untuk mengekspos properti address. Properti address ditentukan oleh ekspresi CONCAT(city, ", ", country), yang merujuk ke kolom city dan country dari tabel input Person.

  • Node Account menggunakan label Account untuk mengekspos properti id dan create_time.

Node Person dan Account memiliki label Entity dengan properti id dan name.

  • Di node Person, properti id dan name berasal dari kolom tabel input.
  • Di node Account, properti name merujuk ke kolom nick_name dari tabel input.
  • Di node Account, properti name menggunakan klausa OPTIONS untuk memberikan deskripsi properti, daftar sinonim, dan daftar key-value pair metadata.

Menentukan opsi

Anda dapat menentukan metadata kustom yang ditentukan pengguna dalam klausa OPTIONS() dari definisi label atau properti, termasuk definisi pengukuran. Opsi berikut didukung:

  • description: Deskripsi string yang dapat dibaca manusia untuk label atau properti.
  • synonyms: Array string yang mewakili sinonim untuk label atau properti.
  • extensions: Array pasangan string (ARRAY<STRUCT<STRING, STRING>>) yang mewakili metadata tambahan. Anda dapat menggunakan ekstensi untuk memberikan metadata, unit, atau aturan pemformatan kustom, seperti [('currency', 'USD')].

Opsi ini memberikan konteks dan meningkatkan visibilitas untuk antarmuka kueri bahasa alami. Anda tidak dapat mengakses kolom ini secara langsung dalam kueri grafik dan kolom ini tidak mengubah hasil kueri GQL dengan cara apa pun.

Konsistensi label dan properti

Dalam grafik, label dan properti diidentifikasi secara unik berdasarkan namanya. Anda dapat menggunakan label dan properti dengan nama yang sama di beberapa definisi node atau edge. Namun, label dan properti dengan nama yang sama harus mengikuti aturan berikut:

  • Properti dengan nama yang sama harus menggunakan jenis nilai yang sama.
  • Label dengan nama yang sama harus menampilkan daftar properti yang sama.

Pada contoh sebelumnya, label Entity ditentukan di node Person dan Account. Kedua definisi menyertakan kumpulan nama properti yang sama, id dan name, dengan jenis nilai yang identik.

Mengelola dependensi skema

Grafik bergantung pada skema tabel input ke definisi node dan edge, serta kolom tabel yang direferensikan oleh properti. BigQuery Graph tidak memeriksa apakah penghapusan atau pengubahan tabel atau kolom akan membatalkan skema grafik yang ada.

Anda bertanggung jawab untuk menghindari perubahan skema yang dapat menyebabkan gangguan. Ikuti praktik terbaik berikut:

  • Sebelum menghapus tabel yang digunakan dalam definisi node grafik, hapus definisi node tersebut dari grafik terlebih dahulu.
  • Sebelum menghapus kolom dari tabel yang diekspos sebagai properti dalam grafik, hapus properti dari definisi node atau edge yang sesuai.

Melihat skema grafik

Untuk melihat pernyataan CREATE PROPERTY GRAPH yang digunakan untuk membuat grafik yang ada, buat kueri tabel virtual INFORMATION_SCHEMA.PROPERTY_GRAPHS:

SELECT
  property_graph_name,
  ddl
FROM
  `region-REGION`.INFORMATION_SCHEMA.PROPERTY_GRAPHS;

Ganti REGION dengan region set data yang berisi grafik.

Atau, Anda dapat memvisualisasikan skema grafik di notebook.

Memperbarui skema grafik

Untuk membuat perubahan apa pun pada skema grafik yang ada, Anda harus menentukan ulang skema grafik menggunakan pernyataan CREATE PROPERTY GRAPH.

Menghapus skema grafik

Untuk menghapus grafik, gunakan pernyataan DROP PROPERTY GRAPH.

Praktik terbaik

Bagian berikut menjelaskan praktik terbaik untuk menentukan skema grafik guna meningkatkan performa kueri grafik Anda.

Menentukan cakupan definisi properti Anda

Properti adalah key-value pair yang memberikan informasi tambahan yang dilampirkan ke node atau edge. Sebaiknya Anda hanya menyertakan properti yang diperlukan dalam node atau edge, dan menghindari penggunaan sintaksis PROPERTIES ALL COLUMNS atau sintaksis default yang melampirkan semua kolom dari tabel node atau edge ke daftar properti. Memiliki banyak properti di node atau edge dapat menyebabkan pemindaian kolom yang tidak perlu dalam kueri grafik, sehingga menurunkan performa.

Untuk membatasi properti yang Anda sertakan dalam definisi node atau edge, gunakan kata kunci PROPERTIES saat Anda menentukan properti elemen dalam pernyataan CREATE PROPERTY GRAPH.

Definisi tabel node berikut membatasi properti untuk tabel node Person menjadi id dan name:

NODE TABLES (
  graph_db.Person PROPERTIES (id, name)
)

Menentukan batasan kunci utama dan kunci asing pada node dan edge grafik

BigQuery dapat menggunakan batasan kunci utama dan asing pada tabel node dan edge untuk mengoptimalkan kueri grafik Anda dengan mengurangi pemindaian tabel yang tidak perlu. Namun, BigQuery tidak menerapkan batasan kunci utama atau kunci asing pada tabel. Jika aplikasi Anda tidak dapat menjamin integritas referensial atau keunikan pada kunci utama, penggunaan kunci utama atau asing untuk pengoptimalan kueri dapat menyebabkan hasil kueri yang salah.

Contoh berikut menentukan batasan kunci utama dan kunci asing pada tabel node Person dan Account, serta tabel edge PersonOwnAccount:

CREATE OR REPLACE TABLE graph_db.Person (
  id               INT64,
  name             STRING,
  birthday         TIMESTAMP,
  country          STRING,
  city             STRING,
  PRIMARY KEY (id) NOT ENFORCED
);

CREATE OR REPLACE TABLE graph_db.Account (
  id               INT64,
  create_time      TIMESTAMP,
  is_blocked       BOOL,
  nick_name        STRING,
  PRIMARY KEY (id) NOT ENFORCED
);

CREATE OR REPLACE TABLE graph_db.PersonOwnAccount (
  id               INT64 NOT NULL,
  account_id       INT64 NOT NULL,
  create_time      TIMESTAMP,
  PRIMARY KEY (id, account_id) NOT ENFORCED,
  FOREIGN KEY (id) references graph_db.Person(id) NOT ENFORCED,
  FOREIGN KEY (account_id) references graph_db.Account(id) NOT ENFORCED
);

Langkah berikutnya