דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

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

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

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

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

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

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

הסכימה של Movie מכילה הנחיות ליבה כמו:

‫@table(name) ו-@col(name) כדי להתאים אישית את הטבלה ואת שמות העמודות ב-SQL. אם לא מציינים שמות, Data Connect יוצר שמות בפורמט snake_case.
@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)")
}

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

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

ערכי סקלר של מפתח הם מזהי אובייקטים תמציתיים ש-Data 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 בטבלה עם אילוץ של מפתח זר, Data Connect יוצר באופן אוטומטי את השדה המתאים בצד השני. אין צורך להגדיר את שדה המיפוי ההפוך (לדוגמה, מ-Actor בחזרה ל-MovieActor).

טיפול בקשרים מסוג `MovieMetadata`

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

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

‫@ref(fields) מציין באילו שדות של מפתח זר להשתמש.
‫@ref(references) מציין את השדות שההפניה אליהם נעשית בטבלת היעד (ברירת המחדל היא המפתח הראשי, אבל אפשר להשתמש גם בשדות @unique). זו אפשרות מתקדמת יותר. בדרך כלל, Data 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
}

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

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

נניח שהסכימה מכילה סוג Movie וסוג Actor משויך. ‫Data 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 }
    }
  }

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

מושגים מתקדמים יותר בנושא סכימה

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

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

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

‫Data Connect type	סוג מובנה של GraphQL או Data 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.
Vector	בהתאמה אישית	וקטור	וקטור איך מבצעים חיפוש דמיון וקטורי באמצעות Vertex AI

‫GraphQL List ממופה למערך חד-ממדי.
- לדוגמה, [Int] ממפה אל int5[], ‏ [Any] ממפה אל jsonb[].
- ‫Data 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);

השלבים הבאים

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

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