chore(api): swift graphQL relational models code snippets

Author: lawmicha

src/pages/[platform]/build-a-backend/graphqlapi/relational-models/index.mdx

@@ -4,7 +4,10 @@ export const meta = {
   title: 'Relational models',
   description:
     'Learn more about how API (GraphQL) handles relationships between Models, such as "has one", "has many", "belongs to".',
-  platforms: ['android']
+  platforms: [
+    'android',
+    'swift'
+    ]
 };
 
 export const getStaticPaths = async () => {
@@ -20,7 +23,7 @@ export function getStaticProps(context) {
   };
 }
 
-<InlineFilter filters={["android"]}>
+<InlineFilter filters={["android", "swift"]}>
 
 API (GraphQL) has the capability to handle relationships between Models, such as _has one_, _has many_, and _belongs to_. In Amplify GraphQL APIs, this is done with the `@hasOne`, `@hasMany` and `@belongsTo` directives as defined in the [GraphQL data modeling documentation](/[platform]/build-a-backend/graphqlapi/data-modeling/).
 
@@ -44,6 +47,20 @@ If you already have relational models in your project, you must re-run `amplify
 
 </InlineFilter>
 
+<InlineFilter filters={["swift"]}>
+
+- Amplify CLI v10.8.0
+- Amplify Library for Swift v2.4.0
+- This guide uses updated model types generated by the Amplify CLI. To follow this guide, locate `"generatemodelsforlazyloadandcustomselectionset"` in `{project-directory}/amplify/cli.json` and set the value to `true`.
+
+<Callout>
+
+If you already have relational models in your project, you must re-run `amplify codegen models` after updating the feature flag. After the models have been updated, breaking changes will need to be addressed because some relationships have changed to `async`. Follow the rest of the guide on this page information on how to use the new lazy supported models.
+
+</Callout>
+
+</InlineFilter>
+
 ## Create a GraphQL schema with relationships between models
 
 For the following example, let's add a Post and Comment model to the [schema](/[platform]/build-a-backend/graphqlapi/set-up-graphql-api/#creating-your-first-api-and-database-table):
@@ -157,6 +174,37 @@ try {
 
 </InlineFilter>
 
+<InlineFilter filters={["swift"]}>
+
+<Block>
+
+```swift
+do {
+    let post = Post(title: "My post with comments",
+                    rating: 10)
+    let comment = Comment(content: "Loving Amplify API!",
+                            post: post) // Directly pass in the post instance
+    
+    let createPostResult = try await Amplify.API.mutate(request: .create(post))
+    guard case .success = createPostResult else {
+        print("API response: \(createPostResult)")
+        return
+    }
+    print("Post created.")
+    let createCommentResult = try await Amplify.API.mutate(request: .create(comment))
+    guard case .success = createCommentResult else {
+        print("API response: \(createCommentResult)")
+        return
+    }
+    print("Comment created.")
+} catch {
+    print("Create post or comment failed", error)
+}
+```
+
+</Block>
+</InlineFilter>
+
 ## Querying relationships
 
 This example demonstrates an initial load of a Post with a subsequent fetch to load a page of comments for the post.
@@ -439,6 +487,32 @@ suspend fun getCommentsForPost(post: Post) {
 
 </InlineFilter>
 
+<InlineFilter filters={["swift"]}>
+
+<Block>
+
+```swift
+do {
+    let queryPostResult = try await Amplify.API.query(request: .get(Post.self, byIdentifier: "123"))
+    guard case .success(let queriedPostOptional) = queryPostResult,
+            let queriedPost = queriedPostOptional,
+            let comments = queriedPost.comments else {
+        print("API response: \(queryPostResult)")
+        return
+    }
+    try await comments.fetch()
+    print("Fetched \(comments.count) comments")
+} catch {
+    print("Failed to query post or fetch comments", error)
+}
+```
+
+</Block>
+
+Always call `fetch()` to load or retrieve the comments. If the comments were loaded as part of the query, it will return immediately. See [Customizing Query Depth](#customizing-query-depth-with-custom-selection-sets) to learn how to eagerly load connected relationships.
+
+</InlineFilter>
+
 ## Deleting relationships
 
 When you delete a parent object in a one-to-many relationship, the children will not be removed. Delete the children before deleting the parent to prevent orphaned data.
@@ -502,6 +576,33 @@ try {
 
 </InlineFilter>
 
+<InlineFilter filters={["swift"]}>
+
+<Block>
+
+```swift
+do {
+    let deleteCommentResult = try await Amplify.API.mutate(request: .delete(comment))
+    guard case .success = deleteCommentResult else {
+        print("API response: \(deleteCommentResult)")
+        return
+    }
+    // Once all comments for a post are deleted, the post can be deleted.
+    let deletePostResult = try await Amplify.API.mutate(request: .delete(post))
+    guard case .success = deletePostResult else {
+        print("API response: \(deletePostResult)")
+        return
+    }
+    print("Deleted comment and post")
+} catch {
+    print("Failed to delete comment or post", error)
+}
+```
+
+</Block>
+
+</InlineFilter>
+
 ## Many-to-many relationships
 
 For many-to-many relationships, you can use the `@manyToMany` directive and specify a `relationName`. Under the hood, Amplify creates a join table and a one-to-many relationship from both models.
@@ -645,6 +746,40 @@ This example illustrates the complexity of working with multiple sequential crea
 
 </InlineFilter>
 
+<InlineFilter filters={["swift"]}>
+
+<Block>
+
+```swift
+do {
+    let post = Post(title: "My Post", rating: 10)
+    let user = User(username: "User")
+    let postEditor = PostEditor(post: post, user: user)
+    
+    let createPostResult = try await Amplify.API.mutate(request: .create(post))
+    guard case .success = createPostResult else {
+        print("API response: \(createPostResult)")
+        return
+    }
+    let createUserResult = try await Amplify.API.mutate(request: .create(user))
+    guard case .success = createUserResult else {
+        print("API response: \(createUserResult)")
+        return
+    }
+    let createPostEditorResult = try await Amplify.API.mutate(request: .create(postEditor))
+    guard case .success = createPostEditorResult else {
+        print("API response: \(createPostEditorResult)")
+        return
+    }
+} catch {
+    print("Failed to create post, user, or post editor", error)
+}
+```
+
+</Block>
+
+</InlineFilter>
+
 ## Customizing query depth with custom selection sets
 
 You can perform a nested query through one network request, by specifying which connected models to include. This is achieved by using the optional `includes` parameter for a GraphQL request.
@@ -726,6 +861,36 @@ This will populate the selection set of the post in the GraphQL document which i
 
 </InlineFilter>
 
+<InlineFilter filters={["swift"]}>
+
+<Block>
+
+```swift
+do {
+    let queryCommentResult = try await Amplify.API.query(request:
+            .get(Comment.self,
+                 byIdentifier: "c1",
+                 includes: { comment in
+        [comment.post]
+    }))
+    guard case .success(let queriedCommentOptional) = queryCommentResult,
+            let queriedComment = queriedCommentOptional,
+            let loadedPost = try await queriedComment.post else {
+        print("API response: \(queryCommentResult)")
+        return
+    }
+    
+    print("Post: ", loadedPost)
+} catch {
+    print("Failed to query comment with post", error)
+}
+```
+This will populate the selection set of the post in the GraphQL document which indicates to your GraphQL service to retrieve the post model as part of the operation. Once the comment is loaded, the post model is immediately available in-memory without requiring an additional network request.
+
+</Block>
+
+</InlineFilter>
+
 Query for the `Post` and the first page of comments for the post:
 
 <InlineFilter filters={["android"]}>
@@ -836,11 +1001,11 @@ This query fetches a comment, eagerly loading the parent post and first page of
 
 ```java
 ModelQuery.get<PostEditor, PostEditorPath>(PostEditor::class.java, "pe1") { postEditorPath ->
-    includes(postEditorPath.post, postEditorPath.comments)
+    includes(postEditorPath.post, postEditorPath.user)
 }
 ```
 
-This query fetches a postEditor and eagerly loads its post and comments
+This query fetches a postEditor and eagerly loads its post and user
 
 </Block>
 <Block name="Kotlin">
@@ -850,15 +1015,78 @@ ModelQuery.get<PostEditor, PostEditorPath>(
     PostEditor::class.java,
     "pe1"
 ) { postEditorPath ->
-    includes(postEditorPath.post, postEditorPath.comments)
+    includes(postEditorPath.post, postEditorPath.user)
 }
 ```
 
-This query fetches a postEditor and eagerly loads its post and comments
+This query fetches a postEditor and eagerly loads its post and user
 
 </Block>
 </BlockSwitcher>
 
 </InlineFilter>
 
+<InlineFilter filters={["swift"]}>
+
+<Block>
+
+```swift
+do {
+    let queryPostResult = try await Amplify.API.query(request: 
+            .get(Post.self,
+                 byIdentifier: "p1",
+                 includes: { post in
+        [post.comments]
+    }))
+    guard case .success(let queriedPostOptional) = queryPostResult,
+            let queriedPost = queriedPostOptional,
+            let comments = queriedPost.comments else {
+        print("API response: \(queryPostResult)")
+        return
+    }
+    
+    try await comments.fetch()
+    print("Comments: ", comments)
+} catch {
+    print("Failed to query post with comments", error)
+}
+```
+
+The network request for post includes the comments, eagerly loading the first page of comments in a single network call.
+
+</Block>
+
+You can generate complex nested queries through the includes parameter.
+
+<Block>
+
+```swift
+let queryCommentResult = try await Amplify.API.query(request: 
+    .get(Comment.self,
+         byIdentifier: "p1",
+         includes: { comment in
+    [comment.post.comments]
+}))
+```
+
+This query fetches a comment, eagerly loading the parent post and first page of comments for the post.
+
+</Block>
+
+<Block>
+
+```swift
+let queryCommentResult = try await Amplify.API.query(request:
+        .get(PostEditor.self,
+             byIdentifier: "pe1",
+             includes: { postEditor in
+    [postEditor.post, postEditor.user]
+}))
+```
+
+This query fetches a postEditor and eagerly loads its post and user
+
+</Block>
+</InlineFilter>
+
 </InlineFilter>