callout for mysql/postgres custom query return types

src/pages/[platform]/build-a-backend/data/connect-to-existing-data-sources/connect-postgres-mysql-database/index.mdx

@@ -315,6 +315,30 @@ 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
+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;
+    `)
+  )
+```
+</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.
@@ -406,4 +430,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';
+

src/pages/gen1/[platform]/build-a-backend/graphqlapi/connect-api-to-existing-database/index.mdx

@@ -498,8 +498,17 @@ 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**
+
+```graphql title="schema.graphql"
+type Query {
+  getPostBySlug(slug: String!): [Post]
+    @sql(statement: "SELECT * FROM posts WHERE slug = :slug LIMIT 1;")
+    @auth(rules: [{ allow: public }])
+}
+```
 </Callout>