Date: Tue, 18 Nov 2025 16:28:01 +0900
From: Yugo Nagata <nagata@sraoss.co.jp>
To: Pgsql Hackers <pgsql-hackers@postgresql.org>
Subject: Add a berief general comment on BTScanInsertData's nextkey and
 backward
Message-Id: <20251118162801.27cb13408cb3c9dd3a72cf7d@sraoss.co.jp>
Content-Type: multipart/mixed;
 boundary="Multipart=_Tue__18_Nov_2025_16_28_01_+0900_XZt7R6WNjiY2SCrp"
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: 
	=?us-ascii?Q?8v/3PSFBemQvH1vPaGvuDub/js3rj8Nupb4iBhCRXJZUriRnQjvPSNeZtuPk?=
 =?us-ascii?Q?hOAt+kcGVpzxl7W5b0T7QJQu6hcjHy/bQGR/dtASSx0gaWiU7ALX3C47okFW?=
 =?us-ascii?Q?HI+dVjSKgJq64kG/AoU1b1O0vVPJEDA5Sh3hH3Ov0V+LjQMZHDGlVWGfg6gc?=
 =?us-ascii?Q?hjffRSRBh5Tk1PUsFTwyeCDimc10mDp7e96c8rtSpRRrxCoBrdYUJdNDnU9f?=
 =?us-ascii?Q?22GjhNCaVndGF3f4XoWU/7ucZdOToQ3Gaz7TEotBsqneWfb/erc2KPShErUc?=
 =?us-ascii?Q?4VYOQlFEy9HKcmCknmC18it5Jb4co93Dq47YJzxMu6rpnb8S6yZxAa5PuU6j?=
 =?us-ascii?Q?ER2rMdkRYHZK9qCKiJC0KOKP2jmJWQo7QMUQ3IERW/7Q/UY2NHKn4Gt58GQX?=
 =?us-ascii?Q?v8Hy/0JskV90xeGOrgHpnznlsPRWup5QyOSs14QMuocFOUH3rtTf77CntBwp?=
 =?us-ascii?Q?lCDIEx9DZCk4p3ZdrXotRylkCy4Mqc7ysyG+W1sNjw/dtCHOqc/dREmrtfXs?=
 =?us-ascii?Q?PBJ9GpM8ChGgFSWfx9+56Uv+zsVu7pI7NH8IUfDG05rO8oM19ww6SRJnbvgd?=
 =?us-ascii?Q?N+cwKmuF9IJnTuljFqkT3Tvy5JaiQ6KPEMKOF7GrAU/u2ocFxZcM4Nitn8o2?=
 =?us-ascii?Q?xN6G2gLKUImO5+8PpnU0Yp8pxMaW7lmiviiAebYjpo3RF3Kcc0FqB6hdmDVa?=
 =?us-ascii?Q?I9h1AvV3KaTnm2sWJstbkgr7owbbqkv7bHKjUR46urGRfKn9X8G0IorUAG57?=
 =?us-ascii?Q?+6HEfHxrVESJBXMkhWnf0DPY6EdCs2Za6LSmoe4Dk6vUoMUFNDBGpN+N3F7S?=
 =?us-ascii?Q?1iUcczKZikx/QpYC47v8cQKGYoqQr+xpst2pENS4JWm8z0++HDKbrwEOWOpj?=
 =?us-ascii?Q?JbNufTnHwiI7jmP/CnNwX6NG2rDkwWpOAxqnB0tpoNxxl+DFzThIbma4TTps?=
 =?us-ascii?Q?42nEajg8k8Bs10chkzbQlMz2MmJj+4hYThiVpWO8YhrICzM/9c+DQX3Rmvcc?=
 =?us-ascii?Q?44Vyf1ahTPZ3RAElKBqCkjsxHEK7aFGyhTcNyFaRp4A6WK42Hvs0k8HI4hyz?=
 =?us-ascii?Q?zkma+7kpCFPasi6p9o8R4dGfV7QdAVkFw0GUeUbZVoJjBdAN0tG1WJhyjn8M?=
 =?us-ascii?Q?IL7c+XN1u4HW7NnUL2i9BDwfouT2SYjPOQfTw1u6aSDikLJ1H/Z4cLxhMIbT?=
 =?us-ascii?Q?L/DyTbsJsqGEiPnasu6DZjKeCCZG1qztrDopHazUnAZ5B1wKL8OQjbEu9Rwi?=
 =?us-ascii?Q?bWGsq2/3NzIXTPZbj3Q0AmwxSw305p8I5G59BQYEetPfqGO1D8bkBUeijIkQ?=
 =?us-ascii?Q?M03AjSOSCm7gqat1YfDwqwJhyzq9F24eqdWdrQzVK/uqtTJo816zCjkhDzWb?=
 =?us-ascii?Q?oqDvtwuR5PO3VggQyFhGw+dJVRA5WdZILWbCL6GovzrLh68O+i8uJ3gaCLb8?=
 =?us-ascii?Q?SPGt2HW9Lta3egmxzhZsQPADjAA9E14T1V3pNAwb5AFA9uRAym25yNJExhNX?=
 =?us-ascii?Q?7CdgfEsU09aj07Lxigbk153lBtN+KGpa+vtaMc5Rqu0zN5Ihfa9V4hfU3/Ra?=
 =?us-ascii?Q?Xg9eaDS2VVEcZT/gmW2mwg9+McQV9KE5UXHGnUR+YLza8dVZbxxhaXRz+XSx?=
 =?us-ascii?Q?F3lI5CzJKGtBbfSPUbyN/rLHvRhUEbDG93jzTH4FVyoY?=
X-OriginatorOrg: sraoss.co.jp
X-MS-Exchange-CrossTenant-Network-Message-Id: 
 259ad591-d3b9-4e3b-8a2a-08de267401e6
X-MS-Exchange-CrossTenant-AuthSource: OSZP286MB2160.JPNP286.PROD.OUTLOOK.COM
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 18 Nov 2025 07:28:02.4642
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 75db6c32-352e-4063-ae79-cafb8623f6db
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: 
 h3gmf/+d+WlLO/sDi5AoQPUxvMnNDAGBha3PVpRhTSYcnFd3ew8h0/U7FfQbWXJ3ykkCWfDpp2cl2enM2TnshA==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: OSZP286MB2286
List-Id: <pgsql-hackers.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-hackers@lists.postgresql.org>
List-Owner: <mailto:pgsql-hackers-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-hackers>
Archived-At: 
 <https://www.postgresql.org/message-id/20251118162801.27cb13408cb3c9dd3a72cf7d%40sraoss.co.jp>
Precedence: bulk

--Multipart=_Tue__18_Nov_2025_16_28_01_+0900_XZt7R6WNjiY2SCrp
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit

Hi,

While reading the nbtree codes, I noticed that the comments on
BTScanInsertData no longer describes the meaning of the nextkey and
backward fields. The comment curently only says:

 * See comments in _bt_first for an explanation of the nextkey and backward
 * fields.

Detailed comments used to exit here, but they were removed by
c9c0589fda0e, I guess, because the semantic changed when
the optimazation for backward scans was introduced. However, having
a brief, general description here is still useful for readers.

I've attached a patch that adds the following comment:

+ * nextkey determines how the scankey's boundary is interpreted, and backward
+ * indicates a backward scan.  See comments in _bt_first for a more detailed
+ * explanation of these fields.

What do think?

Regards,
Yugo Nagata

-- 
Yugo Nagata <nagata@sraoss.co.jp>

--Multipart=_Tue__18_Nov_2025_16_28_01_+0900_XZt7R6WNjiY2SCrp
Content-Type: text/x-diff;
 name="add_brief_general_comment_on_BTScanInsertData_nextkey.patch"
Content-Disposition: attachment;
 filename="add_brief_general_comment_on_BTScanInsertData_nextkey.patch"
Content-Transfer-Encoding: 7bit

diff --git a/src/include/access/nbtree.h b/src/include/access/nbtree.h
index 16be5c7a9c1..581e200a3cf 100644
--- a/src/include/access/nbtree.h
+++ b/src/include/access/nbtree.h
@@ -774,8 +774,9 @@ typedef BTStackData *BTStack;
  * bit, but may not when inserting into an INCLUDE index (tuple header value
  * is affected by the NULL-ness of both key and non-key attributes).
  *
- * See comments in _bt_first for an explanation of the nextkey and backward
- * fields.
+ * nextkey determines how the scankey's boundary is interpreted, and backward
+ * indicates a backward scan.  See comments in _bt_first for a more detailed
+ * explanation of these fields.
  *
  * scantid is the heap TID that is used as a final tiebreaker attribute.  It
  * is set to NULL when index scan doesn't need to find a position for a

--Multipart=_Tue__18_Nov_2025_16_28_01_+0900_XZt7R6WNjiY2SCrp--