From 6395631c518372d9cb92a0e1d9c4f7a3961fe3e5 Mon Sep 17 00:00:00 2001 From: laststylebender Date: Mon, 16 Sep 2024 23:32:02 +0530 Subject: [PATCH 1/3] - updated docs for query complexity and depth --- docs/directives.md | 81 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) diff --git a/docs/directives.md b/docs/directives.md index 98e0d98eb8..cf14ca378e 100644 --- a/docs/directives.md +++ b/docs/directives.md @@ -1672,6 +1672,87 @@ schema @server( ) ``` +### queryComplexity + +The `queryComplexity` configuration sets a limit on the complexity of incoming GraphQL queries. Query complexity is a measure of how resource-intensive a GraphQL query is, primarily based on the number of fields in the query. By default, each field contributes a complexity of 1. This feature helps prevent resource-intensive queries that could potentially overload the server. + +Consider the following schema with a `queryComplexity` limit set to 3: + +```graphql showLineNumbers +schema @server( + port: 8000 + queryComplexity: 3 +) +``` + +In above configuration, the server will reject queries where the total complexity exceeds 3. If a query surpasses this limit, the server will return a validation error. + +- **Example Query:** + + This query has a total complexity of 7. Since it exceeds the configured limit of 3, the server will reject the request with a validation error. + ```graphql showLineNumbers + query { + post { + id + title + body + user { + id + name + } + } + } + ``` + + If the `queryComplexity` was instead set to 8: + ```graphql showLineNumbers + schema @server( + port: 8000 + queryComplexity: 8 + ) + ``` + The same query would succeed because the total complexity (7) is below the limit. + + +### queryDepth + +The `queryDepth` configuration limits the depth of GraphQL queries to prevent overly nested queries that can strain server resources. Query depth refers to the level of nested fields within a query. By restricting the depth, you can safeguard your server from deeply nested queries that could result in excessive processing time. + +Consider the following schema with a `queryDepth` limit set to 2: + +```graphql showLineNumbers +schema @server( + port: 8000 + queryDepth: 2 +) +``` +In this configuration, the server will reject queries where the depth exceeds 2. If a query goes beyond this limit, a validation error will be returned. + +- **Example Query:** + This query has a depth of 3, since the user field is nested under the `post` field, and `id` and `name` are further nested under `user`. Since this exceeds the configured depth limit of 2, the query will be rejected. + ```graphql showLineNumbers + query { + post { # depth: 1 + id # depth: 2 + title + body + user { + id # depth: 3 + name + } + } + } + ``` + + If the `queryDepth` was instead set to 4: + ```graphql showLineNumbers + schema @server( + port: 8000 + queryDepth: 4 + ) + ``` + The same query would succeed because the depth (4) is now within the limit. + ## @telemetry Directive The `@telemetry` directive facilitates seamless integration with [OpenTelemetry](https://open-telemetry.io), enhancing the observability of your GraphQL services powered by Tailcall. By leveraging this directive, developers gain access to valuable insights into the performance and behavior of their applications. From 7fe90f8dcb9e9b0ba4b2996dba5993519311d819 Mon Sep 17 00:00:00 2001 From: laststylebender Date: Mon, 16 Sep 2024 23:33:21 +0530 Subject: [PATCH 2/3] - prettier formatting changes --- docs/directives.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/docs/directives.md b/docs/directives.md index cf14ca378e..2faad62004 100644 --- a/docs/directives.md +++ b/docs/directives.md @@ -1690,6 +1690,7 @@ In above configuration, the server will reject queries where the total complexit - **Example Query:** This query has a total complexity of 7. Since it exceeds the configured limit of 3, the server will reject the request with a validation error. + ```graphql showLineNumbers query { post { @@ -1705,14 +1706,15 @@ In above configuration, the server will reject queries where the total complexit ``` If the `queryComplexity` was instead set to 8: + ```graphql showLineNumbers schema @server( port: 8000 queryComplexity: 8 ) ``` - The same query would succeed because the total complexity (7) is below the limit. + The same query would succeed because the total complexity (7) is below the limit. ### queryDepth @@ -1726,18 +1728,21 @@ schema @server( queryDepth: 2 ) ``` + In this configuration, the server will reject queries where the depth exceeds 2. If a query goes beyond this limit, a validation error will be returned. - **Example Query:** This query has a depth of 3, since the user field is nested under the `post` field, and `id` and `name` are further nested under `user`. Since this exceeds the configured depth limit of 2, the query will be rejected. + ```graphql showLineNumbers query { - post { # depth: 1 - id # depth: 2 - title - body + post { + # depth: 1 + id # depth: 2 + title + body user { - id # depth: 3 + id # depth: 3 name } } @@ -1745,12 +1750,14 @@ In this configuration, the server will reject queries where the depth exceeds 2. ``` If the `queryDepth` was instead set to 4: + ```graphql showLineNumbers schema @server( port: 8000 queryDepth: 4 ) ``` + The same query would succeed because the depth (4) is now within the limit. ## @telemetry Directive From 2c69bb927b57e28c48eb65f0894cdbeb047a04a0 Mon Sep 17 00:00:00 2001 From: laststylebender Date: Mon, 16 Sep 2024 23:34:46 +0530 Subject: [PATCH 3/3] - update the query depth. --- docs/directives.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/directives.md b/docs/directives.md index 2faad62004..b6fff4e78c 100644 --- a/docs/directives.md +++ b/docs/directives.md @@ -1758,7 +1758,7 @@ In this configuration, the server will reject queries where the depth exceeds 2. ) ``` - The same query would succeed because the depth (4) is now within the limit. + The same query would succeed because the depth (3) is now within the limit. ## @telemetry Directive