סכימות, שאילתות ומוטציות של Data Connect

הערה: Firebase Data Connect נמצא בגרסת טרום-השקה ציבורית. Data Connect יהיה כפוף לתנאים של 'מבצעי Pre-GA' בקטע התנאים הספציפיים לשירות בתנאים ובהגבלות של Google Cloud Platform. תכונות שעדיין לא הגיעו ל-GA זמינות "כפי שהן", ויכול להיות שהתמיכה בהן מוגבלת. מידע נוסף זמין בקטע תיאורים של שלבי ההשקה.

באמצעות Firebase Data Connect אפשר ליצור מחברים למכונות PostgreSQL שמנוהלות באמצעות Google Cloud SQL. המחברים האלה הם שילובים של סכימה, שאילתות ומוטציות לשימוש בנתונים שלכם.

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

במדריך הזה מוצגות שאילתות ומוטציות של Data Connect עם דוגמאות לסכימות. למה מדברים על שאילתות (ועל מוטציות) במדריך בנושא סכימות של Data Connect? בדומה לפלטפורמות אחרות שמבוססות על GraphQL, Firebase Data Connect היא פלטפורמת פיתוח שמתמקדת בשאילתות. לכן, כמפתחים, בתהליך בניית מודל הנתונים עליכם להביא בחשבון את הנתונים שהלקוחות שלכם זקוקים להם, כי הם ישפיעו מאוד על סכימה של הנתונים שתפתחו לפרויקט.

טיפ: הקבוצה המלאה של תוספי השפה של GraphQL עבור Data Connect מפורטת במדריך העזרה של השפה.

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

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

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

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

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

טבלת סרטים

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

• @table, שמאפשרת לנו להגדיר שמות של פעולות באמצעות הארגומנטים singular ו-plural
• @col כדי להגדיר שמות של עמודות באופן מפורש
• @default כדי לאפשר הגדרת ברירות מחדל.

הערה: לא ניתן להשתמש בקו תחתון, _, בשמות של שדות. Data Connect משתמש בתווית הזו כשיוצר שדות משניים, שאילתות ומוטציות מרומזות.

# Movies
type Movie
  @table(name: "Movies", singular: "movie", plural: "movies", key: ["id"]) {
  id: UUID! @col(name: "movie_id") @default(expr: "uuidV4()")
  title: String!
  releaseYear: Int @col(name: "release_year")
  genre: String
  rating: Int @col(name: "rating")
  description: String @col(name: "description")
}

ערכי שרת ומשתני מפתח סקלריים

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

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

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

טבלת המטא-נתונים של הסרט

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

מוסיפים את ההנחיה @ref כדי להגדיר קשרים.

# Movie Metadata
# Movie - MovieMetadata is a one-to-one relationship
type MovieMetadata
  @table(
    name: "MovieMetadata"
  ) {
  # @ref creates a field in the current table (MovieMetadata) that holds the
  # primary key of the referenced type
  # In this case, @ref(fields: "id") is implied
  movie: Movie! @ref
  # movieId: UUID <- this is created by the above @ref
  director: String @col(name: "director")
}

Actor ו-MovieActor

בשלב הבא, אתם רוצים ששחקנים יופיעו בסרטים שלכם, וכיוון שיש לכם יחס 'הרבה לרבים' בין סרטים לשחקנים, צריך ליצור טבלת צירוף.

# 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(name: "Actors", singular: "actor", plural: "actors") {
  id: UUID! @col(name: "actor_id") @default(expr: "uuidV4()")
  name: String! @col(name: "name", dataType: "varchar(30)")
}
# Join table for many-to-many relationship for movies and actors
# The 'key' param signifies the primary key(s) of this table
# In this case, the keys are [movieId, actorId], the generated fields of the reference types [movie, actor]
type MovieActor @table(key: ["movie", "actor"]) {
  # @ref creates a field in the current table (MovieActor) that holds the primary key of the referenced type
  # In this case, @ref(fields: "id") is implied
  movie: Movie! @ref
  # movieId: UUID! <- this is created by the above @ref, see: implicit.gql
  actor: Actor! @ref
  # actorId: UUID! <- this is created by the above @ref, see: implicit.gql
  role: String! @col(name: "role") # "main" or "supporting"
  # optional other fields
}

משתמש

לבסוף, משתמשים באפליקציה.

# Users
# Suppose a user can leave reviews for movies
# user:reviews is a one to many relationship, movie:reviews is a one to many relationship, movie:user is a many to many relationship
type User
  @table(name: "Users", singular: "user", plural: "users", key: ["id"]) {
  id: UUID! @col(name: "user_id") @default(expr: "uuidV4()")
  auth: String @col(name: "user_auth") @default(expr: "auth.uid")
  username: String! @col(name: "username", dataType: "varchar(30)")
  # The following are generated from the @ref in the Review table
  # reviews_on_user
  # movies_via_Review
}

טיפ: הקבוצה המלאה של התוספים לשפת GraphQL עבור Data Connect מפורטת במדריך העזרה של השפה.

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

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

הערה: אם מקצים dataType של PostgreSQL בסכימה (לדוגמה, myField: Int @col(dataType: "serial")), העמודה התואמת במסד הנתונים היא מסוג PostgreSQL serial (autoincrementing).

סוג Data Connect	סוג מובנה של GraphQL או סוג Data Connect בהתאמה אישית	סוג ברירת המחדל של PostgreSQL	סוגי PostgreSQL נתמכים (כינוי בסוגריים)
String	GraphQL	טקסט	text bit(n), varbit(n) char(n), varchar(n)
Int	GraphQL	int	Int2‏ (smallint, ‏ smallserial), ‏ int4‏ (integer, ‏ int, ‏ serial)
Float	GraphQL	float8	float4 (מספר ממשי) float8 (דיוק כפול) numeric (עשרוני)
בוליאני	GraphQL	בוליאני	בוליאני
מזהה ייחודי אוניברסלי (UUID)	בהתאמה אישית	uuid	uuid
Int64	בהתאמה אישית	bigint	int8‏ (bigint, ‏ bigserial) numeric (decimal)
תאריך	בהתאמה אישית	date	תאריך
חותמת זמן	בהתאמה אישית	timestamptz	timestamptz הערה: פרטי אזור הזמן המקומי לא נשמרים. PostgreSQL ממירה ומאחסנת חותמות זמן כאלה כ-UTC.
Vector	בהתאמה אישית	vector	וקטור ביצוע חיפוש דמיון וקטורי באמצעות Vertex AI

• List ב-GraphQL ממופה למערך דו-מימדי.
  • לדוגמה, [Int] ממופה ל-int5[], ו-[Any] ממופה ל-jsonb[].
  • אין תמיכה במערכים בתצוגת עץ ב-Data Connect.

שאילתות ומוטציות מרומזות ומוגדרות מראש

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

בתהליך הפיתוח, תטמיעו שאילתות מוגדרות מראש ומוטציות מוגדרות מראש על סמך הפעולות המשתמעות האלה.

הערה: קוד הלקוח יכול להפעיל רק את השאילתות והמוטציות שהוגדרו מראש. לקוחות לא יכולים להפעיל שאילתות או מוטציות מרומזות.

טיפ: כדי לגלות את השאילתות המרומזות שנוצרות במהלך היצירה של שאילתות מוגדרות מראש, אפשר להשתמש בתוסף שלנו ל-Visual Studio Code, באופן מקומי או בסביבת IDX.

מתן שמות מרומזים לשאילתות ולמוטציות

Data Connect מסיק שמות מתאימים לשאילתות ולמוטציות מרומזות מהצהרות הסוג של הסכימה. לדוגמה, כשעובדים עם מקור של PostgreSQL, אם מגדירים טבלה בשם Movie, השרת יוצר באופן משתמע:

• שאילתות לתרחישי שימוש עם טבלה אחת עם השמות הידידותיים movie (יחיד, לאחזור תוצאות בודדות עם העברת ארגומנטים כמו eq) ו-movies (רבים, לאחזור רשימות תוצאות עם העברת ארגומנטים כמו gt ופעולות כמו orderby). Data Connect יוצר גם שאילתות לפעולות יחסיות עם כמה טבלאות עם שמות מפורשים כמו actors_on_movies או actors_via_actormovie.
• מוטציות בשם movie_insert, ‏ movie_upsert…

שפת הגדרת הסכימה מאפשרת גם להגדיר שמות של פעולות באופן מפורש באמצעות ארגומנטים של ההנחיות singular ו-plural.

הנחיות לשאילתות ולמוטציות

בנוסף להנחיות שבהן משתמשים להגדרת סוגים וטבלאות, ב-Data Connect יש את ההנחיות @auth, ‏ @check, ‏ @redact ו-@transaction להרחבת ההתנהגות של שאילתות ומוטציות.

דירקטיבה	רלוונטי ל:	תיאור
@auth	שאילתות ומוטציות	הגדרת מדיניות האימות לשאילתה או למוטציה. המדריך לאימות והרשאה
@check	שאילתות לחיפוש נתוני הרשאה	בדיקה שהשדות שצוינו נמצאים בתוצאות השאילתה. ביטוי של Common Expression Language ‏ (CEL) משמש לבדיקת ערכי השדות. המדריך לאימות והרשאה
@redact	שאילתות	מחיקה של חלק מהתשובה מהלקוח. המדריך לאימות והרשאה
@transaction	מוטציות	אכיפה של כך שטרנספורמציה תמיד תרוץ בטרנזקציה של מסד נתונים. דוגמאות למוטציות של אפליקציות סרטים

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

שאילתות למסד הנתונים של ביקורות על סרטים

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

במדריך למתחילים, לא נדרשו פרמטרים לשאילתה לדוגמה listEmails. כמובן, במקרים רבים הנתונים שיועברו לשדות השאילתה יהיו דינמיים. אפשר להשתמש בתחביר $variableName כדי לעבוד עם משתנים כאחד מהרכיבים של הגדרת השאילתה.

טיפ: אתם יכולים להשתמש ב-Gemini ב-Firebase כדי ליצור ולבדוק שאילתות GraphQL במסוף Firebase. מידע נוסף זמין במאמר שימוש בעזרה של AI לשאילתות ולמוטציות.

כך נראית השאילתה הבאה:

• הגדרת סוג query
• שם של פעולה (שאילתה) ב-ListMoviesByGenre
• ארגומנט פעולה של משתנה יחיד $genre
• הוראה יחידה, @auth.

query ListMoviesByGenre($genre: String!) @auth(level: USER)

לכל ארגומנט של שאילתה נדרשת הצהרת סוג, סוג מובנה כמו String או סוג מותאם אישית שמוגדר בסכימה כמו Movie.

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

מפתחות סקלר בשאילתות

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

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

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

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

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

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

אפשר לספק אותם בבקשה בפורמט JSON כך (או בפורמטים אחרים של שרשור):

{
  # …
  "variables": {
    "myKey": {"foo": "some-string-value", "bar": 42}
  }
}

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

שימוש בכינויים בשאילתות

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

זוהי שאילתה שבה ביטוי משתמש בכינוי mostPopular.

query ReviewTopPopularity($genre: String) {
  mostPopular: review(first: {
    where: {genre: {eq: $genre}},
    orderBy: {popularity: DESC}
  }) { … }
}

שאילתות פשוטות עם מסננים

שאילתות Data Connect ממופות לכל המסננים והפעולות הנפוצות של SQL.

אופרטורים where ו-orderBy (שאילתות יחיד, שאילתות רבים)

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

query MovieByTopRating($genre: String) {
  mostPopular: movies(
     where: { genre: { eq: $genre } }, orderBy: { rating: DESC }
  ) {
    # graphql: list the fields from the results to return
    id
    title
    genre
    description
  }
}

query MoviesByReleaseYear($min: Int, $max: Int) {
  movies(where: {releaseYear: {le: $max, ge: $min}}, orderBy: [{releaseYear: ASC}]) { … }
}

אופרטורים limit ו-offset (שאילתות יחיד, שאילתות רבים)

אפשר לבצע פירוט לדפים בתוצאות. אפשר להעביר את הארגומנטים האלה, אבל הם לא מופיעים בתוצאות.

query MoviesTop10 {
  movies(orderBy: [{ rating: DESC }], limit: 10) {
    # graphql: list the fields from the results to return
    title
  }
}

כולל בשדות מערך

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

# Filter using arrays and embedded fields.
query ListMoviesByTag($tag: String!) {
  movies(where: { tags: { includes: $tag }}) {
    # graphql: list the fields from the results to return
    id
    title
  }
}

פעולות על מחרוזות וביטויים רגולריים

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

query MoviesTitleSearch($prefix: String, $suffix: String, $contained: String, $regex: String) {
  prefixed: movies(where: {title: {startsWith: $prefix}}) {...}
  suffixed: movies(where: {title: {endsWith: $suffix}}) {...}
  contained: movies(where: {title: {contains: $contained}}) {...}
  matchRegex: movies(where: {title: {pattern: {regex: $regex}}}) {...}
}

or ו-and למסננים מורכבים

משתמשים ב-or וב-and ללוגיקה מורכבת יותר.

query ListMoviesByGenreAndGenre($minRating: Int!, $genre: String) {
  movies(
    where: { _or: [{ rating: { ge: $minRating } }, { genre: { eq: $genre } }] }
  ) {
    # graphql: list the fields from the results to return
    title
  }
}

טיפ: הקבוצה המלאה של תוספי השפה של GraphQL עבור Data Connect מפורטת במדריך העזרה של השפה.

שאילתות מורכבות

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

בשאילתות כאלה נעשה שימוש בתחביר הקסום Data Connect _on_ ו-_via בשאילתות מרומזות שנוצרות.

תבצעו שינויים בסכימה מהגרסה הראשונית שלנו.

רבים לאחד

נוסיף ביקורות לאפליקציה שלנו, באמצעות טבלה Review ושינוי ב-User.

# Users
# Suppose a user can leave reviews for movies
# user:reviews is a one to many relationship,
# movie:reviews is a one to many relationship,
# movie:user is a many to many relationship
type User
  @table(name: "Users", singular: "user", plural: "users", key: ["id"]) {
  id: UUID! @col(name: "user_id") @default(expr: "uuidV4()")
  auth: String @col(name: "user_auth") @default(expr: "auth.uid")
  username: String! @col(name: "username", dataType: "varchar(30)")
  # The following are generated from the @ref in the Review table
  # reviews_on_user
  # movies_via_Review
}
# Reviews
type Review @table(name: "Reviews", key: ["movie", "user"]) {
  id: UUID! @col(name: "review_id") @default(expr: "uuidV4()")
  user: User! @ref
  movie: Movie! @ref
  rating: Int
  reviewText: String
  reviewDate: Date! @default(expr: "request.time")
}

שאילתות מסוג 'רבים לאחד'

עכשיו נבחן שאילתה עם כינוי כדי להמחיש את תחביר _via_.

query UserMoviePreferences($username: String!) @auth(level: USER) {
  users(where: { username: { eq: $username } }) {
    likedMovies: movies_via_review(where: { rating: { ge: 4 } }) {
      title
      genre
      description
    }
    dislikedMovies: movies_via_review(where: { rating: { le: 2 } }) {
      title
      genre
      description
    }
  }
}

אחד על אחד

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

# Movies
type Movie
  @table(name: "Movies", singular: "movie", plural: "movies", key: ["id"]) {
  id: UUID! @col(name: "movie_id") @default(expr: "uuidV4()")
  title: String!
  releaseYear: Int @col(name: "release_year")
  genre: String
  rating: Int @col(name: "rating")
  description: String @col(name: "description")
  tags: [String] @col(name: "tags")
}
# Movie Metadata
# Movie - MovieMetadata is a one-to-one relationship
type MovieMetadata
  @table(
    name: "MovieMetadata"
  ) {
  # @ref creates a field in the current table (MovieMetadata) that holds the primary key of the referenced type
  # In this case, @ref(fields: "id") is implied
  movie: Movie! @ref
  # movieId: UUID <- this is created by the above @ref
  director: String @col(name: "director")
}


extend type MovieMetadata {
  movieId: UUID! # matches primary key of referenced type
...
}

extend type Movie {
  movieMetadata: MovieMetadata # can only be non-nullable on ref side
  # conflict-free name, always generated
  movieMetadatas_on_movie: MovieMetadata
}

שאילתות ליחס אחד לאחד

אפשר לשלוח שאילתות באמצעות תחביר _on_.

# One to one
query GetMovieMetadata($id: UUID!) @auth(level: PUBLIC) {
  movie(id: $id) {
    movieMetadatas_on_movie {
      director
    }
  }
}

רבים לרבים

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

# MovieActors Join Table Definition
type MovieActors @table(
  key: ["movie", "actor"] # join key triggers many-to-many generation
) {
  movie: Movie!
  actor: Actor!
}

# generated extensions for the MovieActors join table
extend type MovieActors {
  movieId: UUID!
  actorId: UUID!
}

# Extensions for Actor and Movie to handle many-to-many relationships
extend type Movie {
  movieActors: [MovieActors!]! # standard many-to-one relation to join table
  actors: [Actor!]! # many-to-many via join table

  movieActors_on_actor: [MovieActors!]!
  # since MovieActors joins distinct types, type name alone is sufficiently precise
  actors_via_MovieActors: [Actor!]!
}

extend type Actor {
  movieActors: [MovieActors!]! # standard many-to-one relation to join table
  movies: [Movie!]! # many-to-many via join table

  movieActors_on_movie: [MovieActors!]!
  movies_via_MovieActors: [Movie!]!
}

שאילתות ליחס 'רבים לרבים'

נבחן שאילתה עם כינוי כדי להמחיש את התחביר של _via_.

query GetMovieCast($movieId: UUID!, $actorId: UUID!) @auth(level: PUBLIC) {
  movie(id: $movieId) {
    mainActors: actors_via_MovieActor(where: { role: { eq: "main" } }) {
      name
    }
    supportingActors: actors_via_MovieActor(
      where: { role: { eq: "supporting" } }
    ) {
      name
    }
  }
  actor(id: $actorId) {
    mainRoles: movies_via_MovieActor(where: { role: { eq: "main" } }) {
      title
    }
    supportingRoles: movies_via_MovieActor(
      where: { role: { eq: "supporting" } }
    ) {
      title
    }
  }
}

טיפ: הקבוצה המלאה של תוספי השפה של GraphQL עבור Data Connect מפורטת במדריך העזרה של השפה.

מוטציות למסד הנתונים של ביקורות על סרטים

כפי שצוין, כשמגדירים טבלה בסכימה, Data Connect יוצר מוטציות סמויות בסיסיות לכל טבלה.

type Movie @table { ... }

extend type Mutation {
  # Insert a row into the movie table.
  movie_insert(...): Movie_Key!
  # Upsert a row into movie."
  movie_upsert(...): Movie_Key!
  # Update a row in Movie. Returns null if a row with the specified id/key does not exist
  movie_update(...): Movie_Key
  # Update rows based on a filter in Movie.
  movie_updateMany(...): Int!
  # Delete a single row in Movie. Returns null if a row with the specified id/key does not exist
  movie_delete(...): Movie_Key
  # Delete rows based on a filter in Movie.
  movie_deleteMany(...): Int!
}

בעזרתם תוכלו להטמיע מקרים מורכבים יותר ויותר של פעולות CRUD. צריך לומר את זה חמש פעמים מהר!

טיפ: אתם יכולים להשתמש ב-Gemini ב-Firebase כדי ליצור ולבצע מוטציות של GraphQL במסוף Firebase. מידע נוסף זמין במאמר שימוש בעזרה של AI לשאילתות ולמוטציות.

ההנחיה @transaction

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

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

מוטציות ללא @transaction מריצות כל שדה ברמה הבסיסית ברצף, אחד אחרי השני. השגיאות מופיעות כשגיאות שדה חלקיות, אבל לא מופיעות ההשפעות של ההפעלות הבאות.

הערה: בשלב הזה אי אפשר להוסיף את ההנחיה @transaction לשאילתות. לא ניתן לקבל שגיאה חלקית בשאילתות. לא מובטח שנתוני התשובה יהיו קובץ snapshot עקבי.

יצירה

נתחיל ביצירה בסיסית.

# Create a movie based on user input
mutation CreateMovie($title: String!, $releaseYear: Int!, $genre: String!, $rating: Int!) {
  movie_insert(data: {
    title: $title
    releaseYear: $releaseYear
    genre: $genre
    rating: $rating
  })
}

# Create a movie with default values
mutation CreateMovie2 {
  movie_insert(data: {
    title: "Sherlock Holmes"
    releaseYear: 2009
    genre: "Mystery"
    rating: 5
  })
}

או הוספה ועדכון (upsert).

# Movie upsert using combination of variables and literals
mutation UpsertMovie($title: String!) {
  movie_upsert(data: {
    title: $title
    releaseYear: 2009
    genre: "Mystery"
    rating: 5
    genre: "Mystery/Thriller"
  })
}

ביצוע עדכונים

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

mutation UpdateMovie(
  $id: UUID!,
  $genre: String!,
  $rating: Int!,
  $description: String!
) {
  movie_update(id: $id, data: {
    genre: $genre
    rating: $rating
    description: $description
  })
}

# Multiple updates (increase all ratings of a genre)
mutation IncreaseRatingForGenre($genre: String!, $ratingIncrement: Int!) {
  movie_updateMany(
    where: { genre: { eq: $genre } },
    update: { rating: { inc: $ratingIncrement } }
  )
}

ביצוע מחיקה

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

# Delete by key
mutation DeleteMovie($id: UUID!) {
  movie_delete(id: $id)
}

כאן אפשר להשתמש ב-_deleteMany.

# Multiple deletes
mutation DeleteUnpopularMovies($minRating: Int!) {
  movie_deleteMany(where: { rating: { le: $minRating } })
}

כתיבת מוטציות ביחסים

איך משתמשים בטרנספורמציה המשתמעת _upsert ביחס?

# Create or update a one to one relation
mutation MovieMetadataUpsert($movieId: UUID!, $director: String!) {
  movieMetadata_upsert(
    data: { movie: { id: $movieId }, director: $director }
  )
}

טיפ: הקבוצה המלאה של תוספי השפה של GraphQL עבור Data Connect מפורטת במדריך העזרה של השפה.

שאילתות לחיפוש נתוני הרשאה

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

התכונה הזו תומכת באפשרויות הבאות:

• ההוראה @check, שמאפשרת להעריך את התוכן של שדות, ועל סמך תוצאות ההערכה:
  • ממשיכים בפעולות היצירה, העדכון והמחיקה שהוגדרו על ידי המוטציה
  • שימוש בערכים שהשאילתה מחזירה ללקוחות כדי לבצע לוגיקה שונה בלקוחות
• ההוראה @redact, שמאפשרת להשמיט תוצאות של שאילתות מתוצאות של פרוטוקולים ברשת.

התכונות האלה שימושיות בתהליכי הרשאה.

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

הערה: הסכימה הזו לא מייצגת את ה-DDL או את הטרנספורמציה של הסכימה Data Connect. הוא מופיע למטרות המחשה בלבד.

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

מה השלב הבא?

• איך שומרים על אבטחת השאילתות והמוטציות באמצעות הרשאה ואימות
• מידע נוסף על קריאה של השאילתות והמוטציות מ-web SDK, מ-Android SDK, מ-iOS SDK ומ-Flutter SDK שנוצרו באופן אוטומטי.