@cascade Directive

The @cascade directive can be applied to fields. With the @cascade directive, nodes that don’t have all fields specified in the query are removed. This can be useful in cases where some filter was applied and some nodes might not have all the listed fields.

For example, the query below only returns the authors which have both reputation and posts, where posts have text. Note that @cascade trickles down so if it’s applied at the queryAuthor level, it will automatically be applied at the posts level too.

{
    queryAuthor @cascade {
        reputation
        posts {
            text
        }
    }
}

Pagination

Starting from v21.03, the @cascade directive supports pagination of query results.

For example, to get to get the next 5 results after skipping the first 2 with all the fields non-null:

query {
  queryTask(first: 5, offset: 2) @cascade {
    name
    completed
  }
}

Nested @cascade

@cascade can also be used at nested levels, so the query below would return all authors but only those posts which have both text and id.

{
    queryAuthor  {
        reputation
        posts @cascade {
            id
            text
        }
    }
}

Parameterized @cascade

The @cascade directive can optionally take a list of fields as an argument. This changes the default behavior, considering only the supplied fields as mandatory instead of all the fields for a type. Listed fields are automatically cascaded as a required argument to nested selection sets.

In the example below, name is supplied in the fields argument. For an author to be in the query response, it must have a name, and if it has a country subfield, then that subfield must also have name.

{
    queryAuthor  @cascade(fields:["name"]) {
        reputation
        name
        country{
           Id
           name
        }
    }
}

The query below only return those posts which have a non-null text field.

{
    queryAuthor {
        reputation
        name
        posts @cascade(fields:["text"]) {
           title
           text
        }
    }
}

Nesting

The cascading nature of field selection is overwritten by a nested @cascade.

For example, the query below ensures that an author has the reputation and name fields, and, if it has a posts subfield, then that subfield must have a text field.

{
    queryAuthor @cascade(fields:["reputation","name"]) {
        reputation
        name
        dob
        posts @cascade(fields:["text"]) {
            title
            text
        }
    }
}

Filtering

Filters can be used with the @cascade directive if they are placed before it:

{
    queryAuthor (filter: {
        name: {
          anyofterms: "Alice Bob"
        }
      }) @cascade(fields:["reputation","name"]) {
        reputation
        name
        dob
        posts @cascade(fields:["text"]) {
            title
            text
        }
    }
}