Re: documentation on HOT

[Jonathan S. Katz]

On 2/6/22 8:56 PM, David G. Johnston wrote:

On Sun, Feb 6, 2022 at 6:08 PM Jonathan S. Katz <jk...@postgresql.org <mailto:jk...@postgresql.org>> wrote:

    Given the importance of HOT, it seems like this would be a good
    topic to
    document. I would suggest something higher-level for general users in
    the "Indexes"[4] section, and something lower-level in internals[5]
    (which could perhaps be derived from [2]).

    Thoughts on this?

I'm doubting there is any disagreement that this is needed.  Three of us said as much recently [1] while discussing a user question regarding our documentation for expression indexes.

I did try to search for previous discussion on this (not well enough apparently) and I was unable to find the thread. That is also part of the challenge with the term HOT.

I presently haven't felt moved to fill the need myself as so I was fine with at least providing a high-level summary in the glossary which we also the general user to understand the idea without having to dive into the README.

I don't agree that such an explanation belongs in the glossary. That feels like it would be too brief, and I think that does a disservice to the topic and our users. I agree with Bruce's point that we should have a new section (or subsection). As I mentioned in my previous post, given HOT involves indexing, I would suggest putting it there. I think that something that follows the general outline of Laurenz's post would satisfy the user requirements. It explains at a high level what HOT is, it's advantages, and how it works.

  The details for internals can continue to be handled there in the interest of at least getting something committed for the majority of users.

Thanks,

Jonathan

I do think there should be some reference of it to the docs. Even if we have a page in the "Internals" section that says "For more information on how HOT works, please see <link>". That said, is there any reasoning why the HOT README (or something similar to it) is not in the "Internals" section of the documentation, similar to other indexing topics?

OpenPGP_signature
Description: OpenPGP digital signature