postgresql/src/backend/nodes
Tom Lane 31f38f28b0 Redesign the planner's handling of index-descent cost estimation.
Historically we've used a couple of very ad-hoc fudge factors to try to
get the right results when indexes of different sizes would satisfy a
query with the same number of index leaf tuples being visited.  In
commit 21a39de580 I tweaked one of these
fudge factors, with results that proved disastrous for larger indexes.
Commit bf01e34b55 fudged it some more,
but still with not a lot of principle behind it.

What seems like a better way to address these issues is to explicitly model
index-descent costs, since that's what's really at stake when considering
diferent indexes with similar leaf-page-level costs.  We tried that once
long ago, and found that charging random_page_cost per page descended
through was way too much, because upper btree levels tend to stay in cache
in real-world workloads.  However, there's still CPU costs to think about,
and the previous fudge factors can be seen as a crude attempt to account
for those costs.  So this patch replaces those fudge factors with explicit
charges for the number of tuple comparisons needed to descend the index
tree, plus a small charge per page touched in the descent.  The cost
multipliers are chosen so that the resulting charges are in the vicinity of
the historical (pre-9.2) fudge factors for indexes of up to about a million
tuples, while not ballooning unreasonably beyond that, as the old fudge
factor did (even more so in 9.2).

To make this work accurately for btree indexes, add some code that allows
extraction of the known root-page height from a btree.  There's no
equivalent number readily available for other index types, but we can use
the log of the number of index pages as an approximate substitute.

This seems like too much of a behavioral change to risk back-patching,
but it should improve matters going forward.  In 9.2 I'll just revert
the fudge-factor change.
2013-01-11 12:56:58 -05:00
..
bitmapset.c Update copyrights for 2013 2013-01-01 17:15:01 -05:00
copyfuncs.c Update copyrights for 2013 2013-01-01 17:15:01 -05:00
equalfuncs.c Update copyrights for 2013 2013-01-01 17:15:01 -05:00
list.c Update copyrights for 2013 2013-01-01 17:15:01 -05:00
Makefile Remove cvs keywords from all files. 2010-09-20 22:08:53 +02:00
makefuncs.c Update copyrights for 2013 2013-01-01 17:15:01 -05:00
nodeFuncs.c Update copyrights for 2013 2013-01-01 17:15:01 -05:00
nodes.c Update copyrights for 2013 2013-01-01 17:15:01 -05:00
outfuncs.c Redesign the planner's handling of index-descent cost estimation. 2013-01-11 12:56:58 -05:00
params.c Update copyrights for 2013 2013-01-01 17:15:01 -05:00
print.c Update copyrights for 2013 2013-01-01 17:15:01 -05:00
read.c Update copyrights for 2013 2013-01-01 17:15:01 -05:00
readfuncs.c Update copyrights for 2013 2013-01-01 17:15:01 -05:00
README Remove useless whitespace at end of lines 2010-11-23 22:34:55 +02:00
tidbitmap.c Update copyrights for 2013 2013-01-01 17:15:01 -05:00
value.c Update copyrights for 2013 2013-01-01 17:15:01 -05:00

src/backend/nodes/README

Node Structures
===============

Andrew Yu (11/94)

Introduction
------------

The current node structures are plain old C structures. "Inheritance" is
achieved by convention. No additional functions will be generated. Functions
that manipulate node structures reside in this directory.


FILES IN THIS DIRECTORY (src/backend/nodes/)

    General-purpose node manipulation functions:
	copyfuncs.c	- copy a node tree
	equalfuncs.c	- compare two node trees
	outfuncs.c	- convert a node tree to text representation
	readfuncs.c	- convert text representation back to a node tree
	makefuncs.c	- creator functions for some common node types
	nodeFuncs.c	- some other general-purpose manipulation functions

    Specialized manipulation functions:
	bitmapset.c	- Bitmapset support
	list.c		- generic list support
	params.c	- Param support
	tidbitmap.c	- TIDBitmap support
	value.c		- support for Value nodes

FILES IN src/include/nodes/

    Node definitions:
	nodes.h		- define node tags (NodeTag)
	primnodes.h	- primitive nodes
	parsenodes.h	- parse tree nodes
	plannodes.h	- plan tree nodes
	relation.h	- planner internal nodes
	execnodes.h	- executor nodes
	memnodes.h	- memory nodes
	pg_list.h	- generic list


Steps to Add a Node
-------------------

Suppose you wanna define a node Foo:

1. Add a tag (T_Foo) to the enum NodeTag in nodes.h.  (If you insert the
   tag in a way that moves the numbers associated with existing tags,
   you'll need to recompile the whole tree after doing this.  It doesn't
   force initdb though, because the numbers never go to disk.)
2. Add the structure definition to the appropriate include/nodes/???.h file.
   If you intend to inherit from, say a Plan node, put Plan as the first field
   of your struct definition.
3. If you intend to use copyObject, equal, nodeToString or stringToNode,
   add an appropriate function to copyfuncs.c, equalfuncs.c, outfuncs.c
   and readfuncs.c accordingly.  (Except for frequently used nodes, don't
   bother writing a creator function in makefuncs.c)  The header comments
   in those files give general rules for whether you need to add support.
4. Add cases to the functions in nodeFuncs.c as needed.  There are many
   other places you'll probably also need to teach about your new node
   type.  Best bet is to grep for references to one or two similar existing
   node types to find all the places to touch.


Historical Note
---------------

Prior to the current simple C structure definitions, the Node structures
used a pseudo-inheritance system which automatically generated creator and
accessor functions. Since every node inherited from LispValue, the whole thing
was a mess. Here's a little anecdote:

    LispValue definition -- class used to support lisp structures
    in C.  This is here because we did not want to totally rewrite
    planner and executor code which depended on lisp structures when
    we ported postgres V1 from lisp to C. -cim 4/23/90