add pathkeys description.

diff --git a/src/backend/optimizer/path/pathkeys.c b/src/backend/optimizer/path/pathkeys.c
index 996c197350ca64a4e64d11f8f5b98bda621e1948..29f11dcd1c425ce242c6acc3f79aa119e0c90595 100644 (file)
--- a/src/backend/optimizer/path/pathkeys.c
+++ b/src/backend/optimizer/path/pathkeys.c
@@ -7,7 +7,7 @@
  *
  *
  * IDENTIFICATION
- *   $Header: /cvsroot/pgsql/src/backend/optimizer/path/pathkeys.c,v 1.1 1999/02/20 15:27:42 momjian Exp $
+ *   $Header: /cvsroot/pgsql/src/backend/optimizer/path/pathkeys.c,v 1.2 1999/02/20 16:28:20 momjian Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -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 32c90392de35f9ea799ef66894f3de4b7459eed1..f9818339b0cb054fcc088c0f8d91d52aa9ce760c 100644 (file)
--- a/src/include/nodes/relation.h
+++ b/src/include/nodes/relation.h
@@ -6,7 +6,7 @@
  *
  * Copyright (c) 1994, Regents of the University of California
  *
- * $Id: relation.h,v 1.26 1999/02/18 00:49:38 momjian Exp $
+ * $Id: relation.h,v 1.27 1999/02/20 16:28:20 momjian Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -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;