Merge pull request #652 from bserdar/explain

Fix #231: expose explain plan

Author: paterczm

crud/src/main/java/com/redhat/lightblue/assoc/CompositeFindImpl.java

@@ -49,6 +49,8 @@
 import com.redhat.lightblue.assoc.ep.ResultDocument;
 import com.redhat.lightblue.assoc.ep.ExecutionContext;
 
+import com.redhat.lightblue.util.JsonDoc;
+
 /**
  * Finder for searches involving composite entities
  *
@@ -102,34 +104,51 @@ public void setParallelism(int n) {
         }
     }
 
+    private void initialize(OperationContext ctx,
+                            CRUDFindRequest req) {
+        if(executionPlan==null) {
+            // Composite find algorithm works like this:
+            //   1) Find the minimal entity tree required to evaluate the request.query
+            //   2) Find a query plan for that minimal entity tree
+            //   3) If the query plan root is also the root entity, then expand that query
+            //      plan to include all nodes
+            //   4) Execute search based on query plan
+            //   5) If query plan node is not the entity root, find documents found for entity root,
+            //      and re-retrieve the documents
+            // First: detemine minimal entity tree containing the nodes sufficient to
+            // evaluate the query
+            Set<CompositeMetadata> minimalTree = findMinimalSetOfQueryEntities(req.getQuery(),
+                                                                               ctx.getTopLevelEntityMetadata());
+            
+            selectQueryPlan(req.getQuery(), minimalTree);
+            LOGGER.debug("Search query plan:{}, retrieval query plan:{}", searchQPlan, retrievalQPlan);
+            
+            executionPlan = new ExecutionPlan(req.getProjection(),
+                                              req.getSort(),
+                                              req.getFrom(),
+                                              req.getTo(),
+                                              root,
+                                              searchQPlan,
+                                              retrievalQPlan);
+        }
+    }
+    
+    @Override
+    public void explain(OperationContext ctx,
+                        CRUDFindRequest req) {
+        initialize(ctx,req);
+        ExecutionContext executionContext = new ExecutionContext(ctx,null);
+        JsonDoc doc=new JsonDoc(executionPlan.explain(executionContext));
+        ctx.addDocument(doc);        
+    }
+    
     @Override
     public CRUDFindResponse find(OperationContext ctx,
                                  CRUDFindRequest req) {
         LOGGER.debug("Composite find: start");
+        
+        initialize(ctx,req);
 
-        // Composite find algorithm works like this:
-        //   1) Find the minimal entity tree required to evaluate the request.query
-        //   2) Find a query plan for that minimal entity tree
-        //   3) If the query plan root is also the root entity, then expand that query
-        //      plan to include all nodes
-        //   4) Execute search based on query plan
-        //   5) If query plan node is not the entity root, find documents found for entity root,
-        //      and re-retrieve the documents
-        // First: detemine minimal entity tree containing the nodes sufficient to
-        // evaluate the query
-        Set<CompositeMetadata> minimalTree = findMinimalSetOfQueryEntities(req.getQuery(),
-                ctx.getTopLevelEntityMetadata());
-
-        selectQueryPlan(req.getQuery(), minimalTree);
-        LOGGER.debug("Search query plan:{}, retrieval query plan:{}", searchQPlan, retrievalQPlan);
-
-        executionPlan = new ExecutionPlan(req.getProjection(),
-                req.getSort(),
-                req.getFrom(),
-                req.getTo(),
-                root,
-                searchQPlan,
-                retrievalQPlan);
         ctx.setProperty(Mediator.CTX_QPLAN, searchQPlan == null ? retrievalQPlan : searchQPlan);
         LOGGER.debug("Execution plan:{}", executionPlan);
 

crud/src/main/java/com/redhat/lightblue/assoc/ep/AbstractSearchStep.java

@@ -100,6 +100,7 @@ public OperationContext search(ExecutionContext ctx, CRUDFindRequest req) {
         return search(block, ctx, req);
     }
 
+
     public OperationContext search(ExecutionBlock block, ExecutionContext ctx, CRUDFindRequest req) {
         OperationContext searchCtx = ctx.getOperationContext().
                 getDerivedOperationContext(block.getMetadata().getName(), req);
@@ -152,4 +153,5 @@ public JsonNode toJson() {
         }
         return o;
     }
+
 }

crud/src/main/java/com/redhat/lightblue/assoc/ep/Assemble.java

@@ -73,7 +73,7 @@ public List<ResultDocument> getResultList(QueryExpression q, ExecutionContext ct
     }
 
     @Override
-    public StepResult<ResultDocument> getResults(ExecutionContext ctx) {
+    public void initialize() {
         destinations = new HashMap<ExecutionBlock, Assemble>();
         for (ExecutionBlock x : destinationBlocks) {
             Assemble a = x.getStep(Assemble.class);
@@ -83,6 +83,10 @@ public StepResult<ResultDocument> getResults(ExecutionContext ctx) {
                 throw new IllegalArgumentException("No assemble step in " + x);
             }
         }
+    }
+    
+    @Override
+    public StepResult<ResultDocument> getResults(ExecutionContext ctx) {
         LOGGER.debug("getResults, source:{}, destinations={}", source, destinations);
         // Get the results from the source
         StepResult<ResultDocument> sourceResults = source.getStep().getResults(ctx);
@@ -194,8 +198,13 @@ public JsonNode toJson() {
         ArrayNode array = JsonNodeFactory.instance.arrayNode();
         a.set("right", array);
         for (ExecutionBlock b : destinationBlocks) {
-            array.add(b.toJson());
+            ObjectNode detail=JsonNodeFactory.instance.objectNode();
+            AssociationQuery aq = b.getAssociationQueryForEdge(block);
+            detail.set("associationQuery",aq.getQuery().toJson());
+            detail.set("source",b.toJson());
+            array.add(detail);
         }
         return o;
     }
+
 }

crud/src/main/java/com/redhat/lightblue/assoc/ep/ExecutionBlock.java

@@ -87,7 +87,7 @@ public ExecutionBlock(CompositeMetadata root, QueryPlanNode qpNode) {
     /**
      * This should be called after all execution blocks are built
      */
-    public void initialize() {
+    public void linkBlocks() {
         // Build a list of all reference fields that need to be populated for the docs produces by this block
         // But to do that, we need the destination nodes of this block. We don't have that.
         // What we have is the sources. So, we populate the reference fields of our sources instead.
@@ -101,6 +101,10 @@ public void initialize() {
         }
     }
 
+    public void initializeSteps() {
+        steps.stream().forEach(Step::initialize);
+    }
+
     /**
      * Returns the slots for the child documents of the documents of this block
      */

crud/src/main/java/com/redhat/lightblue/assoc/ep/ExecutionPlan.java

@@ -301,7 +301,10 @@ public ExecutionPlan(Projection requestProjection,
         }
 
         for (ExecutionBlock block : qp2BlockMap.values()) {
-            block.initialize();
+            block.linkBlocks();
+        }
+        for (ExecutionBlock block : qp2BlockMap.values()) {
+            block.initializeSteps();
         }
     }
 
@@ -454,4 +457,8 @@ public JsonNode toJson() {
     public String toString() {
         return toJson().toString();
     }
+
+    public JsonNode explain(ExecutionContext ctx) {
+        return resultStep.explain(ctx);
+    }
 }

crud/src/main/java/com/redhat/lightblue/assoc/ep/Search.java

@@ -23,14 +23,22 @@
 
 import java.util.stream.Collectors;
 
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.node.JsonNodeFactory;
+import com.fasterxml.jackson.databind.node.ArrayNode;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import com.redhat.lightblue.mediator.OperationContext;
+import com.redhat.lightblue.mediator.SimpleFindImpl;
 
 import com.redhat.lightblue.crud.CRUDFindRequest;
 import com.redhat.lightblue.crud.DocCtx;
 
+import com.redhat.lightblue.util.JsonDoc;
+
 /**
  * Performs search
  *
@@ -79,4 +87,26 @@ protected List<ResultDocument> getSearchResults(ExecutionContext ctx) {
         }
     }
 
+    @Override
+    public JsonNode explain(ExecutionContext ctx) {
+        ObjectNode node=(ObjectNode)toJson();
+        CRUDFindRequest req=buildFindRequest(ctx);
+        OperationContext searchCtx = ctx.getOperationContext().
+            getDerivedOperationContext(block.getMetadata().getName(), req);
+        new SimpleFindImpl(block.getMetadata(), searchCtx.getFactory()).explain(searchCtx,req);
+        List<JsonDoc> docs = searchCtx.getOutputDocumentsWithoutErrors();
+        if(docs!=null&&!docs.isEmpty()) {
+            if(docs.size()==1) {
+                node.set("implementation",docs.get(0).getRoot());
+            } else {
+                ArrayNode arr=JsonNodeFactory.instance.arrayNode();
+                for(JsonDoc doc:docs) {
+                    arr.add(doc.getRoot());
+                }
+                node.set("implementation",arr);
+            }
+        }
+        return node;
+    }
+
 }

crud/src/main/java/com/redhat/lightblue/assoc/ep/Step.java

@@ -45,6 +45,13 @@ public Step(ExecutionBlock block) {
 
     public abstract JsonNode toJson();
 
+    public void initialize() {
+    }
+
+    public JsonNode explain(ExecutionContext ctx) {
+        return toJson();
+    }
+
     /**
      * Returns the associated block of this step
      */

crud/src/main/java/com/redhat/lightblue/crud/CRUDController.java

@@ -113,6 +113,7 @@ CRUDFindResponse find(CRUDOperationContext ctx,
                           Long from,
                           Long to);
 
+
     /**
      * Return an implementation of MetadataListener interface to receive
      * notifications about metadata operations. Returns null if this

crud/src/main/java/com/redhat/lightblue/crud/ExplainQuerySupport.java

@@ -0,0 +1,54 @@
+/*
+ Copyright 2013 Red Hat, Inc. and/or its affiliates.
+
+ This file is part of lightblue.
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+package com.redhat.lightblue.crud;
+
+import com.redhat.lightblue.query.Projection;
+import com.redhat.lightblue.query.QueryExpression;
+import com.redhat.lightblue.query.Sort;
+
+import com.redhat.lightblue.util.JsonDoc;
+
+/**
+ * If the controller supports explain query, implement this interface
+ */
+public interface ExplainQuerySupport {
+
+    /**
+     * Explains a query
+     *
+     * @param ctx Operation context
+     * @param entity The entity to search for
+     * @param query The query. Cannot be null
+     * @param projection What fields to return. Cannot be null
+     * @param sort Sort keys. Can be null
+     * @param from starting index in the result set. Can be null. Meaninguful
+     * only if a sort is given. Starts from 0.
+     * @param to end index in the result set. Starts from 0, and inclusive. Can
+     * be null.
+     * @param destDoc This document is populated with the explained query
+     */
+    void explain(CRUDOperationContext ctx,
+                 QueryExpression query,
+                 Projection projection,
+                 Sort sort,
+                 Long from,
+                 Long to,
+                 JsonDoc destDoc);
+                 
+}

crud/src/main/java/com/redhat/lightblue/mediator/Finder.java

@@ -25,4 +25,6 @@
 public interface Finder {
 
     CRUDFindResponse find(OperationContext ctx, CRUDFindRequest req);
+
+    void explain(OperationContext ctx, CRUDFindRequest req);
 }