GraphQL Static Query Complexity Policy

Policy Name

GraphQL Static Query Complexity

Summary

Calculates query complexity and blocks requests that exceed the defined budget

Category

Security

First Omni Gateway version available

v1.13.0

Release Notes

GraphQL Static Query Complexity

Returned status codes

400 - Parse failures always trigger a 400 response. Complexity and list violations return this code only if Block request is enabled. The response includes a standard GraphQL errors object.

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

Parameter Required Default Value Description

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

maximumComplexity

Yes

None

The maximum complexity score allowed for a single query. Requests exceeding this value are blocked or logged as warnings.

source

context

context automatically retrieves the schema file from the API asset in Anypoint Exchange. inline uses the schema text provided directly in the policy configuration. This is required for local mode or environments not connected to Exchange.

schema

The schema text used for validation. Required if source is inline. Omit for context

defaultFieldCost

1.0

The cost applied to fields that don’t have a specific complexity tag (typically @cost) in your schema file.

blockOperation

true

Specifies whether Omni Gateway blocks requests that exceed the complexity limit. If true, Omni Gateway blocks the request and returns a 400 Bad Request error. If false, Omni Gateway logs a warning and forwards the request to your backend. Parse failures always trigger a 400 response, even if this setting is false.

rejectUnboundedLists

true

If true, Omni Gateway blocks queries for list fields that lack a limiting argument, such as first or limit. This prevents users from requesting large datasets.

directiveName

cost

The name of the complexity tag in your schema file that defines per-field costs.

valueArgument

weight

The specific argument within your shema tag that defines the cost of a field. For example, in @cost(value: 5), the argument is value.

multipliersArgument

multipliers

The argument in your shcema tag that lists which field arguments multiply the cost. For example, in @cost(multipliers: ["first"]), the value of the first argument is used to multiply the field’s cost.

Resource Configuration Example

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

- 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:

Field Description Default Value Required

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

Maximum Complexity

The maximum allowed complexity score for a query.

None

Yes

Default Field Cost

The cost applied to fields lacking a specific complexity tag in your schema file.

1.0

Block request

Specifies whether Omni Gateway blocks requests that exceed the complexity limit. If enabled, Omni Gateway blocks the request and returns a 400 error. If disabled, Omni Gateway logs violations as warnings. Parse failures always trigger a 400 response, regardless of this setting.

Enabled

Yes

Reject unbounded lists

If enabled, Omni Gateway blocks queries for list fields that lack a limiting argument, such as first or limit.

Enabled

Yes

Directive Name

The name of the complexity tag in your schema file that defines per-field costs.

cost

Value Argument

The argument within your complexity tag that specifies the field’s base cost.