Feedback-ID: id4a34324:Fastmail
Date: Fri, 13 Mar 2026 12:24:53 -0400
From: Andres Freund <andres@anarazel.de>
To: Ayush Tiwari <ayushtiwari.slg01@gmail.com>
Cc: pgsql-hackers@postgresql.org
Subject: Re: tid_blockno() and tid_offset() accessor functions
Message-ID: <o6f7ha2ceasabwjvrh5a25rdvujjyvq7kqhfs43lthlgwpjb6m@dp7qkki576ay>
References: 
 <CAJTYsWUzok2+mvSYkbVUwq_SWWg-GdHqCuYumN82AU97SjwjCA@mail.gmail.com>
 <CAJTYsWVK6rw++WU94=gFk5ZR5ZXhT3BYOFxhm6tT9xOGG-drnA@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: 
 <CAJTYsWVK6rw++WU94=gFk5ZR5ZXhT3BYOFxhm6tT9xOGG-drnA@mail.gmail.com>
Archived-At: 
 <https://www.postgresql.org/message-id/o6f7ha2ceasabwjvrh5a25rdvujjyvq7kqhfs43lthlgwpjb6m%40dp7qkki576ay>
Precedence: bulk

Hi,

On 2026-03-08 01:13:13 +0530, Ayush Tiwari wrote:
> From 92e3657d85b13355563ba4c447ddf89fcb4c4b3e Mon Sep 17 00:00:00 2001
> From: Ayush Tiwari <ayushtiwari.slg01@gmail.com>
> Date: Sat, 7 Mar 2026 18:27:36 +0000
> Subject: [PATCH v2] Add tid_block() and tid_offset() accessor functions
>
> Add two new built-in SQL functions to extract the components of a tid
> (tuple identifier) value:
>
>   tid_block(tid) -> bigint   -- extract block number
>   tid_offset(tid)  -> integer  -- extract offset number
>
> These provide a clean, efficient alternative to the common workaround
> of ctid::text::point for decomposing TID values. The text-based hack
> is fragile, inefficient, and unavailable outside of SQL contexts.
>
> tid_block() returns int8 (bigint) because BlockNumber is uint32,
> which exceeds the range of int4. tid_offset() returns int4 (integer)
> because OffsetNumber is uint16, which fits safely in int4.
>
> Both functions use the NoCheck accessor variants from itemptr.h,
> are marked leakproof, and include regression tests covering typical
> values, boundary conditions, NULL handling, and round-trip identity.


> +++ b/doc/src/sgml/func/func-tid.sgml
> @@ -0,0 +1,73 @@
> + <sect1 id="functions-tid">
> +  <title>TID Functions</title>
> +
> +  <indexterm zone="functions-tid">
> +   <primary>TID</primary>
> +   <secondary>functions</secondary>
> +  </indexterm>
> +
> +  <indexterm>
> +   <primary>tid_block</primary>
> +  </indexterm>
> +
> +  <indexterm>
> +   <primary>tid_offset</primary>
> +  </indexterm>
> +
> +  <para>
> +   For the <type>tid</type> data type (described in <xref
> +   linkend="datatype-oid"/>), <xref linkend="functions-tid-table"/>

Seems odd to reference the datatype-oid, that's barely mentioning the tid type
and tid is not an oid like type either (like e.g. regtype is).


> +   shows the functions available for extracting the block number and
> +   tuple offset.  These functions are commonly used with the
> +   <structfield>ctid</structfield> system column.
> +  </para>

I know some other places do that too, but "shows the functions" sounds odd to
me. I'd just say "These are listed in ..." or such.

I'd remove the "available for extracting the block number and tuple offset",
as that's bound to become inaccurate and just restates the table contents.


> --- a/doc/src/sgml/func/func.sgml
> +++ b/doc/src/sgml/func/func.sgml
> @@ -59,6 +59,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
>  &func-formatting;
>  &func-datetime;
>  &func-enum;
> +&func-tid;
>  &func-geometry;
>  &func-net;
>  &func-textsearch;

I'd add it somewhere more alphabetically fitting. Unfortunately the list isn't
fully ordered right now, but no need to make it even worse...


Greetings,

Andres Freund