improve FDC initial Schema template (#8160)

templates/init/dataconnect/mutations.gql

@@ -1,36 +1,20 @@
 # # Example mutations for a simple movie app
 
 # # Create a movie based on user input
-# mutation CreateMovie(
-#   $title: String!
-#   $genre: String!
-#   $imageUrl: String!
-# ) @auth(level: USER_EMAIL_VERIFIED) {
-#   movie_insert(
-#     data: {
-#       title: $title
-#       genre: $genre
-#       imageUrl: $imageUrl
-#     }
-#   )
+# mutation CreateMovie($title: String!, $genre: String!, $imageUrl: String!)
+# @auth(level: USER_EMAIL_VERIFIED) {
+#   movie_insert(data: { title: $title, genre: $genre, imageUrl: $imageUrl })
 # }
 
 # # Upsert (update or insert) a user's username based on their auth.uid
 # mutation UpsertUser($username: String!) @auth(level: USER) {
-#   user_upsert(
-#     data: {
-#       id_expr: "auth.uid"
-#       username: $username
-#     }
-#   )
+#   # The "auth.uid" server value ensures that users can only register their own user.
+#   user_upsert(data: { id_expr: "auth.uid", username: $username })
 # }
 
 # # Add a review for a movie
-# mutation AddReview(
-#   $movieId: UUID!
-#   $rating: Int!
-#   $reviewText: String!
-# ) @auth(level: USER) {
+# mutation AddReview($movieId: UUID!, $rating: Int!, $reviewText: String!)
+# @auth(level: USER) {
 #   review_upsert(
 #     data: {
 #       userId_expr: "auth.uid"
@@ -43,8 +27,7 @@
 # }
 
 # # Logged in user can delete their review for a movie
-# mutation DeleteReview(
-#   $movieId: UUID!
-# ) @auth(level: USER) {
+# mutation DeleteReview($movieId: UUID!) @auth(level: USER) {
+#   # The "auth.uid" server value ensures that users can only delete their own reviews.
 #   review_delete(key: { userId_expr: "auth.uid", movieId: $movieId })
 # }

templates/init/dataconnect/queries.gql

@@ -13,19 +13,21 @@
 
 # # List all users, only admins should be able to list all users, so we use NO_ACCESS
 # query ListUsers @auth(level: NO_ACCESS) {
-#   users { id, username }
+#   users {
+#     id
+#     username
+#   }
 # }
 
-# # Logged in user can list all their reviews and movie titles associated with the review 
-# # Since the query requires the uid of the current authenticated user, the auth level is set to USER
+# # Logged in users can list all their reviews and movie titles associated with the review
+# # Since the query uses the uid of the current authenticated user, we set auth level to USER
 # query ListUserReviews @auth(level: USER) {
-#   user(key: {id_expr: "auth.uid"}) {
+#   user(key: { id_expr: "auth.uid" }) {
 #     id
 #     username
 #     # <field>_on_<foreign_key_field> makes it easy to grab info from another table
 #     # Here, we use it to grab all the reviews written by the user.
 #     reviews: reviews_on_user {
-#       id
 #       rating
 #       reviewDate
 #       reviewText
@@ -50,7 +52,6 @@
 #       description
 #     }
 #     reviews: reviews_on_movie {
-#       id
 #       reviewText
 #       reviewDate
 #       rating
@@ -63,16 +64,10 @@
 # }
 
 # # Search for movies, actors, and reviews
-# query SearchMovie(
-#   $titleInput: String
-#   $genre: String
-# ) @auth(level: PUBLIC) {
+# query SearchMovie($titleInput: String, $genre: String) @auth(level: PUBLIC) {
 #   movies(
 #     where: {
-#       _and: [
-#         { genre: { eq: $genre } }
-#         { title: { contains: $titleInput } }
-#       ]
+#       _and: [{ genre: { eq: $genre } }, { title: { contains: $titleInput } }]
 #     }
 #   ) {
 #     id

templates/init/dataconnect/schema.gql

@@ -1,44 +1,51 @@
 # # Example schema for simple movie review app
 
-# # 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
+# # User table is keyed by Firebase Auth UID.
 # type User @table {
-#   id: String! @col(name: "user_auth")
-#   username: String! @col(name: "username", dataType: "varchar(50)")
-#   # The following are generated by the user: User! field in the Review table
-#   # reviews_on_user 
-#   # movies_via_Review
+#   # `@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!]!
 # }
 
-# # Movies
+# # Movie is keyed by a randomly generated UUID.
 # type Movie @table {
-#   # The below parameter values are generated by default with @table, and can be edited manually.
-#   # implies directive `@col(name: "movie_id")`, generating a column name
-#   id: UUID! @default(expr: "uuidV4()")
+#   # If you do not pass a 'key' to `@table`, Data Connect automatically adds the following 'id' column.
+#   # Feel free to uncomment and customize it.
+#   #  id: UUID! @default(expr: "uuidV4()")
 #   title: String!
 #   imageUrl: String!
 #   genre: String
 # }
 
-# # Movie Metadata
-# # Movie - MovieMetadata is a one-to-one relationship
+# # MovieMetadata is a metadata attached to a Movie.
+# # Movie <-> MovieMetadata is a one-to-one relationship
 # type MovieMetadata @table {
-#   # @unique indicates a 1-1 relationship
-#   movie: Movie! @unique 
-#   # movieId: UUID <- this is created by the above reference
+#   # @unique ensures each Movie can only one MovieMetadata.
+#   movie: Movie! @unique
+#   # The movie field adds the following foreign key field. Feel free to uncomment and customize it.
+#   #  movieId: UUID!
 #   rating: Float
 #   releaseYear: Int
 #   description: String
 # }
 
-# # Reviews
+# # Reviews is a join table between 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"]) {
-#   id: UUID! @default(expr: "uuidV4()")
 #   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")