Mendesain skema SQL Connect

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

SQL 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.

Catatan: Ikuti rangkaian lengkap tentang pembuatan SQL Connect skema dan konektor, yang mencakup:

• Pengembangan skema (panduan ini)
• Pengembangan kueri
• Pengembangan mutasi

Panduan Memulai memperkenalkan skema aplikasi ulasan film untuk PostgreSQL.

Panduan ini mengembangkan skema tersebut lebih lanjut dan menyediakan listingan 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 SQL Connect, Anda akan menentukan jenis GraphQL untuk menentukan bentuk data yang dapat dikueri dan dimanipulasi oleh klien Anda. Saat Anda menulis skema, jenis Anda akan diterjemahkan ke Cloud SQL untuk tabel PostgreSQL, paling sering dalam hubungan langsung antara jenis GraphQL dan tabel database, meskipun pemetaan lain dimungkinkan. Panduan ini menunjukkan beberapa contoh dari dasar hingga yang lebih lanjut.

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. SQL Connect membuat 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.

Catatan: Karakter garis bawah, _, tidak dapat digunakan dalam nama kolom. SQL Connect menggunakan karakter tersebut saat membuat kolom tambahan, serta kueri dan mutasi implisit.

# 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, sehingga Anda memerlukan jenis User.

Direktif @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)")
}

Tips: Kumpulan lengkap ekstensi bahasa GraphQL untuk SQL Connect didokumentasikan dalam panduan referensi bahasa.

Skalar kunci dan nilai server

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

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

Dengan menggunakan nilai server, Anda dapat secara efektif mengizinkan 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 membuat model 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 [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, SQL Connect otomatis membuat kolom yang sesuai di sisi lain. Anda tidak perlu menentukan kolom pemetaan terbalik (misalnya, dari Actor kembali ke MovieActor).

Catatan: Relasi ditentukan di satu sisi, bukan keduanya. SQL Connect membuat nama dengan garis bawah (seperti actors_on_movies dan actors_via_actormovie) untuk menghindari konflik dengan nama kolom Anda sendiri.

Menangani hubungan one-to-one dalam jenis MovieMetadata

Sekarang, lacak sutradara film, serta siapkan hubungan one-to-one 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 direferensikan dalam tabel target (default ke kunci utama, tetapi kolom @unique juga berfungsi). Ini adalah opsi yang lebih canggih; SQL 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
}

Menggunakan kolom yang dibuat dari skema Anda untuk membuat operasi

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

Tips: Untuk menemukan kolom yang dibuat saat membuat operasi, gunakan editor kueri di konsol Firebase, atau ekstensi VS Code SQL Connect kami

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

Catatan: Kolom kueri ini memungkinkan Anda meneruskan jenis skalar kunci, di sini Movie_Key, untuk mengidentifikasi data. Kolom ini dibuat berdasarkan skema Anda.

Membuat kueri dengan
movie kolom

Kolom movie mewakili satu data 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
movies kolom

Kolom movies mewakili daftar data 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
actors_on_movies kolom

Kolom actors_on_movies mewakili daftar data 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 } } }

Tips: Bahasa definisi skema juga memungkinkan Anda mengontrol secara eksplisit cara nama dibuat untuk kolom menggunakan singular dan plural argumen untuk direktif @table.

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

Catatan: Lihat panduan memulai cepat atau panduan memulai cepat lokal untuk mengetahui informasi selengkapnya tentang cara menemukan kolom yang dibuat otomatis.

Konsep skema yang lebih canggih

Kolom enumerasi

SQL Connect mendukung kolom enumerasi yang dipetakan ke jenis enumerasi PostgreSQL. Enum memungkinkan Anda menentukan daftar nilai statis yang telah ditentukan sebelumnya dengan urutan tertentu secara cepat.

Untuk menambahkan enum ke skema Anda, deklarasikan enum dan nilai yang telah ditentukan sebelumnya, lalu referensikan dalam jenis Anda.

Catatan: Aturan berikut berlaku untuk kolom enum.

• Berdasarkan konvensi, nama enum:
  • harus diawali dengan huruf kapital dan dalam PascalCase (misalnya, ContentRating atau AspectRatio).
  • tidak boleh menyertakan karakter _ (garis bawah).
• Nilai enum:
  • harus UPPER_SNAKE_CASE.
  • tidak boleh diawali atau diakhiri dengan karakter garis bawah _.
  • dapat berisi deskripsi untuk dokumentasi inline (tidak ditampilkan atau diubah oleh operasi); nilai "string" apa pun yang ditemukan di atas nilai enum dianggap sebagai deskripsinya.
  • peka huruf besar/kecil, sehingga Academy dan ACADEMY akan menjadi dua nilai yang berbeda dan tidak dianggap sama.

enum AspectRatio {
   ACADEMY
   WIDESCREEN
   ANAMORPHIC
   IMAX
   "No information available on aspect ratio"
   UNAVAILABLE
}

type Movie
  @table {
  title: String! 
  genre: String
  description: String
  originalAspectRatio: AspectRatio! @default(value: WIDESCREEN)
  otherAspectRatios: [AspectRatio!]
  tags: [String]
  rating: Float
  imageUrl: String!
  releaseYear: Int
}

Dalam jenis Movie, kami menambahkan kolom enum originalAspectRatio untuk rasio aspek tempat film direkam, dan kolom otherAspectRatios lainnya untuk daftar rasio aspek lain yang tersedia.

Catatan: enum dapat diperlukan (menggunakan token !), memiliki nilai default (menggunakan direktif @default), dan digunakan dalam daftar (menggunakan sintaksis []). Secara umum, enum dapat diperlakukan sama dengan sebagian besar jenis data skalar lainnya seperti string dan bilangan bulat.

Mengelola perubahan pada kolom enumerasi

Anda dapat menambahkan nilai baru ke enum, tetapi urutan daftar enum sangat penting, jadi sisipkan nilai baru Anda dengan bijak. Satu-satunya perubahan yang sepenuhnya kompatibel dengan versi lama pada enum adalah menambahkan nilai baru ke akhir daftar nilai. Khususnya, menyisipkan nilai baru di antara enum yang sebelumnya dipublikasikan atau mengurutkan ulang nilai yang ada akan mengubah pengurutan relatif saat operator relatif seperti "kurang dari" digunakan dalam kueri. Menghapus atau mengganti nama nilai selalu merupakan perubahan yang tidak kompatibel dengan versi lama.

Anda tidak boleh mengurutkan ulang nilai dalam daftar nilai enum; pengurutan penting karena mengubah cara penerapan pemfilteran.

Catatan: Menyisipkan, mengganti nama, mengurutkan ulang, dan menghapus nilai enum adalah perubahan yang dapat menyebabkan error, karena siapa pun yang menggunakan versi terbaru database Anda tidak akan dapat mengurai atau menerima nilai yang diperbarui ini.

Penyesuaian pada nilai enum harus dilakukan dengan hati-hati agar tidak merusak versi lama operasi atau kode klien Anda. Saat menghapus atau mengganti nama nilai enum, pastikan tidak ada instance yang tersisa di database Anda saat ini.

Menggunakan kolom enum dalam operasi dan dalam kode klien

Setelah menambahkan kolom enum ke skema, Anda dapat menggunakan kolom ini dalam kueri dan kode klien.

Pelajari lebih lanjut cara menulis kueri menggunakan enum, dan cara menulis klien untuk mengizinkan penyesuaian pada enum Anda mulai dari panduan kueri.

Konsep lanjutan lainnya

Untuk mempelajari jenis dan hubungan yang lebih canggih, lihat contoh dalam dokumentasi referensi.

Jenis data yang didukung

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

Catatan: Jika Anda menetapkan serial PostgreSQL dataType dalam skema Anda (misalnya, myField: Int @col(dataType: "serial")). kolom database yang sesuai adalah jenis serial PostgreSQL (autoincrementing).

SQL Connect jenis	Jenis bawaan GraphQL atau SQL Connect jenis kustom	Jenis PostgreSQL default	Jenis PostgreSQL yang didukung (alias dalam tanda kurung)
String	GraphQL	teks	teks bit(n), varbit(n) char(n), varchar(n)
Int	GraphQL	int	Int2 (smallint, smallserial), int4 (integer, int, serial)
Float	GraphQL	float8	float4 (real) float8 (double precision) numeric (decimal)
Boolean	GraphQL	boolean	boolean
UUID	Kustom	uuid	uuid
Int64	Kustom	bigint	int8 (bigint, bigserial) numeric (decimal)
Tanggal	Kustom	date	date
Stempel waktu	Kustom	timestamptz	timestamptz Catatan: Informasi zona waktu lokal tidak disimpan. PostgreSQL mengonversi dan menyimpan stempel waktu tersebut sebagai UTC.
Enumerasi	Kustom	enum	enum
Vektor	Kustom	vektor	vektor Lihat Melakukan penelusuran kesamaan vektor dengan Vertex AI.

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

Skema SQL yang setara

Catatan: Skema ini tidak mewakili DDL atau transformasi skema SQL Connect. Skema ini hanya disediakan untuk ilustrasi.

-- 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

Catatan: Ikuti rangkaian lengkap tentang pembuatan SQL Connect konektor, yang mencakup:

• Pengembangan skema (panduan ini)
• Pengembangan kueri
• Pengembangan mutasi

Anda mungkin tertarik dengan:

• Membuat skema untuk aplikasi Anda menggunakan alat bantuan AI
• Meninjau dokumentasi referensi sintaksis.