feat(graphql+-): Allow parameterized @cascade directive. (#5607)

Co-authored-by: Abhimanyu Singh Gaur <12651351+abhimanyusinghgaur@users.noreply.github.com>

Author: parasssh

gql/parser.go

@@ -67,7 +67,7 @@ type GraphQuery struct {
 	Recurse          bool
 	RecurseArgs      RecurseArgs
 	ShortestPathArgs ShortestPathArgs
-	Cascade          bool
+	Cascade          []string
 	IgnoreReflex     bool
 	Facets           *pb.FacetParams
 	FacetsFilter     *FilterTree
@@ -961,7 +961,9 @@ L:
 			case "normalize":
 				gq.Normalize = true
 			case "cascade":
-				gq.Cascade = true
+				if err := parseCascade(it, gq); err != nil {
+					return nil, err
+				}
 			case "groupby":
 				gq.IsGroupby = true
 				if err := parseGroupby(it, gq); err != nil {
@@ -2094,6 +2096,69 @@ func tryParseFacetList(it *lex.ItemIterator) (res facetRes, parseOk bool, err er
 	}
 }
 
+// parseCascade parses the cascade directive.
+// Two formats:
+// 	1. @cascade
+//  2. @cascade(pred1, pred2, ...)
+func parseCascade(it *lex.ItemIterator, gq *GraphQuery) error {
+	item := it.Item()
+	items, err := it.Peek(1)
+	if err != nil {
+		return item.Errorf("Unable to peek lexer after cascade")
+	}
+
+	// check if it is without any args:
+	// 1. @cascade {
+	// 2. @cascade }
+	// 3. @cascade @
+	// 4. @cascade\n someOtherPred
+	if items[0].Typ == itemLeftCurl || items[0].Typ == itemRightCurl || items[0].
+		Typ == itemAt || items[0].Typ == itemName {
+		// __all__ implies @cascade i.e.  implies values for all the children are mandatory.
+		gq.Cascade = append(gq.Cascade, "__all__")
+		return nil
+	}
+
+	count := 0
+	expectArg := true
+	it.Next()
+	item = it.Item()
+	if item.Typ != itemLeftRound {
+		return item.Errorf("Expected a left round after cascade, got: %s", item.String())
+	}
+
+loop:
+	for it.Next() {
+		item := it.Item()
+		switch item.Typ {
+		case itemRightRound:
+			break loop
+		case itemComma:
+			if expectArg {
+				return item.Errorf("Expected a predicate but got comma")
+			}
+			expectArg = true
+		case itemName:
+			if !expectArg {
+				return item.Errorf("Expected a comma or right round but got: %v", item.Val)
+			}
+			gq.Cascade = append(gq.Cascade, collectName(it, item.Val))
+			count++
+			expectArg = false
+		default:
+			return item.Errorf("Unexpected item while parsing: %v", item.Val)
+		}
+	}
+	if expectArg {
+		// use the initial item to report error line and column numbers
+		return item.Errorf("Unnecessary comma in cascade()")
+	}
+	if count == 0 {
+		return item.Errorf("At least one predicate required in parameterized cascade()")
+	}
+	return nil
+}
+
 // parseGroupby parses the groupby directive.
 func parseGroupby(it *lex.ItemIterator, gq *GraphQuery) error {
 	count := 0
@@ -2430,7 +2495,9 @@ func parseDirective(it *lex.ItemIterator, curp *GraphQuery) error {
 			return item.Errorf("Facets parsing failed.")
 		}
 	case item.Val == "cascade":
-		curp.Cascade = true
+		if err := parseCascade(it, curp); err != nil {
+			return err
+		}
 	case item.Val == "normalize":
 		curp.Normalize = true
 	case peek[0].Typ == itemLeftRound:

gql/parser_test.go

@@ -5275,3 +5275,86 @@ func TestFilterWithEmpty(t *testing.T) {
 	require.NoError(t, err)
 	require.Equal(t, gq.Query[0].Filter.Func.Args[0].Value, "")
 }
+
+func TestCascade(t *testing.T) {
+	query := `{
+		names(func: has(name)) @cascade {
+		  name
+		}
+	  }`
+	gq, err := Parse(Request{
+		Str: query,
+	})
+	require.NoError(t, err)
+	require.Equal(t, gq.Query[0].Cascade[0], "__all__")
+}
+
+func TestCascadeParameterized(t *testing.T) {
+	query := `{
+		names(func: has(name)) @cascade(name, age) {
+		  name
+		  age
+		  dob
+		}
+	  }`
+	gq, err := Parse(Request{
+		Str: query,
+	})
+	require.NoError(t, err)
+	require.Equal(t, gq.Query[0].Cascade[0], "name")
+	require.Equal(t, gq.Query[0].Cascade[1], "age")
+}
+
+func TestBadCascadeParameterized(t *testing.T) {
+	badQueries := []string{
+		`{
+			names(func: has(name)) @cascade( {
+			  name
+			  age
+			  dob
+			}
+		  }`,
+		`{
+			names(func: has(name)) @cascade) {
+			  name
+			  age
+			  dob
+			}
+		 }`,
+		`{
+			names(func: has(name)) @cascade() {
+			  name
+			  age
+			  dob
+			}
+		  }`,
+		`{
+			names(func: has(name)) @cascade(,) {
+			  name
+			  age
+			  dob
+			}
+		  }`,
+		`{
+			names(func: has(name)) @cascade(name,) {
+			  name
+			  age
+			  dob
+			}
+		  }`,
+		`{
+			names(func: has(name)) @cascade(,name) {
+			  name
+			  age
+			  dob
+			}
+		  }`,
+	}
+
+	for _, query := range badQueries {
+		_, err := Parse(Request{
+			Str: query,
+		})
+		require.Error(t, err)
+	}
+}

graphql/dgraph/graphquery.go

@@ -69,8 +69,10 @@ func writeQuery(b *strings.Builder, query *gql.GraphQuery, prefix string) {
 		x.Check2(b.WriteRune(')'))
 	}
 
-	if query.Cascade {
-		x.Check2(b.WriteString(" @cascade"))
+	if len(query.Cascade) != 0 {
+		if query.Cascade[0] == "__all__" {
+			x.Check2(b.WriteString(" @cascade"))
+		}
 	}
 
 	switch {

graphql/resolve/query_rewriter.go

@@ -544,7 +544,7 @@ func (authRw *authRewriter) rewriteRuleNode(
 		r1 := rewriteAsQuery(qry, authRw)
 		r1.Var = varName
 		r1.Attr = "var"
-		r1.Cascade = true
+		r1.Cascade = append(r1.Cascade, "__all__")
 
 		return []*gql.GraphQuery{r1}, &gql.FilterTree{
 			Func: &gql.Function{

graphql/schema/wrappers.go

@@ -122,7 +122,7 @@ type Field interface {
 	SetArgTo(arg string, val interface{})
 	Skip() bool
 	Include() bool
-	Cascade() bool
+	Cascade() []string
 	HasCustomDirective() (bool, map[string]bool)
 	Type() Type
 	SelectionSet() []Field
@@ -659,8 +659,12 @@ func (f *field) Include() bool {
 	return dir.ArgumentMap(f.op.vars)["if"].(bool)
 }
 
-func (f *field) Cascade() bool {
-	return f.field.Directives.ForName(cascadeDirective) != nil
+func (f *field) Cascade() []string {
+
+	if f.field.Directives.ForName(cascadeDirective) == nil {
+		return nil
+	}
+	return []string{"__all__"}
 }
 
 func (f *field) HasCustomDirective() (bool, map[string]bool) {
@@ -1049,7 +1053,7 @@ func (q *query) Include() bool {
 	return true
 }
 
-func (q *query) Cascade() bool {
+func (q *query) Cascade() []string {
 	return (*field)(q).Cascade()
 }
 
@@ -1162,7 +1166,7 @@ func (m *mutation) Include() bool {
 	return true
 }
 
-func (m *mutation) Cascade() bool {
+func (m *mutation) Cascade() []string {
 	return (*field)(m).Cascade()
 }
 
@@ -1197,7 +1201,7 @@ func (m *mutation) QueryField() Field {
 		}
 		// if @cascade was given on mutation itself, then it should get applied for the query which
 		// gets executed to fetch the results of that mutation, so propagating it to the QueryField.
-		if m.Cascade() && !f.Cascade() {
+		if len(m.Cascade()) != 0 && len(f.Cascade()) == 0 {
 			field := f.(*field).field
 			field.Directives = append(field.Directives, &ast.Directive{Name: cascadeDirective})
 		}

query/query.go

@@ -156,8 +156,10 @@ type params struct {
 	Recurse bool
 	// RecurseArgs stores the arguments passed to the @recurse directive.
 	RecurseArgs gql.RecurseArgs
-	// Cascade is true if the @cascade directive is specified.
-	Cascade bool
+	// Cascade is the list of predicates to apply @cascade to.
+	// __all__ is special to mean @cascade i.e. all the children of this subgraph are mandatory
+	// and should have values otherwise the node will be excluded.
+	Cascade []string
 	// IgnoreReflex is true if the @ignorereflex directive is specified.
 	IgnoreReflex bool
 
@@ -532,7 +534,6 @@ func treeCopy(gq *gql.GraphQuery, sg *SubGraph) error {
 
 		args := params{
 			Alias:        gchild.Alias,
-			Cascade:      gchild.Cascade || sg.Params.Cascade,
 			Expand:       gchild.Expand,
 			Facet:        gchild.Facets,
 			FacetsOrder:  gchild.FacetsOrder,
@@ -549,6 +550,15 @@ func treeCopy(gq *gql.GraphQuery, sg *SubGraph) error {
 			IsInternal:   gchild.IsInternal,
 		}
 
+		// If parent has @cascade (with or without params), inherit @cascade (with no params)
+		if len(sg.Params.Cascade) > 0 {
+			args.Cascade = append(args.Cascade, "__all__")
+		}
+		// Allow over-riding at this level.
+		if len(gchild.Cascade) > 0 {
+			args.Cascade = gchild.Cascade
+		}
+
 		if gchild.IsCount {
 			if len(gchild.Children) != 0 {
 				return errors.New("Node with count cannot have child attributes")
@@ -1296,6 +1306,13 @@ func (sg *SubGraph) populateVarMap(doneVars map[string]varValue, sgPath []*SubGr
 	if sg.DestUIDs == nil || sg.IsGroupBy() {
 		return nil
 	}
+
+	cascadeArgMap := make(map[string]bool)
+	for _, pred := range sg.Params.Cascade {
+		cascadeArgMap[pred] = true
+	}
+	cascadeAllPreds := cascadeArgMap["__all__"]
+
 	out := make([]uint64, 0, len(sg.DestUIDs.Uids))
 	if sg.Params.Alias == "shortest" {
 		goto AssignStep
@@ -1311,7 +1328,7 @@ func (sg *SubGraph) populateVarMap(doneVars map[string]varValue, sgPath []*SubGr
 			return err
 		}
 		sgPath = sgPath[:len(sgPath)-1] // Backtrack
-		if !child.Params.Cascade {
+		if len(child.Params.Cascade) == 0 {
 			continue
 		}
 
@@ -1320,7 +1337,7 @@ func (sg *SubGraph) populateVarMap(doneVars map[string]varValue, sgPath []*SubGr
 		child.updateUidMatrix()
 	}
 
-	if !sg.Params.Cascade {
+	if len(sg.Params.Cascade) == 0 {
 		goto AssignStep
 	}
 
@@ -1336,7 +1353,8 @@ func (sg *SubGraph) populateVarMap(doneVars map[string]varValue, sgPath []*SubGr
 
 			// If the length of child UID list is zero and it has no valid value, then the
 			// current UID should be removed from this level.
-			if !child.IsInternal() &&
+			if (cascadeAllPreds || cascadeArgMap[child.Attr]) &&
+				!child.IsInternal() &&
 				// Check len before accessing index.
 				(len(child.valueMatrix) <= i || len(child.valueMatrix[i].Values) == 0) &&
 				(len(child.counts) <= i) &&