Re: Documentation of bt_page_items()'s ctid field

On 12/30/2014 04:08 AM, Peter Geoghegan wrote:
> Attached documentation patch describes the purpose of
> bt_page_items()'s ctid field. This has come up enough times in
> disaster recovery or testing scenarios that I feel it's worth drawing
> particular attention to.

How much detail on the b-tree internals do we want to put in the 
pageinspect documentation? I can see that being useful, but should we 
also explain e.g. that the first item on each (non-rightmost) page is 
the high key?

> +      Note that <structfield>ctid</> addresses a heap tuple if the
> +      page under consideration is a B-Tree leaf page.  Otherwise, for
> +      internal B-Tree pages <structfield>ctid</> addresses a page in
> +      the B-Tree itself (excluding the root page if and only if there
> +      has not yet been a root page split, as in the example above).
> +      These internally referenced pages are child pages, and may
> +      themselves be leaf pages or internal pages.

I had a hard time understanding the remark about the root page. But in 
any case, if you look at the flags set e.g. with bt_page_stats(), the 
root page is flagged as also being a leaf page, when it is the only page 
in the index. So the root page is considered also a leaf page in that case.

I'd suggest saying the same thing (or more) with fewer words:

In a B-tree leaf page, <structfield>ctid</> points to a heap tuple. In 
an internal page, it points to another page in the index itself, and the 
offset number part (the second number) of the ctid field is ignored.

- Heikki