Rate Limiting

Rate limiting is a technique for reducing server load by limiting the number of requests that can be made to a subgraph.

You can use rate limiting feature in order to limit the rate of calling queries and mutations.

Programmatic Configuration

import { defineConfig } from "@graphql-hive/gateway";

export const gatewayConfig = defineConfig({
  rateLimiting: [
    {
      type: "Query",
      field: "foo",
      max: 5, // requests limit for a time period
      ttl: 5000, // time period
      // You can use any value from the context
      identifier: "{context.headers.authorization}",
    },
  ],
});

Rate Limiting through @rateLimit directive

import { defineConfig } from "@graphql-hive/gateway";

export const gatewayConfig = defineConfig({
  rateLimiting: true,
});

This approach follows the pattern of graphql-rate-limit.

To set rate limit hints in your subgraph schema, the @rateLimit directive definition should be included in the subgraph schema:

# Import the directive for Federation
extend schema
  @link(url: "https://specs.apollo.dev/link/v1.0")
  @link(
    url: "https://specs.apollo.dev/federation/v2.3"
    import: ["@composeDirective"]
  )
  @link(
    url: "https://the-guild.dev/graphql/mesh/spec/v1.0"
    import: ["@rateLimit"]
  )
  @composeDirective(name: "@rateLimit")

directive @rateLimit(
  max: Int
  window: String
  message: String
  identityArgs: [String]
  arrayLengthField: String
) on FIELD_DEFINITION

Then in the subgraph schema, you can use the @rateLimit directive to set rate limit hints on fields:

type Query {
  getItems: [Item]
    @rateLimit(window: "1s", max: 5, message: "You are doing that too often.")
}

Field Configuration

• window: Specify a time interval window that the max number of requests can access the field. We use Zeit's ms to parse the window arg, docs here.

• max: Define the max number of calls to the given field per window.

• identityArgs: If you wanted to limit the requests to a field per id, per user, use identityArgs to define how the request should be identified. For example you'd provide just ["id"] if you wanted to rate limit the access to a field by id. We use Lodash's get to access nested identity args, docs here.

• message: A custom message per field. Note you can also use formatError to customise the default error message if you don't want to define a single message per rate limited field.

• arrayLengthField: Limit calls to the field, using the length of the array as the number of calls to the field.