[Epic] Explain Request Functionality

[jsimnz]

Simple Explain SUB-TASKS (initial implementation will be verbose = true).

• Explain selectNode
• Explain selectTopNode
• Explain createNode
• Explain deleteNode
• Explain Request - Simple #325
• Explain the attributes of scanNode #474
• Explain the attributes of commitSelectNode. #477
• Explain the attributes of countNode. #478
• Explain the attributes of typeIndexJoin. #475
• Explain the attributes of updateNode. #483
• Explain the attributes of sortNode. #481
• Explain the attributes of sumNode. #482
• Explain the attributes of dagScanNode. #479
• Add cid and field attributes to dagScanNode #597
• Make countNode explain more consistent with other nodes (sumNode) #599
• Explain the attributes of groupNode #525
• Explain the attributes of averageNode. #476
• Explain the attributes of limit (renderLimitNode / hardLimitNode) #561
• Explain the attributes of renderNode. #480
• Make topLevelNode explainable as is without updating Source() #736
• Wireup explain around topLevelNode's recursive nature. #748
• Explain the topLevelNode and it's attribute(s). #626

Debug Explain SUB-TASKS

• Explain Request - Debug #948

Prediction Explain SUB-TASKS

• Explain Request - Prediction #327

Execution Explain SUB-TASKS

• Explain Request - Execution #326

Bugs:

• bug: wrapped scanNode inside another scanNode while explaining #486
• bug: Explain result has int64 type rather than uint64 #485
• bug: including the subtype in the top level filter argument won't produce a MultiNode #484

CHECKLIST:

• Update schema to parse in @explain directive from the query and mutation location only.
• Iterate over all directive and find the matching explain.
• Introduce the option to set verbose false for explain request.
• Make sure to test MultiNode properly.

DESCOPED:

• Explain Request - Simple (TEXT) #361
• Explain Request - Prediction (TEXT) #362
• Explain Request - Execution (TEXT) #363

DESCRIPTION

Implement an Explain API + Endpoint for returning the structure of a plan graph as generated by the planner package.

Request:

query @explain {
 user {
   _key
   age
   name
 }
}

Response:

{
 "data": [
   {
     "explain": {
       "selectTopNode": {
         "selectNode": {
           "filter": null,
           "scanNode": {
             "collectionID": "1",
             "collectionName": "user",
             "filter": null
           }
         }
       }
     }
   }
 ]
}

There should be additional data options. Such as ANALYZE (from SQL) which would actually execute the Request, and provide insights into perf analysis on a per node basis and EXECUTE to provide insights to what was actually executed.

There should be an additional option to change the verbosity level of explain to omit attributes like filter when they are null.

Output is only going to be in JSON.

[jsimnz]

defradb/api/http/api.go

Line 1 in c113312

// Copyright 2020 Source Inc.

[shahzadlone]

So pretty much like this example:

from:
https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/life_of_a_query.md

[jsimnz]

Spec doc: https://hackmd.io/BbMstl-9TE6n_Nq-5G8PRw?view