Mendesain skema Data Connect

Dengan Firebase Data Connect, Anda mendesain skema GraphQL yang merepresentasikan model data yang diperlukan untuk aplikasi Anda. Data Connect mengonversi skema ini ke instance Cloud SQL untuk PostgreSQL yang mendukung aplikasi Anda. Kemudian, Anda menulis kueri dan mutasi untuk berinteraksi dengan backend dan menggabungkan operasi ini ke dalam konektor untuk menggunakan data dari kode klien.

Data Connect menawarkan alat AI untuk membantu Anda mendesain dan menerapkan skema. Panduan ini memperkenalkan konsep penting desain skema untuk mendukung dan melengkapi alur kerja standar dan yang dibantu AI saat Anda mulai mengembangkan aplikasi, dan seterusnya.

Panduan memulai memperkenalkan skema aplikasi ulasan film untuk PostgreSQL.

Panduan ini mengembangkan skema tersebut lebih lanjut dan memberikan daftar SQL yang setara dengan skema aplikasi ulasan film akhir.

Skema untuk aplikasi ulasan film

Bayangkan Anda ingin membuat layanan yang memungkinkan pengguna mengirim dan melihat ulasan film.

Anda memerlukan skema awal untuk aplikasi tersebut guna mendukung kueri dasar. Anda akan memperluas skema ini nanti untuk membuat kueri relasional yang kompleks.

Di Data Connect, Anda akan menentukan jenis GraphQL untuk menentukan bentuk data yang dapat dikueri dan dimanipulasi oleh klien Anda. Saat Anda menulis skema, jenis Anda diterjemahkan ke tabel Cloud SQL untuk PostgreSQL, paling sering dalam hubungan langsung antara jenis GraphQL dan tabel database, meskipun pemetaan lain dimungkinkan. Panduan ini menunjukkan beberapa contoh dari yang dasar hingga yang lebih canggih.

Menentukan jenis Movie dasar

Anda dapat memulai dengan jenis Movie.

Skema untuk Movie berisi direktif inti seperti:

  • @table(name) dan @col(name) untuk menyesuaikan nama tabel dan kolom SQL. Data Connect menghasilkan nama snake_case jika tidak ditentukan.
  • @col(dataType) untuk menyesuaikan jenis kolom SQL.
  • @default untuk mengonfigurasi nilai default kolom SQL selama penyisipan.

Untuk mengetahui detail selengkapnya, lihat dokumen referensi untuk @table, @col, @default.

# Movies
type Movie @table(name: "movie", key: "id") {
  id: UUID! @col(name: "movie_id") @default(expr: "uuidV4()")
  title: String!
  releaseYear: Int
  genre: String @col(dataType: "varchar(20)")
  rating: Int
  description: String
}

Menyimpan data pengguna penting secara otomatis dalam jenis User

Aplikasi Anda akan melacak pengguna, jadi Anda memerlukan jenis User.

Perintah @default sangat berguna dalam kasus ini. Kolom id di sini dapat otomatis mengambil ID pengguna dari autentikasi: perhatikan penggunaan @default(expr: "auth.uid") dalam contoh berikut.

# Users
# Suppose a user can leave reviews for movies
type User @table {
  id: String! @default(expr: "auth.uid")
  username: String! @col(dataType: "varchar(50)")
}

Skalar kunci dan nilai server

Sebelum melihat lebih lanjut aplikasi ulasan film, penting untuk memperkenalkan Data Connect skalar utama dan nilai server.

Skalar utama adalah ID objek ringkas yang Data Connect dirakit secara otomatis dari kolom utama dalam skema Anda. Skalar kunci berkaitan dengan efisiensi, yang memungkinkan Anda menemukan informasi tentang identitas dan struktur data dalam satu panggilan. Parameter ini sangat berguna saat Anda ingin melakukan tindakan berurutan pada rekaman baru dan memerlukan ID unik untuk diteruskan ke operasi mendatang, dan juga saat Anda ingin mengakses kunci relasional untuk melakukan operasi tambahan yang lebih kompleks.

Dengan nilai server, Anda dapat secara efektif membiarkan server mengisi kolom dalam tabel Anda secara dinamis menggunakan nilai yang disimpan atau mudah dihitung sesuai dengan ekspresi CEL sisi server tertentu dalam argumen expr. Misalnya, Anda dapat menentukan kolom dengan stempel waktu yang diterapkan saat kolom diakses menggunakan waktu yang disimpan dalam permintaan operasi, updatedAt: Timestamp! @default(expr: "request.time").

Menangani hubungan many-to-many dalam jenis Actor dan MovieActor

Setelah pengguna ditangani, Anda dapat kembali memodelkan data film.

Selanjutnya, Anda ingin aktor membintangi film Anda.

Tabel Actor cukup mudah.

# Actors
# Suppose an actor can participate in multiple movies and movies can have multiple actors
# Movie - Actors (or vice versa) is a many to many relationship
type Actor @table {
  id: UUID! @default(expr: "uuidV4()")
  name: String! @col(dataType: "varchar(30)")
}

Jika Anda ingin aktor berada dalam beberapa film dan film memiliki beberapa aktor, Anda memerlukan "tabel gabungan".

Tabel MovieActor menangani hubungan many-to-many, dan kunci utamanya adalah kombinasi dari [movie, actor] (kolom kunci asing dari movie dan actor).

# Join table for many-to-many relationship for movies and actors
# The 'key' param signifies the primary keys of this table
# In this case, the keys are [movieId, actorId], the foreign key fields of the reference fields [movie, actor]
type MovieActor @table(key: ["movie", "actor"]) {
  movie: Movie!
  # movieId: UUID! <- implicitly added foreign key field
  actor: Actor!
  # actorId: UUID! <- implicitly added foreign key field
  role: String! # "main" or "supporting"
  # optional other fields
}

Saat Anda menentukan hubungan SQL pada tabel dengan batasan kunci asing, Data Connect akan otomatis membuat kolom yang sesuai di sisi lainnya. Anda tidak perlu menentukan kolom pemetaan terbalik (misalnya, dari Actor kembali ke MovieActor).

Menangani hubungan one-to-one dalam jenis MovieMetadata

Sekarang, pantau sutradara film, serta siapkan hubungan satu-ke-satu dengan Movie.

Anda dapat menggunakan direktif @ref untuk menyesuaikan batasan kunci asing:

  • @ref(fields) menentukan kolom kunci asing yang akan digunakan.
  • @ref(references) menentukan kolom yang dirujuk dalam tabel target (secara default adalah kunci utama, tetapi kolom @unique juga berfungsi). Ini adalah opsi yang lebih lanjut; Data Connect sering kali dapat menyimpulkan hal ini untuk Anda.

Untuk mengetahui detail selengkapnya, lihat dokumen referensi untuk @ref.

# Movie Metadata
# Movie - MovieMetadata is a one-to-one relationship
type MovieMetadata @table {
  # @unique ensures that each Movie only has one MovieMetadata.
  movie: Movie! @unique
  # Since it references to another table type, it adds a foreign key constraint.
  #  movie: Movie! @unique @ref(fields: "movieId", references: "id")
  #  movieId: UUID! <- implicitly added foreign key field
  director: String
}

Gunakan kolom yang dibuat dari skema Anda untuk membuat operasi

Operasi Data Connect Anda akan memperluas sekumpulan kolom Data Connect yang dibuat secara otomatis berdasarkan jenis dan hubungan jenis dalam skema Anda. Kolom ini dibuat oleh alat lokal setiap kali Anda mengedit skema.

Asumsikan skema Anda berisi jenis Movie dan jenis Actor terkait. Data Connect menghasilkan kolom movie, movies, actors_on_movies, dan lainnya.

Membuat kueri dengan kolom
movie

Kolom movie mewakili satu catatan dalam tabel Movie.

Gunakan kolom ini untuk membuat kueri satu film berdasarkan kuncinya.

query GetMovie($myKey: Movie_Key!) {
  movie(key: $myKey) { title }
}

Membuat kueri dengan kolom
movies

Kolom movies merepresentasikan daftar catatan dalam tabel Movie.

Gunakan kolom ini untuk membuat kueri beberapa film, misalnya, semua film dengan tahun tertentu.

query GetMovies($myYear: Int!) {
  movies(where: { year: { eq: $myYear } }) { title }
}

Membuat kueri dengan kolom
actors_on_movies

Kolom actors_on_movies merepresentasikan daftar record yang menghubungkan tabel Actor dan Movie. Gunakan kolom ini untuk membuat kueri semua aktor yang terkait dengan film tertentu.

Gunakan kolom ini untuk membuat kueri semua aktor yang terkait dengan film tertentu.

  query GetActorsOnMovie($myKey: Movie_Key!) {
    actors_on_movies(where: { movie: { key: { eq: $myKey } } }) {
      actor { name }
    }
  }

Dengan mempertimbangkan hal ini, Anda dapat membaca cara menerapkan operasi menggunakan kolom ini dalam panduan penerapan kueri dan panduan penerapan mutasi.

Konsep skema yang lebih canggih

Untuk melampaui jenis dan hubungan dasar tetapi berguna, lihat contoh dalam dokumentasi referensi.

Jenis data yang didukung

Data Connect mendukung jenis data skalar berikut, dengan penetapan ke jenis PostgreSQL menggunakan @col(dataType:).

Jenis Data Connect Jenis bawaan GraphQL atau
Data Connect jenis kustom
Jenis PostgreSQL default Jenis PostgreSQL yang didukung
(alias dalam tanda kurung)
String GraphQL teks text
bit(n), varbit(n)
char(n), varchar(n)
Int GraphQL int Int2 (smallint, smallserial),
int4 (integer, int, serial)
Float GraphQL float8 float4 (real)
float8 (presisi ganda)
numeric (desimal)
Boolean GraphQL boolean boolean
UUID Kustom uuid uuid
Int64 Kustom bigint int8 (bigint, bigserial)
numeric (desimal)
Tanggal Kustom date tanggal
Stempel waktu Kustom timestamptz

timestamptz

Catatan: Informasi zona waktu lokal tidak disimpan.
PostgreSQL mengonversi dan menyimpan stempel waktu tersebut sebagai UTC.

Vektor Kustom vektor

vektor

Lihat Melakukan penelusuran kesamaan vektor dengan Vertex AI.

  • GraphQL List dipetakan ke array satu dimensi.
    • Misalnya, [Int] dipetakan ke int5[], [Any] dipetakan ke jsonb[].
    • Data Connect tidak mendukung array bertingkat.

Skema SQL yang setara

-- Movies Table
CREATE TABLE Movies (
    movie_id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    release_year INT,
    genre VARCHAR(30),
    rating INT,
    description TEXT,
    tags TEXT[]
);
-- Movie Metadata Table
CREATE TABLE MovieMetadata (
    movie_id UUID REFERENCES Movies(movie_id) UNIQUE,
    director VARCHAR(255) NOT NULL,
    PRIMARY KEY (movie_id)
);
-- Actors Table
CREATE TABLE Actors (
    actor_id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
    name VARCHAR(30) NOT NULL
);
-- MovieActor Join Table for Many-to-Many Relationship
CREATE TABLE MovieActor (
    movie_id UUID REFERENCES Movies(movie_id),
    actor_id UUID REFERENCES Actors(actor_id),
    role VARCHAR(50) NOT NULL, # "main" or "supporting"
    PRIMARY KEY (movie_id, actor_id),
    FOREIGN KEY (movie_id) REFERENCES Movies(movie_id),
    FOREIGN KEY (actor_id) REFERENCES Actors(actor_id)
);
-- Users Table
CREATE TABLE Users (
    user_id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
    user_auth VARCHAR(255) NOT NULL
    username VARCHAR(30) NOT NULL
);
-- Reviews Table
CREATE TABLE Reviews (
    review_id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
    user_id UUID REFERENCES Users(user_id),
    movie_id UUID REFERENCES Movies(movie_id),
    rating INT,
    review_text TEXT,
    review_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE (movie_id, user_id)
    FOREIGN KEY (user_id) REFERENCES Users(user_id),
    FOREIGN KEY (movie_id) REFERENCES Movies(movie_id)
);
-- Self Join Example for Movie Sequel Relationship
ALTER TABLE Movies
ADD COLUMN sequel_to UUID REFERENCES Movies(movie_id);

Langkah berikutnya

Anda mungkin tertarik dengan: