תכנון סכימות של SQL Connect

ב-Firebase SQL Connect, אתם מתכננים סכימת GraphQL שמייצגת את מודל הנתונים שנדרש לאפליקציה. ‫SQL Connect ממיר את הסכימה הזו למכונה של Cloud SQL ל-PostgreSQL שמגבה את האפליקציה. לאחר מכן, אתם יוצרים שאילתות ומוטציות כדי להתממשק עם הקצה העורפי, ומאגדים את הפעולות האלה למחברים כדי להשתמש בנתונים שלכם מקוד הלקוח.

‫SQL Connect מציע כלי AI שיעזרו לכם לתכנן ולהטמיע את הסכימות. במדריך הזה נציג מושגים חשובים בתכנון סכימות, שיעזרו לכם בתהליכי העבודה הרגילים והמבוססים על AI כשאתם מתחילים לפתח אפליקציה ובהמשך.

במדריך לתחילת העבודה הצגנו סכימה של אפליקציה לביקורות על סרטים ב-PostgreSQL.

במדריך הזה נפתח את הסכימה הזו ונספק רשימת SQL שוות ערך לסכימה הסופית של אפליקציית ביקורות הסרטים.

הסכימה של אפליקציה לביקורות על סרטים

נניח שאתם רוצים ליצור שירות שמאפשר למשתמשים לשלוח ביקורות על סרטים ולצפות בהן.

כדי לתמוך בשאילתות בסיסיות, צריך סכימה ראשונית לאפליקציה כזו. בהמשך תרחיבו את הסכימה הזו כדי ליצור שאילתות קשורות מורכבות.

ב-SQL Connect, מגדירים סוגי GraphQL כדי להגדיר את צורת הנתונים שהלקוחות יכולים לשלוח לגביהם שאילתות ולשנות אותם. כשכותבים את הסכימה, הסוגים מתורגמים לטבלאות Cloud SQL ל-PostgreSQL, בדרך כלל בקשר ישיר בין סוגי GraphQL לטבלאות של מסדי נתונים, אבל אפשר גם למפות בדרכים אחרות. במדריך הזה מוצגות כמה דוגמאות, החל מדוגמאות בסיסיות ועד לדוגמאות מתקדמות יותר.

הגדרת סוג בסיסי של Movie

אפשר להתחיל עם סוג Movie.

הסכימה של Movie מכילה הוראות ליבה כמו:

  • ‫@table(name) ו-@col(name) כדי להתאים אישית את שמות הטבלאות והעמודות ב-SQL. אם לא מציינים את הפרמטר, SQL Connect יוצר שמות עם קו תחתון בין המילים.
  • @col(dataType) כדי להתאים אישית את סוגי העמודות ב-SQL.
  • ‫@default כדי להגדיר ערכי ברירת מחדל לעמודות SQL במהלך ההוספה.

לפרטים נוספים, אפשר לעיין במסמכי העזרה של @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
}

אחסון אוטומטי של נתוני משתמשים חשובים בסוג User

האפליקציה תעקוב אחרי המשתמשים, ולכן צריך סוג User.

ההוראה @default שימושית במיוחד במקרה הזה. השדה id יכול לאסוף באופן אוטומטי את מזהה המשתמש מהאימות: שימו לב לשימוש ב-@default(expr: "auth.uid") בדוגמה הבאה.

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

ערכים סקלריים מרכזיים וערכי שרת

לפני שנמשיך לבחון את האפליקציה לביקורת סרטים, חשוב להציג את SQL Connect הסקלרים העיקריים וערכי השרת.

סקלרים של מפתחות הם מזהי אובייקטים תמציתיים ש-SQL Connect אוסף באופן אוטומטי משדות המפתחות בסכימות. הערכים הסקלריים העיקריים קשורים ליעילות, ומאפשרים לכם למצוא בקריאה אחת מידע על הזהות והמבנה של הנתונים. הם שימושיים במיוחד כשרוצים לבצע פעולות רציפות ברשומות חדשות וצריך מזהה ייחודי כדי להעביר לפעולות הבאות, וגם כשרוצים לגשת למפתחות יחסיים כדי לבצע פעולות נוספות ומורכבות יותר.

באמצעות ערכי שרת, אתם יכולים לאפשר לשרת לאכלס באופן דינמי שדות בטבלאות שלכם באמצעות ערכים מאוחסנים או ערכים שניתן לחשב בקלות, בהתאם לביטויי CEL מסוימים בצד השרת בארגומנט expr. לדוגמה, אפשר להגדיר שדה עם חותמת זמן שחלה כשניגשים לשדה באמצעות הזמן שמאוחסן בבקשת פעולה, updatedAt: Timestamp! @default(expr: "request.time").

טיפול בקשרים מסוג רבים לרבים בסוגים Actor ו-MovieActor

עכשיו, אחרי שטיפלתם במשתמשים, אתם יכולים לחזור ליצירת מודלים של נתוני סרטים.

עכשיו אתם רוצים שחקנים שיככבו בסרטים שלכם.

הטבלה Actor די פשוטה.

# 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)")
}

אם רוצים ששחקנים יופיעו בכמה סרטים ובסרטים יהיו כמה שחקנים, צריך "טבלת איחוד".

הטבלה MovieActor מטפלת בקשר רבים לרבים, והמפתח הראשי שלה הוא שילוב של [movie, actor] (שדות המפתח הזר מ-movie ומ-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
}

כשמגדירים קשר SQL בטבלה עם אילוץ של מפתח זר, SQL Connect יוצר באופן אוטומטי את השדה התואם בצד השני. אין צורך להגדיר את שדה המיפוי ההפוך (למשל, מ-Actor בחזרה אל MovieActor).

טיפול בקשרים של אחד לאחד בסוג MovieMetadata

עכשיו, עקבו אחרי במאי הסרטים, והגדירו קשר אחד לאחד עם Movie.

אפשר להשתמש בהוראה @ref כדי להתאים אישית את האילוצים של המפתח הזר:

  • ‫@ref(fields) מציין באילו שדות של מפתחות זרים להשתמש.
  • ‫@ref(references) מציין את השדות שאליהם מפנים בטבלת היעד (ברירת המחדל היא המפתח הראשי, אבל גם שדות @unique פועלים). זו אפשרות מתקדמת יותר. לעיתים קרובות, SQL Connect יכול להסיק את זה בשבילכם.

לפרטים נוספים, אפשר לעיין במסמכי העזרה של @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
}

שימוש בשדות שנוצרו מהסכימה כדי ליצור פעולות

הפעולות של SQL Connect ירחיבו קבוצה של שדות שנוצרו באופן אוטומטי על ידי SQL Connect, על סמך הסוגים והקשרים בין הסוגים בסכימה. השדות האלה נוצרים על ידי כלים מקומיים בכל פעם שעורכים את הסכימה.

נניח שהסכימה מכילה סוג Movie וסוג Actor משויך. ‫SQL Connect יוצר את השדות movie,‏ movies,‏ actors_on_movies ועוד.

שאילתה עם השדה
movie

השדה movie מייצג רשומה אחת בטבלה Movie.

אפשר להשתמש בשדה הזה כדי לשלוח שאילתה לגבי סרט אחד לפי המפתח שלו.

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

שאילתה עם השדה
movies

השדה movies מייצג רשימה של רשומות בטבלה Movie.

אפשר להשתמש בשדה הזה כדי לשלוח שאילתה על כמה סרטים, למשל כל הסרטים משנה מסוימת.

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

שאילתה עם השדה
actors_on_movies

השדה actors_on_movies מייצג רשימה של רשומות שמקשרות בין הטבלאות Actor ו-Movie. אפשר להשתמש בשדה הזה כדי לשלוח שאילתה על כל השחקנים שמשויכים לסרט מסוים.

אפשר להשתמש בשדה הזה כדי לשלוח שאילתה על כל השחקנים שמשויכים לסרט מסוים.

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

בהתאם לכך, אתם יכולים לקרוא איך להטמיע פעולות באמצעות השדות האלה במדריך להטמעת שאילתות ובמדריך להטמעת מוטציות.

מושגים מתקדמים יותר של סכימה

שדות ספירה

‫SQL Connect תומך בשדות מסוג enum שממופים לסוגי enum ב-PostgreSQL. בעזרת טיפוסי Enum אפשר להגדיר במהירות רשימה של ערכים סטטיים ומוגדרים מראש בסדר מסוים.

כדי להוסיף enum לסכימה, מגדירים את ה-enum ואת הערכים המוגדרים מראש שלו, ואז מפנים אליו בסוג.

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
}

בסוג Movie, הוספנו שדה enum‏ originalAspectRatio ליחס הגובה-רוחב שבו הסרט צולם, ושדה נוסף otherAspectRatios לרשימה של יחסי גובה-רוחב זמינים אחרים.

ניהול שינויים בשדות של ערכים מוגדרים מראש

אפשר להוסיף ערכים חדשים ל-enum, אבל הסדר של רשימת ה-enum חשוב מאוד, אז כדאי להוסיף את הערכים החדשים בזהירות. השינוי היחיד ב-enum שתואם באופן מלא לדורות קודמים הוא הוספת ערך חדש לסוף רשימת הערכים. חשוב לציין שהוספת ערך חדש בין ערכי enum שכבר פורסמו, או שינוי הסדר של ערכים קיימים, משנים את הסדר היחסי כשמשתמשים בשאילתות באופרטורים יחסיים כמו "פחות מ-". הסרה או שינוי שם של ערכים הם תמיד שינויים שלא תואמים לאחור.

אסור לשנות את הסדר של הערכים ברשימת ערכי ה-enum. הסדר חשוב כי הוא משנה את אופן הסינון.

צריך לבצע שינויים בערכי enum בזהירות כדי לא לשבש גרסאות ישנות יותר של הפעולה או של קוד הלקוח. כשמסירים ערך enum או משנים את השם שלו, חשוב לוודא שלא נשארו מופעים שלו במסד הנתונים הנוכחי.

שימוש בשדות enum בפעולות ובקוד הלקוח

עכשיו, אחרי שהוספתם שדה enum לסכימה, אתם יכולים להשתמש בשדה הזה בשאילתות ובקוד הלקוח.

במדריך לשאילתות מוסבר איך לכתוב שאילתות באמצעות טיפוסי enum ואיך לכתוב לקוח שיאפשר לבצע שינויים בטיפוסי ה-enum.

מושגים מתקדמים אחרים

כדי להרחיב את הידע מעבר לסוגים וליחסים הבסיסיים, אפשר לעיין בדוגמאות שבמאמרי העזרה.

סוגי נתונים נתמכים

‫SQL Connect תומך בסוגי הנתונים הסקלריים הבאים, עם הקצאות לסוגי PostgreSQL באמצעות @col(dataType:).

סוג SQL Connect סוג מובנה של GraphQL או
SQL Connect סוג מותאם אישית 		סוג ברירת המחדל של PostgreSQL סוגי PostgreSQL נתמכים
(שם חלופי בסוגריים)
מחרוזת GraphQL טקסט 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 (double precision)
numeric (decimal)
בוליאני GraphQL בוליאני בוליאני
מזהה ייחודי אוניברסלי (UUID) בהתאמה אישית uuid uuid
Int64 בהתאמה אישית bigint int8 (bigint, bigserial)
numeric (decimal)
תאריך בהתאמה אישית date תאריך
חותמת זמן בהתאמה אישית timestamptz

timestamptz

הערה: פרטי אזור הזמן המקומי לא נשמרים.
‫PostgreSQL ממיר חותמות זמן כאלה ומאחסן אותן כ-UTC.
ערכי ספירה בהתאמה אישית enum

טיפוסים בני מנייה (enum)
וקטור בהתאמה אישית וקטור

וקטור

מידע נוסף זמין במאמר ביצוע חיפוש וקטורי לפי דמיון באמצעות Vertex AI.
  • ‫List ב-GraphQL ממופה למערך חד-ממדי.
    • לדוגמה, [Int] ממופה אל int5[], ו-[Any] ממופה אל jsonb[].
    • אין תמיכה במערכים בתוך מערכים ב-SQL Connect.

סכימת SQL מקבילה

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

השלבים הבאים

אולי יעניין אותך גם: