Suggestion for docs, section "4.2.3 Subscripts": bounds and base

On Thu, 2025-04-03 at 18:22 +0000, PG Doc comments form wrote:

Page: https://www.postgresql.org/docs/17/sql-expressions.html
Description:

I skimmed over section 4.2 while waiting for a meeting to start and found no
mention of the following two questions that immediately pop up in my mind
when subscripts are mentionned:

Are subscripts 0-based or 1-based?

This question is answered in the documentation of the array data types:
https://www.postgresql.org/docs/current/arrays.html

The array subscript numbers are written within square brackets. By default
PostgreSQL uses a one-based numbering convention for arrays, that is, an
array of n elements starts with array[1] and ends with array[n].

Are slice boundaries inclusive or exclusive?

That becomes clear on the same page:

We can also access arbitrary rectangular slices of an array, or subarrays.
An array slice is denoted by writing lower-bound:upper-bound for one or
more array dimensions. For example, this query retrieves the first item
on Bill's schedule for the first two days of the week:

SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill';

schedule
------------------------
{{meeting},{training}}
(1 row)

Admittedly, there is no exact definition, but the example makes clear that
the boundaries are inclusive.

I don't think that we need to repeat that information.

Yours,
Laurenz Albe

------ Original Message ------

On Mon, 2025-04-07 at 09:07 +0000, Stefan Schmiedl wrote:

Wearing my documentation writer's hat, I agree that the information given on
one page need not be repeated on another one, especially if it's already
cross-referenced.

However, with my documentation reader's glasses on, I would have liked to see
that data there, as it would have allowed me to file subscripts under 
"brackets, mostly 1-based, slices [a:b] are closed intervals" and move on.

As it is, I needed to follow the link to the array page, then to the section 
"Accessing", where I encounter "Now, we can run some queries on the table", 
which implies that I need to at least scan content somewhere above the current 
point to learn about the table structure. Only then I reach the bit about the
first index.

Pages in part I and II (at least, I have not really gone into III and IV) feel like
they're meant to be read completely from top to bottom, not topical like a lookup
in the excellent Reference where I usually can find answers to my questions by
reading a few lines in the description of the option I'm unsure about.

As such, I'd have appreciated the additional information as it would have kept
me in the flow of the page, a flow that its author has worked hard to set up for me.

There is always room for improvement.

It would be great if you could put on both of your hats and come up with
a patch that implements the rather invasive change you are envisioning.
Then we can see if it feels better overall, and we have a concrete basis
for a discussion.

Yours,
Laurenz Albe

On Thursday, April 3, 2025, PG Doc comments form <noreply@postgresql.org>
wrote:

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/17/sql-expressions.html
Description:

I skimmed over section 4.2 while waiting for a meeting to start and found
no
mention of the following two questions that immediately pop up in my mind
when subscripts are mentionned:

Are subscripts 0-based or 1-based?
Are slice boundaries inclusive or exclusive?

The answers depend on the data type to which the [ ] operation is being
applied. And we haven’t really covered data type at this point. So
probably we should just acknowledge these nuances exist and say you can
find the answers for a given data type in its reference page. As a reader,
then, it is registered as an unimportant detail within the overall learning
of the grammar. (I’ll have a more precise answer when I have a moment to
re-read these docs.)

David J.