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

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

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

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

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

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

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

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

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

טבלת סרטים

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

• @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
}

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

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

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

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

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

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

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

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

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

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

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 {
  id: UUID! @default(expr: "uuidV4()")
  name: String! @col(dataType: "varchar(30)")
}
# 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
}

משתמש

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

# 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 תומך בסוגי הנתונים הסקלריים הבאים, עם הקצאות לסוגים של PostgreSQL באמצעות @col(dataType:).

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

שימוש בשדות שנוצרו כדי ליצור שאילתות ומוטציות

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

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

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

שמות שדות שנוצרים באופן אוטומטי

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 להרחבת ההתנהגות של שאילתות ומוטציות.

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

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

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

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

• הגדרת סוג 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
  }
}

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

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

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

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

רבים לאחד

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

# User table is keyed by Firebase Auth UID.
type User @table {
  # `@default(expr: "auth.uid")` sets it to Firebase Auth UID during insert and upsert.
  id: String! @default(expr: "auth.uid")
  username: String! @col(dataType: "varchar(50)")
  # The `user: User!` field in the Review table generates the following one-to-many query field.
  #  reviews_on_user: [Review!]!
  # The `Review` join table the following many-to-many query field.
  #  movies_via_Review: [Movie!]!
}

# Reviews is a join table tween User and Movie.
# It has a composite primary keys `userUid` and `movieId`.
# A user can leave reviews for many movies. A movie can have reviews from many users.
# User  <-> Review is a one-to-many relationship
# Movie <-> Review is a one-to-many relationship
# Movie <-> User is a many-to-many relationship
type Review @table(name: "Reviews", key: ["movie", "user"]) {
  user: User!
  # The user field adds the following foreign key field. Feel free to uncomment and customize it.
  #  userUid: String!
  movie: Movie!
  # The movie field adds the following foreign key field. Feel free to uncomment and customize it.
  #  movieId: UUID!
  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
    }
    dislikedMovies: movies_via_Review(where: { rating: { le: 2 } }) {
      title
      genre
    }
  }
}

אחד על אחד

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

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

שאילתות צבירת נתונים

מהם נתונים מצטברים ולמה כדאי להשתמש בהם?

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

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

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

• ביצועים מהירים יותר של האפליקציה (כי אין צורך לבצע חישובים בצד הלקוח)
• הפחתת עלויות תעבורת הנתונים היוצאת (כי שולחים רק את התוצאות המצטברות במקום את כל הקלט)
• אבטחה משופרת (כי אפשר לתת ללקוחות גישה לנתונים מצטברים במקום לכל קבוצת הנתונים)

דוגמה לסכימה של צבירה

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

  type Product @table {
    name: String!
    manufacturer: String!
    quantityInStock: Int!
    price: Float!
    expirationDate: Date
  }

צבירה פשוטה

_count לכל השדות

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

query CountProducts {
  products {
    _count
  }
}

{
  "products": [
    {
    "_count": 5
    }
  ]
}

לכל השדות יש שדה <field>_count, שסופר את מספר השורות שיש להן ערך שאינו null בשדה הזה.

query CountProductsWithExpirationDate {
  products {
    expirationDate_count
  }
}

{
  "products": [
    {
    "expirationDate_count": 3
    }
  ]
}

_min,‏ _max,‏ _sum ו-_avg לשדות מספריים

גם לשדות מספריים (int,‏ float,‏ int64) יש את הערכים <field>_min,‏ <field>_max,‏ <field>_sum ו-<field>_avg.

query NumericAggregates {
  products {
  quantityInStock_max
  price_min
  price_avg
  quantityInStock_sum
  }
}

{
  "products": [
    {
    "quantityInStock_max": 20,
    "price_min": 1.99,
    "price_avg": 3.6566666666666666,
    "quantityInStock_sum": 35
    }
  ]
}

_min ו-_max לתאריכים ולחותמות זמן

השדות 'תאריך' ו'חותמת זמן' מכילים את הערכים <field>_min ו-<field>_max.

query DateAndTimeAggregates {
  products {
  expirationDate_max
  expirationDate_min
  }
}

{
  "products": [
    {
    "expirationDate_max": "2024-03-01",
    "expirationDate_min": "2024-01-01"
    }
  ]
}

ייחודי

הארגומנט distinct מאפשר לקבל את כל הערכים הייחודיים של שדה (או שילוב של שדות). לדוגמה:

query ListDistinctManufacturers {
  products(distinct: true) {
    manufacturer
  }
}

{
  "products": [
    { "manufacturer": "Acme" },
    { "manufacturer": "Beta" }
  ]
}

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

query CountDistinctManufacturers {
  products {
    manufacturer_count(distinct: true)
  }
}

{
  "products": [
    {
    "manufacturer_count": 2
    }
  ]
}

צבירה של נתונים מקובצים

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

query MostExpensiveProductByManufacturer {
  products {
  manufacturer
  price_max
  }
}

{
  "products": [
    { "manufacturer": "Acme", "price_max": 2.99 },
    { "manufacturer": "Beta", "price_max": 5.99 }
  ]
}

having ו-where עם צבירה מקובצת

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

• having מאפשר לסנן קבוצות לפי השדות המצטברים שלהן

• where מאפשר לסנן את השורות על סמך שדות לא מצטברים.

query FilteredMostExpensiveProductByManufacturer {
  products(having: {price_max: {ge: 2.99}}) {
  manufacturer
  price_max
  }
}

{
  "products": [
    { "manufacturer": "Acme", "price_max": 2.99 },
    { "manufacturer": "Beta", "price_max": 5.99 }
  ]
}

צבירה בין טבלאות

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

  type Product @table {
    name: String!
    manufacturer: Manufacturer!
    quantityInStock: Int!
    price: Float!
    expirationDate: Date
  }

  type Manufacturer @table {
    name: String!
    headquartersCountry: String!
  }

עכשיו אפשר להשתמש בשדות צבירה כדי לבצע פעולות כמו חיפוש מספר המוצרים שהיצרן מייצא:

query GetProductCount($id: UUID) {
  manufacturers {
    name
    products_on_manufacturer {
      _count
    }
  }
}

{
  "manufacturers": [
    { "name": "Acme", "products_on_manufacturer": { "_count": 2 } },
    { "name": "Beta", "products_on_manufacturer": { "_count": 1 } }
  ]
}

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

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

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. צריך לומר את זה חמש פעמים מהר!

יצירה

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

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

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

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

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

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

כדי לבצע כמה עדכונים, משתמשים בשדה movie_updateMany.

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

שימוש בפעולות הוספה, הפחתה, צירוף והוספה בתחילת שורה באמצעות _update

בעוד שבמוטציות _update ו-_updateMany אפשר להגדיר ערכים ב-data: באופן מפורש, לרוב עדיף להחיל אופרטור כמו increment כדי לעדכן ערכים.

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

mutation UpdateMovie(
  $id: UUID!,
  $ratingIncrement: Int!
) {
  movie_update(id: $id, data: {
    rating_update: {
      inc: $ratingIncrement
    }
  })
}

Data Connect תומך באופרטורים הבאים לעדכוני שדות:

• inc כדי להגדיל את סוגי הנתונים Int, Int64, Float, Date ו-Timestamp
• dec כדי להקטין את סוגי הנתונים Int, ‏ Int64, ‏ Float, ‏ Date ו-Timestamp

ברשימות, אפשר גם לעדכן ערכים ספציפיים או רשימות של ערכים באמצעות:

• add כדי לצרף פריטים לסוגים של רשימות, אם הם עדיין לא נמצאים בהן, מלבד רשימות Vector
• remove כדי להסיר את כל הפריטים, אם קיימים, מסוגים של רשימות, מלבד רשימות Vector
• append כדי לצרף פריטים לסוגי רשימות, מלבד רשימות Vector
• prepend כדי להוסיף פריטים לתחילת סוגי רשימות, מלבד רשימות וקטורים

ביצוע מחיקה

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

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

לאפשר ל-Data Connect לספק ערכים באמצעות תחביר field_expr

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

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

כשמטמיעים מוטציות, משתמשים בתחביר field_expr כדי להפעיל עדכונים שנוצרים על ידי השרת או לגשת לנתונים מהבקשות. לדוגמה, כדי להעביר את ההרשאה uid ששמורה בבקשה לפעולה _upsert, מעבירים את "auth.uid" בשדה userId_expr.

# Add a movie to the user's favorites list
mutation AddFavoritedMovie($movieId: UUID!) @auth(level: USER) {
  favorite_movie_upsert(data: { userId_expr: "auth.uid", movieId: $movieId })
}

# Remove a movie from the user's favorites list
mutation DeleteFavoritedMovie($movieId: UUID!) @auth(level: USER) {
  favorite_movie_delete(key: { userId_expr: "auth.uid", movieId: $movieId })
}

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

mutation CreateTodoListWithFirstItem(
  $listName: String!
) @transaction {
  # Step 1
  todoList_insert(data: {
    id_expr: "uuidV4()", # <-- auto-generated. Or a column-level @default on `type TodoList` will also work
    name: $listName,
  })
}

מידע נוסף זמין במאמר בנושא scalars reference._Expr

פעולות בכמה שלבים

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

בעזרת Data Connect תוכלו לבצע לוגיקה של כמה שלבים במונטיפיקציות, באמצעות תמיכה באפשרויות הבאות:

• מספר שדות כתיבה

• מספר שדות קריאה במונטיפיקציות (באמצעות מילת המפתח של השדה query).

• ההוראה @transaction, שמספקת תמיכה בטרנזקציות שמוכרת ממסדי נתונים רלציוניים.

• ההוראה @check, שמאפשרת להעריך את התוכן של קריאות באמצעות ביטויים ב-CEL, ועל סמך תוצאות ההערכה הזו:

  • המשך בפעולות יצירה, עדכון ומחיקה שמוגדרות על ידי מוטציה
  • המשך להחזרת התוצאות של שדה שאילתה
  • שימוש בהודעות חזרה כדי לבצע לוגיקה מתאימה בקוד הלקוח

• ההוראה @redact, שמאפשרת להשמיט תוצאות של שדות שאילתה מתוצאות של פרוטוקולים ברשת.

• קישור response של CEL, שמאחסן את התוצאות המצטברות של כל המוטציות והשאילתות שבוצעו בפעולה מורכבת שמחולקת לכמה שלבים. אפשר לגשת לקישור response:

  • בהנחיות @check, דרך הארגומנט expr:
  • עם ערכי שרת, באמצעות תחביר field_expr

ההוראה @transaction

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

ההנחיה @transaction אוכפת שטרנספורמציה – עם שדה כתיבה יחיד (למשל, _insert או _update) או עם כמה שדות כתיבה – תמיד תרוץ בעסקה של מסד נתונים.

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

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

ההוראות @check ו-@redact

ההנחיה @check מאמתת ששדות מסוימים נמצאים בתוצאות של השאילתה. ביטוי של Common Expression Language ‏ (CEL) משמש לבדיקה של ערכי השדות. התנהגות ברירת המחדל של ההנחיה היא לבדוק אם יש צמתים שהערך שלהם הוא null או [] (רשימות ריקות) ולדחות אותם.

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

שימוש ב-@check, ב-@check(message:) וב-@redact

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

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

query GetMovieEditors($movieId: UUID!) @auth(level: USER) {
  moviePermission(key: { movieId: $movieId, userId_expr: "auth.uid" }) @redact {
    role @check(expr: "this == 'admin'", message: "You must be an admin to view all editors of a movie.")
  }
  moviePermissions(where: { movieId: { eq: $movieId }, role: { eq: "editor" } }) {
    user {
      id
      username
    }
  }
}

למידע נוסף על ההנחיות @check ו-@redact בבדיקות ההרשאה, קראו את הסקירה על חיפוש נתוני הרשאה.

שימוש ב-@check לאימות מפתחות

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

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

# Delete by key, error if not found
mutation MustDeleteMovie($id: UUID!) @transaction {
  movie_delete(id: $id) @check(expr: "this != null", message: "Movie not found, therefore nothing is deleted")
}

שימוש בקישור response כדי לשרשר מוטציות בכמה שלבים

הגישה הבסיסית ליצירת רשומות קשורות, למשל רשומה חדשה של Movie ורשומת MovieMetadata משויכת, היא:

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

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

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

שימוש ב-response כדי להגדיר שדות עם ערכי שרת

במוּטאציה הבאה של רשימת המשימות:

• קישור response מייצג את אובייקט התגובה החלקי עד כה, שכולל את כל שדות המוטציה ברמה העליונה לפני השדה הנוכחי.
• אנחנו ניגשים לתוצאות של הפעולה הראשונית todoList_insert, שמחזירה את השדה id (מפתח), מאוחר יותר ב-response.todoList_insert.id כדי שנוכל להוסיף מיד פריט חדש ברשימת המשימות.

mutation CreateTodoListWithFirstItem(
  $listName: String!,
  $itemContent: String!
) @transaction {
  # Sub-step 1:
  todoList_insert(data: {
    id_expr: "uuidV4()", # <-- auto-generated. Or a column-level @default on `type TodoList` will also work
    name: $listName,
  })
  # Sub-step 2:
  todo_insert(data: {
    listId_expr: "response.todoList_insert.id" # <-- Grab the newly generated ID from the partial response so far.
    content: $itemContent,
  })
}

שימוש ב-response כדי לאמת שדות באמצעות @check

response זמין גם ב-@check(expr: "..."), כך שאפשר להשתמש בו כדי ליצור לוגיקה מורכבת עוד יותר בצד השרת. בשילוב עם query { … } שלבים במוטציות, אפשר להשיג הרבה יותר בלי נסיעות הלוך ושוב נוספות בין שרת ללקוח.

בדוגמה הבאה, חשוב לשים לב: ל-@check כבר יש גישה ל-response.query כי @check תמיד פועל אחרי השלב שאליו הוא מצורף.

mutation CreateTodoInNamedList(
  $listName: String!,
  $itemContent: String!
) @transaction {
  # Sub-step 1: Look up List.id by its name
  query
  @check(expr: "response.query.todoLists.size() > 0", message: "No such TodoList with the name!")
  @check(expr: "response.query.todoLists.size() < 2", message: "Ambiguous listName!") {
    todoLists(where: { name: $listName }) {
      id
    }
  }
  # Sub-step 2:
  todo_insert(data: {
    listId_expr: "response.todoLists[0].id" # <-- Now we have the parent list ID to insert to
    content: $itemContent,
  })
}

למידע נוסף על קישור response, ראו חומר העזר של CEL.

הסבר על פעולות מושהות באמצעות @transaction ו-query @check

במוטציות בכמה שלבים יכולות להתרחש שגיאות:

• פעולות במסד הנתונים עשויות להיכשל.
• הלוגיקה של השאילתה @check עשויה לסיים את הפעולות.

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

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

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

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

סכימה מקבילת של 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);

מה השלב הבא?

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