@defer

Definition

directive @defer(
  if: Boolean! = true
  label: String
) on FRAGMENT_SPREAD | INLINE_FRAGMENT

Arguments

Argument	Type	Default	Description
`if`	`Boolean!`	`true`	Controls whether the router defers the fragment. Accepts a literal or a variable. With `false`, the router delivers the fragment in the initial response.
`label`	`String`		A static string that identifies the fragment in the response. The router returns it on the `pending` entry of the fragment.

Overview

@defer is an executable directive. Clients use it in operations, not in subgraph schemas. It marks a fragment whose fields the client does not need in the initial response. The router returns all other fields in the initial response. The router delivers the deferred fragment in a later part of a multipart/mixed response. The router provides the directive when you set engine.enable_defer to true. You change no subgraph and no composition. See Defer for the router configuration and the response format. The Incremental Delivery spec draft defines @defer. The draft is at RFC stage 2 of the GraphQL specification process. The router follows the response format of that draft.

Supported locations

Inline fragments without a type condition: ... @defer { ... }.
Inline fragments with a type condition: ... on Product @defer { ... }.
Fragment spreads: ...ProductReviews @defer.

Supported operations

Queries, on root fields and on nested fields.
Mutations, on nested fields below the root selection set.

Examples

Example schema

type Query {
  product(id: ID!): Product
}

type Product @key(fields: "id") {
  id: ID!
  name: String!
  reviews: [Review!]!
}

type Review {
  rating: Int!
  body: String!
}

Deferring an inline fragment

query ProductPage {
  product(id: "1") {
    id
    name
    ... @defer {
      reviews {
        rating
        body
      }
    }
  }
}

The response has two parts. The initial response carries id and name. It announces the deferred fragment:

{
  "data": { "product": { "id": "1", "name": "Router" } },
  "pending": [{ "id": "1", "path": ["product"] }],
  "hasNext": true
}

The incremental response delivers the fragment and completes it:

{
  "incremental": [
    {
      "data": { "reviews": [{ "rating": 5, "body": "Fast." }] },
      "id": "1"
    }
  ],
  "completed": [{ "id": "1" }],
  "hasNext": false
}

Deferring a fragment spread

query ProductPage {
  product(id: "1") {
    id
    name
    ...ProductReviews @defer
  }
}

fragment ProductReviews on Product {
  reviews {
    rating
    body
  }
}

Using Labels

query ProductPage {
  product(id: "1") {
    id
    ... @defer(label: "reviews") {
      reviews {
        rating
      }
    }
  }
}

The router returns the label on the pending entry:

{
  "data": { "product": { "id": "1" } },
  "pending": [{ "id": "1", "path": ["product"], "label": "reviews" }],
  "hasNext": true
}

Conditional defer

query ProductPage($deferReviews: Boolean!) {
  product(id: "1") {
    id
    ... @defer(if: $deferReviews) {
      reviews {
        rating
      }
    }
  }
}

With deferReviews: true, reviews arrives in an incremental response. With deferReviews: false, reviews belongs to the initial response. The router then sends a single JSON response.

Rules

A label is a static string. The router does not accept a variable as a label.
Labels must be unique across all @defer and @stream directives in the document.
The client can select the same field inside and outside a deferred fragment on the same object. The router then delivers the field in the initial response and drops the deferred copy.
A deferred fragment without field selections has no effect.
if accepts a literal or a variable. The router resolves the variable value per request. The value belongs to the cache key of the query plan.

Federation behavior

The router handles @defer itself. It plans the deferred fragment as a separate set of subgraph fetches. Those fetches run after the router sends the initial response. A deferred fragment can select fields of an entity that another subgraph owns. The router then fetches the entity key in the primary phase. It uses that key as the representation for the deferred entity fetch. Subgraphs never receive the @defer directive. See How the Router Executes @defer for the execution model.

Getting Started

Concepts

Cosmo Connect

Cosmo ConnectRPC

Router

Studio

Control Plane

GraphQL / Federation

Deployments and Hosting

Definition

Arguments

Overview

Supported locations

Supported operations

Examples

Example schema

Deferring an inline fragment

Deferring a fragment spread

Using Labels

Conditional defer

Rules

Federation behavior

​Definition

​Arguments

​Overview

​Supported locations

​Supported operations

​Examples

​Example schema

​Deferring an inline fragment

​Deferring a fragment spread

​Using Labels

​Conditional defer

​Rules

​Federation behavior

Definition

Arguments

Overview

Supported locations

Supported operations

Examples

Example schema

Deferring an inline fragment

Deferring a fragment spread

Using Labels

Conditional defer

Rules

Federation behavior