@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

We’re overhauling Dgraph’s docs to make them clearer and more approachable. If you notice any issues during this transition or have suggestions, please let us know.

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 is automatically 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’re placed before it:

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