Merge remote-tracking branch 'origin/develop' into apollo-studio-docs

docs/getting_started/configuration.mdx

@@ -15,9 +15,6 @@ Create one of the following files and paste the contents into it.
 
 <Tabs>
 <TabItem value="graphql" label="graphql">
-
-`jsonplaceholder.graphql`
-
 ```graphql showLineNumbers
 schema
   # Specify server configuration: Start tailcall server at 0.0.0.0:8000 and enable GraphiQL playground

docs/guides/apollo-studio.md

@@ -1,47 +1,46 @@
 ---
 title: Apollo Studio
+description: "Learn to enhance your GraphQL server's efficiency by integrating Tailcall with Apollo Studio through our concise guide. Discover how to configure Tailcall to send vital usage metrics to Apollo Studio, enabling advanced performance monitoring and optimization. Whether you're establishing a Monolith graph or improving an existing one, our instructions will facilitate a seamless integration. This guide helps you set up for better insights and also advises on leveraging Apollo Studio's features for a more responsive GraphQL server. Start optimizing today with our straightforward steps, and explore how to access Apollo Studio's free trial for new users."
 ---
 
 This guide illustrates how to configure `tailcall` to send usage metrics to [Apollo Studio](https://studio.apollographql.com).<br/><br/>
 _Note: Before proceeding make sure you have an Apollo Enterprise account. If not, you can get a free 28 days trial by going [here](https://studio.apollographql.com/signup?type=enterprise-trial)._
 
 ## Creating a monolith graph
 
-Before you configure `tailcall`, you will need to create a `Monolith` graph on Apollo Studio.
+1. Before you configure `tailcall`, you will need to create a `Monolith` graph on Apollo Studio.
 
-![home.png](../../static/images/apollo-studio/home.png)
+   ![home.png](../../static/images/apollo-studio/home.png)
 
-- Go to your organization's home page.
-- Click on `Create your first graph`, if this is your first graph or `Create New Graph` if you have existing graphs.
+1. Go to your organization's home page and click on `Create your first graph`, if this is your first graph or `Create New Graph` if you have existing graphs.
 
-![create-graph.png](../../static/images/apollo-studio/create-graph.png)
+   ![create-graph.png](../../static/images/apollo-studio/create-graph.png)
 
-- Change the `Graph title`, `Graph ID` and other fields as desired.
-- Make sure to change `Graph Architecture` to Monolith, since only Monolith graphs are currently supported by `tailcall`.
-- Once you are done, click on `Next`. You'll see the following screen.
+1. Change the `Graph title`, `Graph ID` and other fields as desired and make sure to change `Graph Architecture` to Monolith, assuming `tailcall` is booted in monolith mode.
+1. Once you are done, click on `Next`. You'll see the following screen.
 
-![insert-gql-schema.png](../../static/images/apollo-studio/insert-gql-schema.png)
+   ![insert-gql-schema.png](../../static/images/apollo-studio/insert-gql-schema.png)
 
-- Copy the fields `APOLLO_KEY` and `APOLLO_GRAPH_REF` as they are required by `tailcall` to be able to send the usage metrics.
+1. Copy the fields `APOLLO_KEY` and `APOLLO_GRAPH_REF` as they are required by `tailcall` to be able to send the usage metrics.
 - There are two ways to let Apollo know about your GraphQL schema:
 
-  - Navigate to `Local Introspection`. If you have a deployed instance of your GraphQL server you can put the URL pointing to that in `Endpoint URL`. If not, start a local instance of `tailcall` and put the local url here, similar to how is shown in the image below.<br/>
+  1. Navigate to `Local Introspection`. If you have a deployed instance of your GraphQL server you can put the URL pointing to that in `Endpoint URL`. If not, start a local instance of `tailcall` and put the local url here, similar to how is shown in the image below.<br/>
     _Note: You can start a local instance of tailcall by running `tailcall start <path-to-config>`(click [here](./cli.md) to know more)._
 
   ![local-introspection.png](../../static/images/apollo-studio/local-introspection.png)
 
-  - Or, Navigate to `Local Schema` and insert your schema generated by `tailcall` and click `Upload`.<br/>
+  1. Or, Navigate to `Local Schema` and insert your schema generated by `tailcall` and click `Upload`.<br/>
     _Note: you can get the schema by running `tailcall check --schema <path-to-config>`_(click [here](./cli.md) to know more).
 
 ![local-schema.png](../../static/images/apollo-studio/local-schema.png)
 
-You have now successfully created a Monolith graph in Apollo Studio. The next step is to configure `tailcall` to use the `APOLLO_API_KEY` and `APOLLO_GRAPH_REF`. Follow instructions [here](../operators/telemetry.md).
+You have now created a Monolith graph in Apollo Studio. The next step is to configure `tailcall` to use the `APOLLO_API_KEY` and `APOLLO_GRAPH_REF`. Follow detailed instructions [here](../operators/telemetry.md).
 
-## Check the metrics in Apollo Studio
+## Checking the metrics in Apollo Studio
 
-To see the metrics for your queries follow these instructions:
+To see the metrics for you queries follow these instructions:
 
-- Start `tailcall` with the appropriate configuration for Apollo. Below is an example of what a config may look like.
+1. Start `tailcall` with the appropriate configuration for Apollo (click [here](./cli.md#start) to know more). Below is an example of what a config may look like.
 
 ```graphql
 schema
@@ -72,30 +71,33 @@ type Post {
 }
 ```
 
-- Visit `http://localhost:8000/graphql` and create a query with an appropriate name (below is an example query named `MyQuery`) and run it multiple times to send the metrics to Apollo Studio.<br/>
-  _Note: Naming the query is not required to be able to send the metrics, but it helps to organize the metrics with appropriate names when viewed in Apollo Studio._
+1. Visit `http://localhost:8000/graphql` and create a query with an appropriate name (below is an example query named `MyQuery`) and run it multiple times to send the metrics to Apollo Studio.<br/>
+     _Note: Naming the query is not required to be able to send the metrics, but it helps to organize the metrics with appropriate names when viewed in Apollo Studio._
 
-```graphql
-query MyQuery {
-  posts {
-    id
-    title
-  }
-}
-```
 
-- To see the metrics click on the `VARIANT NAME` of your graph. In the example below, the variant name is `current`.
+   ```graphql
+   query MyQuery {
+     posts {
+       id
+       title
+     }
+   }
+   ```
+
+1. To see the metrics click on the `VARIANT NAME` of your graph. In the example below, the variant name is `current`.
 
-![graph-home.png](../../static/images/apollo-studio/graph-home.png)
+   ![graph-home.png](../../static/images/apollo-studio/graph-home.png)
 
-- You will see the following page. From here click on insights icon as highlighted on the left side of the image.
+1. You will see the following page. From here click on insights icon as highlighted on the left side of the image.
 
-![insights-nav.png](../../static/images/apollo-studio/insights-nav.png)
+   ![insights-nav.png](../../static/images/apollo-studio/insights-nav.png)
 
-- You will now be able to see all the information related to your queries here
+1. You will now be able to see all the information related to your queries here
 
-![insights.png](../../static/images/apollo-studio/insights.png)
+   ![insights.png](../../static/images/apollo-studio/insights.png)
 
-![insights-graph.png](../../static/images/apollo-studio/insights-graph.png)
+   ![insights-graph.png](../../static/images/apollo-studio/insights-graph.png)
 
-_Note: If you don't see the name of your query here, try running the query multiple times and waiting for some time. Since the metric isn't sent to Apollo Studio for each query, instead they are batched together and sent at once for efficiency reasons._
+:::important
+If you don't see the name of your query here, try running the query multiple times and waiting for some time. Since the metric isn't sent to Apollo Studio for each query, instead they are batched together and sent at once for efficiency reasons.
+:::

docs/guides/cli.md

@@ -44,22 +44,12 @@ Example:
 tailcall check --schema ./path/to/file1.graphql ./path/to/file2.graphql
 ```
 
-## compose
-
-The `compose` merges configuration files into one. To use the `compose` command, follow this format:
-
-Example:
-
-```bash
-tailcall compose ./path/to/file1.graphql ./path/to/file2.graphql
-```
-
 ### --format
 
-This specifies the format of the desired composed file. It accepts `gql` or `graphql`,`yml` or `yaml`, `json` . Default is `json`.
+This is an optional command which allows changing the format of the input file. It accepts `gql` or `graphql`,`yml` or `yaml`, `json` .
 
 ```bash
-tailcall compose ./path/to/file1.graphql ./path/to/file2.graphql --format gql
+tailcall check ./path/to/file1.graphql ./path/to/file2.graphql --format json
 ```
 
 ## start

docs/guides/conventions.md

@@ -7,7 +7,7 @@ description: Enhance your understanding of naming and casing conventions for Gra
 
 1. **Consistency is Key:** Ensure that naming conventions are uniform across your entire schema to maintain clarity and consistency.
 2. **Descriptive Over Generic:** Opt for descriptive, specific names rather than broad, generic ones to avoid ambiguity.
-3. **Avoid Abbreviations:** Avoid the use of acronyms, initialisms, and abbreviations to keep your schema intuitive and understandable.
+3. **Avoid Abbreviations:** Avoid the use of acronyms, initialism, and abbreviations to keep your schema intuitive and understandable.
 
 ## Detailed Naming Cases
 
@@ -35,7 +35,7 @@ union SearchResult = ...
 scalar Date
 ```
 
-**Enum Values in `SCREAMING_SNAKE_CASE`:** Clearly distinguish enum values by using `SCREAMING_SNAKE_CASE`.
+**Enum Values in `SCREAMING_SNAKE_CASE`:** Distinguish enum values by using `SCREAMING_SNAKE_CASE`.
 
 ```graphql
 enum StatusEnum {
@@ -86,7 +86,7 @@ query PostQuery {
 
 ### Mutations
 
-**Verb Prefixes for Mutations:** Begin mutation field names with a verb to clearly indicate the action being performed, improving schema readability.
+**Verb Prefixes for Mutations:** Begin mutation field names with a verb to indicate the action being performed, improving schema readability.
 
 ```graphql
 type Mutation {
@@ -102,7 +102,7 @@ type Mutation {
 
 ### Input Types
 
-**`Input` Suffix:** Clearly denote input types by appending `Input` to their names, specifying their use case.
+**`Input` Suffix:** Denote input types by appending `Input` to their names, specifying their use case.
 
 ```graphql
 input AddPostInput {

docs/guides/grpc.md

@@ -206,7 +206,7 @@ Or
 
 Another important feature of the `@grpc` operator is that it allows you to implement request batching for remote data almost effortlessly as soon as you have gRPC methods that resolve multiple responses for multiple inputs in a single request.
 
-In our protobuf example file, we have a method called `GetMultipleNews` that we can use. To enable batching we need to enable [`@upstream.batch` option](../operators/upstream.md#batch) first and specify `groupBy` option for the `@grpc` operator.
+In our protobuf example file, we have a method called `GetMultipleNews` that we can use. To enable batching we need to enable [`@upstream.batch` option](../operators/upstream.md#batch) first and specify `batchKey` option for the `@grpc` operator.
 
 ```graphql
 schema
@@ -222,7 +222,7 @@ type Query {
       method: "news.NewsService.GetNews"
       body: "{{args.news}}"
       # highlight-next-line
-      groupBy: ["news", "id"]
+      batchKey: ["news", "id"]
     )
 }
 ```

docs/guides/n+1.md

@@ -40,7 +40,7 @@ In real-world applications featuring thousands of posts and users, the problem b
 
 The TailCall CLI serves as a powerful tool for developers, identifying N+1 issues in GraphQL applications even before making any requests or publishing configurations in production. This proactive approach enables the mitigation of potential issues from the development stage.
 
-Before diving into the usage, ensure you have familiarized yourself with the basics of the TailCall CLI. If you haven't already, please refer to the [Installation] guide, which will walk you through the setup process and help you understand the key commands.
+Before diving into the usage, ensure you have familiarized yourself with the basics of the TailCall CLI. If you haven't already, please refer to the [installation guide], which will walk you through the setup process and help you understand the key commands.
 
 ### Jsonplaceholder Example
 
@@ -73,7 +73,7 @@ type Post {
 }
 ```
 
-This schema enables clients to retrieve a list of posts, each including its associated user data. Yet, in its present form, it's affected by the N+1 problem: fetching each post necessitates a separate request for its associated user data.
+This schema enables clients to retrieve a list of posts, each including its associated user data. Yet, in its present form, it's affected by the **N+1 problem**: fetching each post necessitates a separate request for its associated user data.
 
 The following section will show how to detect this issue with the TailCall CLI.
 
@@ -83,9 +83,10 @@ With the `check` command, TailCall CLI can assist you in identifying potential N
 
 ```bash
 tailcall check ./jsonplaceholder.graphql
-No errors found.
+INFO File read: ./examples/jsonplaceholder.graphql ... ok
+INFO Config ./examples/jsonplaceholder.graphql ... ok
 # highlight-start
-N + 1:     1
+INFO N + 1 detected: 1
 # highlight-end
 ```
 
@@ -95,10 +96,11 @@ For a deeper understanding of these issues, you can use the `--n-plus-one-querie
 
 ```bash
 tailcall check  ./jsonplaceholder.graphql --n-plus-one-queries
-No errors found.
+INFO File read: ./examples/jsonplaceholder.graphql ... ok
+INFO Config ./examples/jsonplaceholder.graphql ... ok
+INFO N + 1 detected: 1
 # highlight-start
-N + 1:     1
-  query { posts { user } }
+query { posts { user } }
 # highlight-end
 ```
 
@@ -121,19 +123,19 @@ type Post {
       path: "/users"
       # highlight-start
       query: [{key: "id", value: "{{value.userId}}"}]
-      groupBy: ["id"]
+      batchKey: ["id"]
       # highlight-end
     )
 }
 ```
 
-The described changes introduce significant tweaks to the `@http` directive and incorporate the `@groupBy` operator:
+The described changes introduce two significant tweaks to the `@http` directive and incorporate the `batchKey` configuration:
 
-- `query: [{key: "id", value: "{{value.userId}}"}]`: In this configuration, the TailCall CLI generates a URL that aligns the user id with the `userId` from the parent `Post`. For a batch of posts, the CLI compiles a single URL, such as `/users?id=1&id=2&id=3...id=10`, consolidating the requests into one.
+1. `query: [{key: "id", value: "{{value.userId}}"}]`: In this configuration, the TailCall CLI generates a URL that aligns the user id with the `userId` from the parent `Post`. For a batch of posts, the CLI compiles a single URL, such as `/users?id=1&id=2&id=3...id=10`, consolidating the requests into one.
 
-- `groupBy: ["id"]`: This parameter instructs the system to convert the list of responses into a map internally, using the user's `id` as the unique key. In essence, it allows the system to differentiate each user value in the response list.
+2. `batchKey: ["id"]`: This parameter instructs the system to convert the list of responses into a map internally, using the user's `id` as the unique key. In essence, it allows the system to differentiate each user value in the response list.
 
 By using this approach, you can reduce the number of requests from 101 (for 100 posts plus one initial request for the post list) down to 2. This significant optimization effectively handles the N+1 problem, thereby enhancing your application's efficiency and user experience.
 
 [json placeholder api]: https://jsonplaceholder.typicode.com
-[installation]: /docs/getting_started/
+[installation guide]: /docs/getting_started/