From 824622d69024c569af9475e1d8ee3d4f56cd2d05 Mon Sep 17 00:00:00 2001
From: Chris Bonifacio <christopher.bonifacio@gmail.com>
Date: Wed, 6 Dec 2023 17:39:07 -0500
Subject: [PATCH] Cbonif/add split schema section (#6619)

---
 .../graphqlapi/data-modeling/index.mdx        | 66 +++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/src/pages/[platform]/build-a-backend/graphqlapi/data-modeling/index.mdx b/src/pages/[platform]/build-a-backend/graphqlapi/data-modeling/index.mdx
index 2281d260390..d39ac2764cc 100644
--- a/src/pages/[platform]/build-a-backend/graphqlapi/data-modeling/index.mdx
+++ b/src/pages/[platform]/build-a-backend/graphqlapi/data-modeling/index.mdx
@@ -1032,6 +1032,72 @@ type Customer @model {
 }
 ```
 
+### Split GraphQL files
+
+<Callout info>
+Amplify Studio does not support splitting GraphQL schemas.
+
+If using Amplify Studio, please follow the [Limitations](https://docs.amplify.aws/javascript/tools/console/data/data-model/#split-graphql-files) section of the Data Modeling documentation for Amplify Studio.
+</Callout>
+
+AWS Amplify supports splitting your GraphQL schema into separate `.graphql` files.
+
+You can start by creating a `amplify/backend/api/<api-name>/schema/` directory. As an example, you might split up the schema for a blog site by creating `Blog.graphql`, `Post.graphql`, and `Comment.graphql` files.
+
+You can then run `amplify api gql-compile` and the output build schema will include all the types declared across your schema files.
+
+As your project grows, you may want to organize your custom queries, mutations, and subscriptions depending on the size and maintenance requirements of your project. You can either consolidate  all of them into one file or colocate them with their corresponding models.
+
+**Using a Single `Query.graphql` File**
+
+This method involves consolidating all queries into a single `Query.graphql` file. It is useful for smaller projects or when you want to keep all queries in one place.
+
+1. In the `amplify/backend/api/<api-name>/schema/` directory, create a file named `Query.graphql`.
+
+2. Copy all query type definitions from your multiple schema files into the `Query.graphql` file.
+
+3. Make sure all your queries are properly formatted and enclosed within a single `type Query { ... }` block.
+
+**Using the `extend` Keyword**
+
+Declaring a `Query` type in separate schema files will result in schema validation errors similar to the following when running `amplify api gql-compile`:
+
+```sh
+🛑 Schema validation failed.
+
+There can be only one type named "Query".
+```
+
+Amplify GraphQL schemas support the `extend` keyword, which allows you to extend types with additional fields. In this case, it also allows you to split your custom queries, mutations, and subscriptions into multiple files. This may be more ideal for larger, more complex projects.
+
+1. Organize your GraphQL schema into multiple files as per your project's architecture.
+
+2. In one of the files (e.g., `schema1.graphql`), declare your type normally:
+
+```graphql
+type Query {
+  # initial custom queries
+}
+```
+
+3. In other schema files (e.g., `schema2.graphql`), use the `extend` keyword to add to the type:
+
+```graphql
+extend type Query {
+  # additional custom queries
+}
+```
+<Callout info>
+The order in which the Query types are extended does not affect the compilation of separate schema files.
+</Callout>
+
+<Callout info>
+Declaring custom Query, Mutation, and/or Subscription with the same field names in another schema file will result in schema validation errors similar to the following:
+
+`🛑 Object type extension 'Query' cannot redeclare field getBlogById`
+</Callout>
+
+
 ## How it works
 
 ### Model directive