feat(graphql): output translated DQL query when the graphql debug sup…

…erflag is set (#9280)

**Description**

This change adds the translated DQL query to the GraphQL's `extension`
attribute set when the GraphQL debug superflag is set to true.

In Dgraph, GraphQL queries are translated to DQL before entering the
query system. This change allows for an inspection of what the
translator is doing behind the scenes.

Potential Use Cases:

* learning DQL
* aiding few shot prompting in LMs
* use in Dgraph "dashboards" or other helper apps

Note: this is for queries (reads) only. Mutations in DQL are pretty
straightforward, but support for them could be added in the future.


![image](https://github.com/user-attachments/assets/a818ef04-5189-4bc1-a3d7-7b7a5d2fbe70)

**Checklist**

- [x] Code compiles correctly and linting passes locally
- [x] For all _code_ changes, an entry added to the `CHANGELOG.md` file
describing and linking to
      this PR
- [x] Tests added for new functionality, or regression tests for bug
fixes added as applicable
- [x] [Docs PR](dgraph-io/dgraph-docs#689)

CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project will
 adhere to [Semantic Versioning](https://semver.org) starting `v22.0.0`.
 
+## [v24.X.X] - YYYY-MM-DD
+
+- **GraphQL**
+
+  - feat(graphql): adds translated DQL to extensions response when the "--graphql debug" super flag
+    is set to true (#9280)
+
+[v24.X.X]: https://github.com/hypermodeinc/dgraph/compare/v24.0.5...v24.X.X
+
 ## [v24.0.5] - 2024-11-05
 
 [v24.0.5]: https://github.com/hypermodeinc/dgraph/compare/v24.0.4...v24.0.5

graphql/e2e/common/common.go

@@ -848,6 +848,7 @@ func RunAll(t *testing.T) {
 	t.Run("multiple operations", multipleOperations)
 	t.Run("query post with author", queryPostWithAuthor)
 	t.Run("queries have extensions", queriesHaveExtensions)
+	t.Run("queries with debug flag have dql query in extensions", queriesWithDebugFlagHaveDQLQueryInExtensions)
 	t.Run("queries have touched_uids even if there are GraphQL errors", erroredQueriesHaveTouchedUids)
 	t.Run("alias works for queries", queryWithAlias)
 	t.Run("multiple aliases for same field in query", queryWithMultipleAliasOfSameField)

graphql/e2e/common/query.go

@@ -24,6 +24,7 @@ import (
 	"io"
 	"math/rand"
 	"net/http"
+	"regexp"
 	"sort"
 	"strconv"
 	"strings"
@@ -2097,6 +2098,26 @@ func queriesHaveExtensions(t *testing.T) {
 	require.Greater(t, int(gqlResponse.Extensions[touchedUidskey].(float64)), 0)
 }
 
+func queriesWithDebugFlagHaveDQLQueryInExtensions(t *testing.T) {
+	query := &GraphQLParams{
+		Query: `query {
+			queryPost {
+				title
+			}
+		}`,
+	}
+
+	gqlResponse := query.ExecuteAsPost(t, GraphqlURL+"?debug=true")
+	RequireNoGQLErrors(t, gqlResponse)
+
+	// Needed for directives tests (Post remapped to myPost)
+	pattern := regexp.MustCompile(`query \{\n\s*query(?:Post|myPost)\(func: type\((?:Post|myPost)\)\) \{\n\s*Post\.title : (?:Post|myPost)\.title\n\s*dgraph\.uid : uid\n\s*\}\n\}`)
+
+	require.Contains(t, gqlResponse.Extensions, "dql_query")
+	require.NotEmpty(t, gqlResponse.Extensions["dql_query"])
+	require.True(t, pattern.MatchString(gqlResponse.Extensions["dql_query"].(string)))
+}
+
 func erroredQueriesHaveTouchedUids(t *testing.T) {
 	country1 := addCountry(t, postExecutor)
 	country2 := addCountry(t, postExecutor)

graphql/e2e/directives/docker-compose.yml

@@ -37,7 +37,7 @@ services:
       /gobin/dgraph  ${COVERAGE_OUTPUT} alpha --telemetry "reports=false; sentry=false;"
       --zero=zero1:5080 --expose_trace --profile_mode block --block_rate 10 --logtostderr -v=2
       --my=alpha1:7080 --security "whitelist=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16;" --graphql
-      "lambda-url=http://lambda:8686/graphql-worker;" --trace "ratio=1.0;"
+      "lambda-url=http://lambda:8686/graphql-worker; debug=true;" --trace "ratio=1.0;"
 
   lambda:
     image: dgraph/dgraph-lambda:latest

graphql/e2e/normal/docker-compose.yml

@@ -37,7 +37,7 @@ services:
       /gobin/dgraph  ${COVERAGE_OUTPUT} alpha --telemetry "reports=false; sentry=false;"
       --zero=zero1:5080 --expose_trace --profile_mode block --block_rate 10 --logtostderr -v=2
       --my=alpha1:7080 --security "whitelist=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16;" --graphql
-      "lambda-url=http://lambda:8686/graphql-worker;" --trace "ratio=1.0;"
+      "lambda-url=http://lambda:8686/graphql-worker; debug=true;" --trace "ratio=1.0;"
 
   lambda:
     image: dgraph/dgraph-lambda:latest

graphql/resolve/query.go

@@ -139,6 +139,9 @@ func (qr *queryResolver) rewriteAndExecute(ctx context.Context, query schema.Que
 	}
 
 	ext.TouchedUids = resp.GetMetrics().GetNumUids()[touchedUidsKey]
+	if x.Config.GraphQL.GetBool("debug") {
+		ext.DQLQuery = qry
+	}
 	resolved := &Resolved{
 		Data:       resp.GetJson(),
 		Field:      query,

graphql/schema/response.go

@@ -182,6 +182,7 @@ func (r *Response) Output() interface{} {
 type Extensions struct {
 	TouchedUids uint64 `json:"touched_uids,omitempty"`
 	Tracing     *Trace `json:"tracing,omitempty"`
+	DQLQuery    string `json:"dql_query,omitempty"`
 }
 
 // GetTouchedUids returns TouchedUids
@@ -205,6 +206,12 @@ func (e *Extensions) Merge(ext *Extensions) {
 	} else {
 		e.Tracing.Merge(ext.Tracing)
 	}
+
+	if e.DQLQuery == "" {
+		e.DQLQuery = ext.DQLQuery
+	} else {
+		e.DQLQuery = e.DQLQuery + "\n" + ext.DQLQuery
+	}
 }
 
 // Trace : Apollo Tracing is a GraphQL extension for tracing resolver performance.Response