From cf023d950ab4ba63de97f4dde07be5dfdb1816e2 Mon Sep 17 00:00:00 2001
From: Chris Bonifacio <christopher.bonifacio@gmail.com>
Date: Thu, 11 Jul 2024 07:27:14 -0400
Subject: [PATCH] add callout for sql custom query/mutation return types with
 example

---
 .../connect-postgres-mysql-database/index.mdx | 31 ++++++++++++++++++-
 .../index.mdx                                 | 27 ++++++++++++++--
 2 files changed, 55 insertions(+), 3 deletions(-)

diff --git a/src/pages/[platform]/build-a-backend/data/connect-to-existing-data-sources/connect-postgres-mysql-database/index.mdx b/src/pages/[platform]/build-a-backend/data/connect-to-existing-data-sources/connect-postgres-mysql-database/index.mdx
index a720275fa95..5add870e53d 100644
--- a/src/pages/[platform]/build-a-backend/data/connect-to-existing-data-sources/connect-postgres-mysql-database/index.mdx
+++ b/src/pages/[platform]/build-a-backend/data/connect-to-existing-data-sources/connect-postgres-mysql-database/index.mdx
@@ -327,6 +327,34 @@ VALUES (:name, :address, ST_SetSRID(ST_MakePoint(:long, :lat), 4326))
 </Block>
 </BlockSwitcher>
 
+<Callout info>
+The return type for custom queries and mutations expecting to return row data from SQL statements must
+be an array of the corresponding model. This is true even for custom `get` queries, where a single row is expected.
+
+**Example**
+
+```ts
+sqlSchema.addToSchema({
+  getPostBySlug: a
+    .query()
+    .arguments({
+      slug: a.string().required(),
+    })
+    // highlight-start
+    .returns(a.ref("Post").array())
+    // highlight-end
+    .handler(
+      a.handler.inlineSql(`
+      SELECT id, title, slug, content, created_at, updated_at
+      FROM posts
+      WHERE slug = :slug;
+      `)
+    )
+    .authorization((allow) => [allow.guest()]),
+});
+```
+</Callout>
+
 ## How does it work?
 
 The Amplify uses AWS Lambda functions to enable features like querying data from your database. To work properly, these Lambda functions need access to common logic and dependencies.
@@ -418,4 +446,5 @@ To return the actual SQL error instead of a generic error from underlying API re
 
 ### My SQL table doesn't get generated when running `npx ampx generate schema-from-database`
 
-This is likely because the table doesn't have a designated primary key. A primary key is required for `npx ampx generate schema-from-database` to infer the table structure and create a create, read, update, and delete API.
+This is likely because the table doesn't have a designated primary key. A primary key is required for `npx ampx generate schema-from-database` to infer the table structure and create a create, read, update, and delete API.import ts from 'typescript';
+
diff --git a/src/pages/gen1/[platform]/build-a-backend/graphqlapi/connect-api-to-existing-database/index.mdx b/src/pages/gen1/[platform]/build-a-backend/graphqlapi/connect-api-to-existing-database/index.mdx
index 1a09d114375..7520aa372b5 100644
--- a/src/pages/gen1/[platform]/build-a-backend/graphqlapi/connect-api-to-existing-database/index.mdx
+++ b/src/pages/gen1/[platform]/build-a-backend/graphqlapi/connect-api-to-existing-database/index.mdx
@@ -498,8 +498,31 @@ type Mutation {
 </BlockSwitcher>
 
 <Callout info>
-  The return type for custom queries and mutations expecting row data must
-  be an array of the corresponding model.
+The return type for custom queries and mutations expecting to return row data from SQL statements must
+be an array of the corresponding model. This is true even for custom `get` queries, where a single row is expected.
+
+**Example**
+
+```ts
+sqlSchema.addToSchema({
+  getPostBySlug: a
+    .query()
+    .arguments({
+      slug: a.string().required(),
+    })
+    // highlight-start
+    .returns(a.ref("Post").array())
+    // highlight-end
+    .handler(
+      a.handler.inlineSql(`
+      SELECT id, title, slug, content, created_at, updated_at
+      FROM posts
+      WHERE slug = :slug;
+      `)
+    )
+    .authorization((allow) => [allow.guest()]),
+});
+```
 </Callout>