Dgraph GraphQL Tour

Basic

Cascade

The @cascade directive removes any nodes from query results that don’t have all fields included in the query. You can also use the @cascade directive to remove nodes from query results where a filter inside a block returns no results.

In the following query, Dgraph returns all of Alice’s friends, whether or not they own a pet:

{
  getPerson(xid: "alice") {
    name
    age
    friends {
      name
      ownsPets {
        name
      }
    }
  }
}

With the @cascade directive, friends of Alice that don’t own a pet are not included in the result, as follows:

{
  getPerson(xid: "alice") @cascade {
    name
    age
    friends {
      name
      ownsPets {
        name
      }
    }
  }
}

You can get the same query result more efficiently by using the has filter argument. However, you can’t use the has argument to return the desired results in queries that filter on an edge, or with deeper queries.

Something to try: Return Alice’s friends that own the animal with an xid equal to “goldie”.

{
  getPerson(xid: "alice") {
    name
    age
    friends @cascade {
      name
      ownsPets(filter: { xid: { eq: "goldie" } }) {
        name
      }
    }
  }
}

Putting the cascade directive at different levels in the subgraph applies the cascade effect from that level down.

Compare the responses returned by this query in the following three subgraphs:

{
  noCascade: queryPerson {
    id
    name
    age
    friends {
      id
      name
      age
    }
  }
  cascadeFriends: queryPerson {
    id
    name
    age
    friends @cascade {
      id
      name
      age
    }
  }
  cascadePeople: queryPerson @cascade {
    id
    name
    age
    friends {
      id
      name
      age
    }
  }
}

To learn more about the @cascade directive, see the Dgraph documentation site: https://dgraph.io/docs/graphql/queries/cascade/