explain api for explaining query execution

[dpetran]

Explain

Adds an api function for tracking solution during query execution.

Each pattern in the where clause is tracked and the number of solutions it produces is returned, so users can see how each pattern affects the solution space.

This query:

{"@context" {"ex" "http://example.com/"}
  "where" [{"@id" "?s" "ex:num" "?num"}
                   ["optional"
                      {"@id" "?s" "ex:ref1" "?ref1"}]
                   ["union"
                     {"@id" "?s" "ex:foo" "?str"}
                     {"@id" "?s" "ex:bar" "?str"}]
                   ["filter" "(> 50 ?num)"]]
   "select" ["?s" "?ref1" "?str"]}

Produces this solution report of a vector of [<pattern> <counters>] tuples in execution order, tracking the number of solutions input to a pattern under :in and the number of solutions produced by a pattern under :out.

[[{"@id" "?s", "ex:num" "?num"} {:in 1, :out 48}]
 [[:optional {"@id" "?s", "ex:ref1" "?ref1"}] {:in 48, :out 48}]
 [{"@id" "?s", "ex:ref1" "?ref1"} {:in 48, :out 0}]
 [[:union {"@id" "?s", "ex:foo" "?str"} {"@id" "?s", "ex:bar" "?str"}] {:in 48, :out 96}]
 [{"@id" "?s", "ex:foo" "?str"} {:in 48, :out 48}]
 [{"@id" "?s", "ex:bar" "?str"} {:in 48, :out 48}]
 [[:filter "(> 50 ?num)"] {:in 96, :out 48}]]

Limitations

This PR provides a subset of the functionality outlined in https://github.com/fluree/core/issues/181.

The issue describes tracking the number of bindings per variable, but each solution will always have a binding for each variable introduced in prior patterns, so the number of solutions can be used to infer this information.

This PR does not track any of the following at this time:

• execution data about the interior of a solution - including whether a binding is null in the case of OPTIONAL patterns.
• timing data on pattern evaluation - I don't think we can tell when a pattern is finished producing solutions until the whole query is finished executing.
• which index is used to produce new solutions
• expression-level (BIND, FILTER, HAVING, etc.) performance tracking