Improved query planning

Author: mbakli

src/planner/distributed_mobilitydb_explain.c

@@ -132,6 +132,7 @@ static void ExplainQueryType(DistributedSpatiotemporalQueryPlan *distPlan, Expla
     ExplainPropertyText("Distributed Spatiotemporal Planner", temp->data, es);
 }
 
+/* getQueryType renders the combination of chosen strategies as a short human-readable label. */
 static char * getQueryType(List *strategies)
 {
     ListCell *cell = NULL;
@@ -222,6 +223,13 @@ static void ExplainQueryPlan(DistributedSpatiotemporalQueryPlan *distPlan, Expla
     }
 }
 
+/*
+ * ExplainPlanStrategies re-runs the executor in explain-only mode
+ * (RunQueryExecutor with explain=true, so no data-modifying SPI calls
+ * happen) to obtain the per-strategy tasks, then prints one representative
+ * task per task type via ExplainOneTask — showing the plan for a single
+ * tile stands in for all `candidates` tiles that would actually run.
+ */
 static void
 ExplainPlanStrategies(DistributedSpatiotemporalQueryPlan *distPlan, ExplainState *es, int indent_group)
 {
@@ -242,6 +250,12 @@ ExplainPlanStrategies(DistributedSpatiotemporalQueryPlan *distPlan, ExplainState
         es->indent -= 5;
     }
 }
+/*
+ * ExplainOneTask plans and (via ExplainWorkerPlan) prints the local plan
+ * for a single, randomly-chosen tile of `task`, substituting that tile's
+ * concrete shard identifier into the task's query (GetLocalQuery) so it
+ * can be planned as an ordinary local query.
+ */
 static void
 ExplainOneTask(ExecutorTask *task, STMultirelation *base,ExplainState *es, int indent_group)
 {
@@ -267,6 +281,12 @@ ExplainOneTask(ExecutorTask *task, STMultirelation *base,ExplainState *es, int i
     ExplainEndOutput(es);
 }
 
+/*
+ * GetLocalQuery rewrites query_string so that every distributed table name
+ * it references is replaced by the concrete shard/tile identifier chosen
+ * for it (GetRandomTileId), producing a plain local query that EXPLAIN can
+ * plan directly.
+ */
 static char *
 GetLocalQuery(char *query_string, Oid base, ExecTaskType taskType, int rand_tile)
 {

src/post_processing/post_processing.c

@@ -47,8 +47,15 @@ PostProcessingQuery(PostProcessing *postProcessing, List *strategies)
     /* The other operations will be added internally based on the query semantics */
 }
 
-/* Early rewriting for the distributed functions */
-
+/*
+ * RewriterDistFuncs rewrites query_string so each registered distributed
+ * function call (e.g. an aggregate like avg()) is replaced by its worker
+ * function, producing the query that actually runs on each tile
+ * (postProcessing->worker). For every rewritten function it also records
+ * the coordinator-side combiner/final operations (as QOperations) so the
+ * executor's post-processing phase can merge the per-tile results back
+ * together (see ProcessIntermediateTasks/ProcessFinalTasks).
+ */
 extern void
 RewriterDistFuncs(Query *parse, PostProcessing *postProcessing, const char *query_string)
 {

src/utils/helper_functions.c

@@ -14,6 +14,12 @@
 
 #include "utils/helper_functions.h"
 
+/*
+ * replaceWord replaces the first occurrence of oldW in s with newW,
+ * in place, and returns s. Assumes s has enough allocated room to hold the
+ * result (the local buffer is sized off strlen(s), so newW must not be
+ * longer than oldW).
+ */
 extern
 char* replaceWord( char* s,  char* oldW,  char* newW)
 {
@@ -35,6 +41,7 @@ char* replaceWord( char* s,  char* oldW,  char* newW)
     return s;
 }
 
+/* extract_between returns a newly allocated copy of the substring of str found strictly between markers p1 and p2. */
 extern
 char * extract_between(const char *str, const char *p1, const char *p2) {
     const char *i1 = strstr(str, p1);
@@ -54,6 +61,7 @@ char * extract_between(const char *str, const char *p1, const char *p2) {
     }
 }
 
+/* change_sentence returns a newly allocated copy of sentence with the first occurrence of find replaced by replace. */
 extern char *
 change_sentence (char *sentence, char *find, char *replace)
 {
@@ -72,6 +80,7 @@ change_sentence (char *sentence, char *find, char *replace)
     return dest;
 }
 
+/* toLower returns a newly allocated, lowercased copy of str. */
 extern
 char *toLower(char *str)
 {
@@ -84,6 +93,7 @@ char *toLower(char *str)
     return str_l;
 }
 
+/* IsDatumEmpty reports whether val is the zero/unset Datum (i.e. no value was assigned). */
 extern bool
 IsDatumEmpty(Datum val)
 {

src/utils/planner_utils.c

@@ -17,6 +17,11 @@
 #include "utils/planner_utils.h"
 #include "catalog/pg_dist_spatiotemporal_dist_functions.h"
 
+/*
+ * GetTilingSchemeInfo loads relationId's pg_dist_spatiotemporal_tables row
+ * into an in-memory STMultirelationCatalog: its tiling method/type/
+ * granularity, tile count, distribution column, and related metadata.
+ */
 extern STMultirelationCatalog
 GetTilingSchemeInfo(Oid relationId)
 {
@@ -85,6 +90,13 @@ DisFuncRelationId()
     return RelationId(Tbl_Dist_Functions);
 }
 
+/*
+ * AddCatalogFilterInfo records into catalogFilter which of tbl's tiles a
+ * predicate node of predType could match. A NULL node (no analysable
+ * predicate) conservatively assumes every tile is a candidate. Narrowing
+ * the candidate count below numTiles (e.g. via a real bounding-box lookup)
+ * is left as future work — see the Tile Scan Rebalancer TODO below.
+ */
 extern void
 AddCatalogFilterInfo(STMultirelationCatalog tbl, CatalogFilter *catalogFilter, Node *node,
                      PredicateType predType, bool IsConst)