add pathkeys description.

diff --git a/src/backend/optimizer/path/pathkeys.c b/src/backend/optimizer/path/pathkeys.c
index 82e88c0a74b0e038f5f29ed0c605ac241eb7b7b3..098581a2dcfbebf9bd162cefd31ba5587794aa10 100644 (file)
--- a/src/backend/optimizer/path/pathkeys.c
+++ b/src/backend/optimizer/path/pathkeys.c
@@ -25,7 +25,6 @@
 #include "optimizer/joininfo.h"
 #include "optimizer/ordering.h"
 
-
 static int match_pathkey_joinkeys(List *pathkey, List *joinkeys,
                                                int outer_or_inner);
 static bool joinkeys_pathkeys_match(List *joinkeys, List *pathkey,
@@ -35,6 +34,29 @@ static List *new_join_pathkey(List *subkeys, List *considered_subkeys,
 static List *new_matching_subkeys(Var *subkey, List *considered_subkeys,
                                                List *join_rel_tlist, List *joinclauses);
 
+
+/*
+ *     Explanation of Path.pathkeys
+ *
+ *     This structure is a List of List of Var nodes that represent the sort
+ *     order of the result generated by the Path.
+ *
+ *     In single/base relation RelOptInfo's, the Path's represent various ways
+ *     of generate the relation.  Sequential scan Paths have a NIL pathkeys.
+ *     Index scans have Path.pathkeys that represent the chosen index.  A
+ *     single-key index pathkeys would be { {tab1_indexkey1} }.  The pathkeys
+ *     entry for a multi-key index would be { {tab1_indexkey1}, {tab1_indexkey2} }.
+ *
+ *     Multi-relation RelOptInfo Path's are more complicated.  Mergejoins are
+ *     only performed with equajoins("=").  Because of this, the multi-relation
+ *     path actually has more than one ordering.  For example, a mergejoin Path
+ *     of "tab1.col1 = tab2.col1" would generate a pathkeys of
+ *     { {tab1.col1, tab2.col1} }.  This allows future joins to use either Var
+ *     as a pre-sorted key to prevent Mergejoins from having to re-sort the Path.
+ *     They are equal, so they are both primary sort keys.  This is why pathkeys
+ *     is a List of Lists.
+ */
+ 
 /****************************************************************************
  *             KEY COMPARISONS
  ****************************************************************************/

diff --git a/src/include/nodes/relation.h b/src/include/nodes/relation.h
index 8e23072d2e08c801a02740903a69543ac9e68028..ed049f30dbdf2e1591960eb9a1b9edeaefa5c4c1 100644 (file)
--- a/src/include/nodes/relation.h
+++ b/src/include/nodes/relation.h
@@ -142,9 +142,10 @@ typedef struct Path
 
        PathOrder       *pathorder;
 
-       List        *pathkeys;  /* This is a List of List of Var nodes.
-                                                        * It is a List of Lists because of multi-key
-                                                        * indexes.
+       List        *pathkeys;  /*
+                                                        * This is a List of List of Var nodes.
+                                                        * See the top of optimizer/path/pathkeys.c
+                                                        * for more information.
                                                         */                                                        
        Cost            outerjoincost;
        Relids          joinid;