From 9188aab758b94cc72bdf99a03ae2bbefa95e61f7 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Sat, 20 Feb 1999 16:28:20 +0000
Subject: [PATCH] add pathkeys description.

---
 src/backend/optimizer/path/pathkeys.c | 26 ++++++++++++++++++++++++--
 src/include/nodes/relation.h          |  9 +++++----
 2 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/src/backend/optimizer/path/pathkeys.c b/src/backend/optimizer/path/pathkeys.c
index 996c197350..29f11dcd1c 100644
--- 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 32c90392de..f9818339b0 100644
--- 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;