Re: Add ids to catalog/view columns in documentation

From: "Tristan Partin" <tristan(at)partin(dot)io>
To: "Matthias van de Meent" <boekewurm+postgres(at)gmail(dot)com>
Cc: "pgsql-hackers" <pgsql-hackers(at)lists(dot)postgresql(dot)org>
Subject: Re: Add ids to catalog/view columns in documentation
Date: 2026-11-18 19:56:22
Message-ID: DMYLNSXGCHMI.2CYD1F7BAJJ4K@partin.io
Views: Whole Thread | Raw Message | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

On Wed Nov 18, 2026 at 6:55 PM UTC, Matthias van de Meent wrote:
> On Wed, 18 Nov 2026 at 19:34, Tristan Partin <tristan(at)partin(dot)io> wrote:
>>
>> When referring to columns within catalog/views, I found it annoying that
>> they were not linkable. You could only link to something higher level
>> and then the reader was left to scroll and search for the column
>> definition.
>>
>> I think adding IDs to column definitions would be a good idea. In this
>> initial patch, I've only decided to change pg_stat_statements
>> documentation. It should make it easier to view necessary changes and
>> visualize the impact of this change within the documentation.
>
> I like minimal changes, but you're stretching it a bit. I think I
> like the idea behind the patch, though.
>
>> Things that have changed:
>>
>> - Octothorope
>
> TIL. Alternatively: "#", pound, or sharp.

I actually misspelled it! Octothorpe.

>> is now visible when hovering a column within the column
>> definitions of pg_stat_statements and pg_stat_statements_info views
>
> What is it that you hover? The document's column, the document's row
> that describes the view column, or the table cell that has the name of
> the view column? I assume the last of these?

If you are looking at the pg_stat_statements columns, hover the area
containing the column name and type. That amounts to a:

<p class="column_definition">...</p>

>> - Copying that link and pasting it in a new tab will take you directly
>> to the row of the column definition with a background color change to
>> highlight what was linked to. I understand that the CSS we use in-tree
>> is not the same CSS that is used on postgresql.org. I could make
>> a similar CSS change there as well if this seems like a good
>> direction.
>>
>> I think there is discussion to be had about ID names. For instance,
>> I used the format <view>-view.<column>. Should we do that for all views?
>
> I think I'd like "catalog [sep] <schema>.<objname>[.<column>]` better,
> as it's simpler to remember, copy-paste, and read. [sep] could be any
> useful symbol; "." would be a natural fit but : or - could work, too.

Part of the problem is that we don't necessarily seem to be very
consistent with IDs already.

Here is the ID of the pg_stat_statements view documentation:
PGSTATSTATEMENTS-PG-STAT-STATEMENTS. And then here is the ID of
pg_stat_activity: MONITORING-PG-STAT-ACTIVITY-VIEW.

So we seem to use a prefix (pgstatstatements vs monitoring)
consistently, but whether we append the word view is not. I wonder if we
should rectify that to make things more consistent and predictable as
you said.

>> How should IDs for catalog columns look? For pg_stat_statements
>> specifically, should I have used an ID like
>> pgstatstatements-<view>.<column>? Maybe there isn't a one size fits all
>> solution.
>
> With the above solution, you could select the extension's name as schema prefix.

--
Tristan Partin
PostgreSQL Contributors Team
AWS (https://aws.amazon.com)

In response to

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Andres Freund 2026-11-18 20:07:47 Re: CI slowdown due to PG_TEST_INITDB_EXTRA_OPTS
Previous Message Joao Rito 2026-11-18 19:47:41 Re: EXPLAIN ANALYZE overcounts MERGE inserts suppressed by triggers