---
schema_version: "1"
id: 35a69417712a79453ac659323367c03e31f653263c3620b40919c87ea743080b
title: GraphQL Static Query Complexity Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/1.13/policies-included-graphql-static-query-complexity.md
canonical_url: https://docs.mulesoft.com/gateway/1.13/policies-included-graphql-static-query-complexity
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 6d230c818ca2d0b37ce5a8b2a60a4d984c59c91e492813a93492f17433ad2ac1
description: MuleSoft Documentation Site
release: "1.13"
latest: false
---
---
product: Omni Gateway
version: 1.13
keywords: graphql, query complexity, api gateway, flex gateway, gateway, policy
---

# GraphQL Static Query Complexity Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>GraphQL Static Query Complexity</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Calculates query complexity and blocks requests that exceed the defined budget</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/graphql-static-query-complexity-release-notes">GraphQL Static Query Complexity</a></p></td></tr><tr><td><p><strong>Returned status codes</strong></p></td><td><p>400 - Parse failures always trigger a 400 response. Complexity and list violations return this code only if <strong>Block request</strong> is enabled. The response includes a standard GraphQL errors object.</p></td></tr></tbody></table>

## Summary

The GraphQL Static Query Complexity policy estimates the complexity of each incoming GraphQL
operation from your GraphQL schema and the operation text. If the estimate exceeds the configured
budget or fails other checks enforced by the policy, Omni Gateway rejects the request or logs a
warning and forwards it upstream.

The policy loads schema in these ways:

- If `source` is `context`, Omni Gateway automatically loads the schema file from the API asset in
  Anypoint Exchange.

- If `source` is `inline`, provide the schema text directly in the policy configuration. This is
  required for local mode or environments not connected to Exchange.

After Omni Gateway extracts the GraphQL operation text, the policy analyzes query complexity.

If Omni Gateway can’t resolve the full operation text, as with persisted queries, it skips
complexity analysis.

If a system error occurs during analysis, even if the schema loads into memory, Omni Gateway logs a
warning and forwards the request instead of blocking it.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: graphql-static-query-complexity-flex config: maximumComplexity: <number> //
REQUIRED, must be positive source: <string> // OPTIONAL, default: context; values: "context" or
"inline" schema: <string> // REQUIRED when source is inline; omit when source is context
defaultFieldCost: <number> // OPTIONAL, default: 1.0, must be >= 0 blockOperation: <boolean> //
OPTIONAL, default: true rejectUnboundedLists: <boolean> // OPTIONAL, default: true directiveName:
<string> // OPTIONAL, default: cost valueArgument: <string> // OPTIONAL, default: weight
multipliersArgument: <string> // OPTIONAL, default: multipliers

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>maximumComplexity</code></p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>None</p></div></div></td><td><div><div><p>The maximum complexity score allowed for a single query. Requests exceeding this value are blocked or logged as warnings.</p></div></div></td></tr><tr><td><div><div><p><code>source</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>context</code></p></div></div></td><td><div><div><p><code>context</code> automatically retrieves the schema file from the API asset in Anypoint Exchange. <code>inline</code> uses the schema text provided directly in the policy configuration. This is required for local mode or environments not connected to Exchange.</p></div></div></td></tr><tr><td><div><div><p><code>schema</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>NA</p></div></div></td><td><div><div><p>The schema text used for validation. Required if <code>source</code> is <code>inline</code>. Omit for <code>context</code></p></div></div></td></tr><tr><td><div><div><p><code>defaultFieldCost</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>1.0</code></p></div></div></td><td><div><div><p>The cost applied to fields that don’t have a specific complexity tag (typically @cost) in your schema file.</p></div></div></td></tr><tr><td><div><div><p><code>blockOperation</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>Specifies whether Omni Gateway blocks requests that exceed the complexity limit. If <code>true</code>, Omni Gateway blocks the request and returns a <code>400</code> Bad Request error. If <code>false</code>, Omni Gateway logs a warning and forwards the request to your backend. Parse failures always trigger a <code>400</code> response, even if this setting is <code>false</code>.</p></div></div></td></tr><tr><td><div><div><p><code>rejectUnboundedLists</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>If <code>true</code>, Omni Gateway blocks queries for list fields that lack a limiting argument, such as <code>first</code> or <code>limit</code>. This prevents users from requesting large datasets.</p></div></div></td></tr><tr><td><div><div><p><code>directiveName</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>cost</code></p></div></div></td><td><div><div><p>The name of the complexity tag in your schema file that defines per-field costs.</p></div></div></td></tr><tr><td><div><div><p><code>valueArgument</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>weight</code></p></div></div></td><td><div><div><p>The specific argument within your shema tag that defines the cost of a field. For example, in <code>@cost(value: 5)</code>, the argument is <code>value</code>.</p></div></div></td></tr><tr><td><div><div><p><code>multipliersArgument</code></p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p><code>multipliers</code></p></div></div></td><td><div><div><p>The argument in your shcema tag that lists which field arguments multiply the cost. For example, in <code>@cost(multipliers: ["first"])</code>, the value of the <code>first</code> argument is used to multiply the field’s cost.</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

This example sets the maximum complexity at `250`, uses default costs and tag names, and provides
the schema text inline:

```yaml
- policyRef:
    name: graphql-static-query-complexity-flex
  config:
    source: inline
    maximumComplexity: 250
    blockOperation: true
    rejectUnboundedLists: true
    schema: |
      directive @cost(weight: Int!, multipliers: [String!]) on FIELD_DEFINITION

      type Query {
        users(limit: Int): [User!]! @cost(weight: 1, multipliers: ["limit"])
        version: String!
      }

      type User {
        id: ID!
        name: String!
      }
```

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Field</th><th>Description</th><th>Default Value</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Maximum Complexity</p></div></div></td><td><div><div><p>The maximum allowed complexity score for a query.</p></div></div></td><td><div><div><p>None</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Default Field Cost</p></div></div></td><td><div><div><p>The cost applied to fields lacking a specific complexity tag in your schema file.</p></div></div></td><td><div><div><p><code>1.0</code></p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Block request</p></div></div></td><td><div><div><p>Specifies whether Omni Gateway blocks requests that exceed the complexity limit. If enabled, Omni Gateway blocks the request and returns a <code>400</code> error. If disabled, Omni Gateway logs violations as warnings. Parse failures always trigger a <code>400</code> response, regardless of this setting.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Reject unbounded lists</p></div></div></td><td><div><div><p>If enabled, Omni Gateway blocks queries for list fields that lack a limiting argument, such as <code>first</code> or <code>limit</code>.</p></div></div></td><td><div><div><p>Enabled</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Directive Name</p></div></div></td><td><div><div><p>The name of the complexity tag in your schema file that defines per-field costs.</p></div></div></td><td><div><div><p><code>cost</code></p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Value Argument</p></div></div></td><td><div><div><p>The argument within your complexity tag that specifies the field’s base cost.</p></div></div></td><td><div><div><p><code>weight</code></p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Multipliers Argument</p></div></div></td><td><div><div><p>The argument within your complexity tag that identifies which query parameters multiply the cost. For example, in \@cost(weight: 1, multipliers: ["limit"])<code>, the multipliers argument is `multipliers</code>, and the <code>limit</code> value multiplies the base cost.</p></div></div></td><td><div><div><p><code>multipliers</code></p></div></div></td><td><div><div><p>No</p></div></div></td></tr></tbody></table>

## See Also

- [Inbound Policies Directory](https://docs.mulesoft.com/gateway/1.13/policies-included-directory)

- [GraphQL Schema Validation Policy](https://docs.mulesoft.com/gateway/1.13/policies-included-graphql-schema-validation)

- [Securing Omni Gateway Instances with Policies](https://docs.mulesoft.com/gateway/1.13/gateway-secure-apis)