Re: LIMIT NULL

Lists: pgsql-hackers
From: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
To: PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: LIMIT NULL
Date: 2009-01-31 22:28:15
Message-ID: 781ECF4C-ACE1-45CC-BB0C-FBE59A7AECA0@kineticode.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

Howdy,

Is it intentional that `LIMIT NULL` means the same as `LIMIT ALL`? If
so, I'd like to submit a patch to document it, because I've found it
useful in SQL functions:

http://justatheory.com/computers/databases/postgresql/dynamic-limit.html

Thanks,

David


From: Bruce Momjian <bruce(at)momjian(dot)us>
To: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
Cc: PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: LIMIT NULL
Date: 2009-02-02 17:58:21
Message-ID: 200902021758.n12HwLo01930@momjian.us
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

David E. Wheeler wrote:
> Howdy,
>
> Is it intentional that `LIMIT NULL` means the same as `LIMIT ALL`? If
> so, I'd like to submit a patch to document it, because I've found it
> useful in SQL functions:
>
> http://justatheory.com/computers/databases/postgresql/dynamic-limit.html

Uh, I figure LIMIT NULL should return no rows.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +


From: Robert Haas <robertmhaas(at)gmail(dot)com>
To: Bruce Momjian <bruce(at)momjian(dot)us>
Cc: "David E(dot) Wheeler" <david(at)kineticode(dot)com>, PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: LIMIT NULL
Date: 2009-02-02 18:03:34
Message-ID: 603c8f070902021003k19a79114vdcd23fe0577d0657@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Mon, Feb 2, 2009 at 12:58 PM, Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> David E. Wheeler wrote:
>> Howdy,
>>
>> Is it intentional that `LIMIT NULL` means the same as `LIMIT ALL`? If
>> so, I'd like to submit a patch to document it, because I've found it
>> useful in SQL functions:
>>
>> http://justatheory.com/computers/databases/postgresql/dynamic-limit.html
>
> Uh, I figure LIMIT NULL should return no rows.

Wouldn't that be LIMIT 0? Per SQL spec, doesn't NULL refer to an
unknown quantity? Making it mean ALL seems more useful than making it
mean 0, since you can already write 0 if you want 0.

...Robert


From: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
To: Bruce Momjian <bruce(at)momjian(dot)us>
Cc: PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: LIMIT NULL
Date: 2009-02-02 18:04:11
Message-ID: 70A4F459-E2F8-44CA-8229-7FC3FB85E977@kineticode.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Feb 2, 2009, at 9:58 AM, Bruce Momjian wrote:

>> Is it intentional that `LIMIT NULL` means the same as `LIMIT ALL`? If
>> so, I'd like to submit a patch to document it, because I've found it
>> useful in SQL functions:
>>
>> http://justatheory.com/computers/databases/postgresql/dynamic-limit.html
>
> Uh, I figure LIMIT NULL should return no rows.

Well, LIMIT 0 does that, and it's useful to have a type-compatible
option to LIMIT that allows it to return all rows. And I say type-
compatible, because you can't pass "ALL" as a bare string via a
function like COALESCE.

Best,

David


From: "Kevin Grittner" <Kevin(dot)Grittner(at)wicourts(dot)gov>
To: "David E(dot) Wheeler" <david(at)kineticode(dot)com>, "Bruce Momjian" <bruce(at)momjian(dot)us>
Cc: "PostgreSQL Hackers" <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: LIMIT NULL
Date: 2009-02-02 18:09:28
Message-ID: 4986E278.EE98.0025.0@wicourts.gov
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

>>> Bruce Momjian <bruce(at)momjian(dot)us> wrote:
> David E. Wheeler wrote:
>> Is it intentional that `LIMIT NULL` means the same as `LIMIT ALL`?

> Uh, I figure LIMIT NULL should return no rows.

Why? Since the normal meaning of NULL is "value unknown or does not
apply" it would seem to be most reasonable, if it's going to be
accepted in a LIMIT clause, to have it mean "the LIMIT does not
apply".

Plus, if it has been accepted with the "no limit" semantics, wouldn't
it require a really good reason to break backwards compatibility?

-Kevin


From: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
To: Bruce Momjian <bruce(at)momjian(dot)us>
Cc: "David E(dot) Wheeler" <david(at)kineticode(dot)com>, PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: LIMIT NULL
Date: 2009-02-02 18:17:35
Message-ID: 23028.1233598655@sss.pgh.pa.us
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

Bruce Momjian <bruce(at)momjian(dot)us> writes:
> Uh, I figure LIMIT NULL should return no rows.

It's worked the way it does now since 7.1, and no one has complained;
in fact we've gotten bug reports when it was broken by the int8-limit
patch. So there are people depending on the behavior.

regards, tom lane


From: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
To: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
Cc: Bruce Momjian <bruce(at)momjian(dot)us>, PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: LIMIT NULL
Date: 2009-02-02 19:03:29
Message-ID: B29CA2FD-2638-4D0C-BD8E-A2604B7B9955@kineticode.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Feb 2, 2009, at 10:17 AM, Tom Lane wrote:

> It's worked the way it does now since 7.1, and no one has complained;
> in fact we've gotten bug reports when it was broken by the int8-limit
> patch. So there are people depending on the behavior.

Yeah, it's very useful. Here's a patch for the docs about it.

Thanks,

David

Attachment Content-Type Size
limit-null.patch application/octet-stream 704 bytes
unknown_filename text/plain 1 byte

From: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
To: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
Cc: Bruce Momjian <bruce(at)momjian(dot)us>, PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: LIMIT NULL
Date: 2009-02-02 20:43:42
Message-ID: 1502.1233607422@sss.pgh.pa.us
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

"David E. Wheeler" <david(at)kineticode(dot)com> writes:
> On Feb 2, 2009, at 10:17 AM, Tom Lane wrote:
>> It's worked the way it does now since 7.1, and no one has complained;
>> in fact we've gotten bug reports when it was broken by the int8-limit
>> patch. So there are people depending on the behavior.

> Yeah, it's very useful. Here's a patch for the docs about it.

Seems to me that the SELECT reference page is a more appropriate place
for this type of detail. I've applied a patch there.

regards, tom lane


From: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
To: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
Cc: Bruce Momjian <bruce(at)momjian(dot)us>, PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: LIMIT NULL
Date: 2009-02-02 20:52:50
Message-ID: 449BF3E3-FCC2-4958-808F-B8B40D7CA1FB@kineticode.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Feb 2, 2009, at 12:43 PM, Tom Lane wrote:

>> Yeah, it's very useful. Here's a patch for the docs about it.
>
> Seems to me that the SELECT reference page is a more appropriate place
> for this type of detail. I've applied a patch there.

What about both? The LIMIT page is the first page I'd look for it, and
the ALL note is there…

Thanks,

David


From: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
To: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
Cc: Bruce Momjian <bruce(at)momjian(dot)us>, PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: LIMIT NULL
Date: 2009-02-02 21:10:15
Message-ID: 2511.1233609015@sss.pgh.pa.us
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

"David E. Wheeler" <david(at)kineticode(dot)com> writes:
> On Feb 2, 2009, at 12:43 PM, Tom Lane wrote:
>> Seems to me that the SELECT reference page is a more appropriate place
>> for this type of detail. I've applied a patch there.

> What about both?

We don't really have space to document every little niggling detail in
two places; if we did that, the main docs would become unreadably dense.

(I think it's justifiable to regard this as a "niggling detail" because
no one's asked about it before.)

regards, tom lane


From: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
To: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
Cc: Bruce Momjian <bruce(at)momjian(dot)us>, PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: LIMIT NULL
Date: 2009-02-02 21:44:15
Message-ID: DEC99081-56C9-4570-AB41-1B94FE2DCF7D@kineticode.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Feb 2, 2009, at 1:10 PM, Tom Lane wrote:

> "David E. Wheeler" <david(at)kineticode(dot)com> writes:
>> On Feb 2, 2009, at 12:43 PM, Tom Lane wrote:
>>> Seems to me that the SELECT reference page is a more appropriate
>>> place
>>> for this type of detail. I've applied a patch there.
>
>> What about both?
>
> We don't really have space to document every little niggling detail in
> two places; if we did that, the main docs would become unreadably
> dense.

What, disk space? What do you mean by “space”?

> (I think it's justifiable to regard this as a "niggling detail"
> because
> no one's asked about it before.)

Sure.

Best,

David


From: Robert Haas <robertmhaas(at)gmail(dot)com>
To: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
Cc: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, Bruce Momjian <bruce(at)momjian(dot)us>, PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: LIMIT NULL
Date: 2009-02-02 21:52:53
Message-ID: 603c8f070902021352q4274ed02gf4617290145e5d49@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

>> We don't really have space to document every little niggling detail in
>> two places; if we did that, the main docs would become unreadably dense.
>
> What, disk space? What do you mean by "space"?

Brain space.

...Robert


From: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
To: Robert Haas <robertmhaas(at)gmail(dot)com>
Cc: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, Bruce Momjian <bruce(at)momjian(dot)us>, PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: LIMIT NULL
Date: 2009-02-03 16:29:06
Message-ID: 092C1B1D-2A7A-40D6-BFA7-64494470E748@kineticode.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Feb 2, 2009, at 1:52 PM, Robert Haas wrote:

>>> We don't really have space to document every little niggling
>>> detail in
>>> two places; if we did that, the main docs would become unreadably
>>> dense.
>>
>> What, disk space? What do you mean by "space"?
>
> Brain space.

Heh. Okay. Well, should there be a separate LIMIT/OFFSET documentation
page? Why have this stuff in two places? I had assumed that the LIMIT/
OFFSET page would have all the specifies on these clauses, and that
the SELECT page (which is kind of overwhelming as it is) would refer
to it…

Thanks,

David


From: Andrew Dunstan <andrew(at)dunslane(dot)net>
To: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
Cc: Robert Haas <robertmhaas(at)gmail(dot)com>, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, Bruce Momjian <bruce(at)momjian(dot)us>, PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: LIMIT NULL
Date: 2009-02-03 16:40:15
Message-ID: 4988736F.4080001@dunslane.net
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

David E. Wheeler wrote:
>
> Heh. Okay. Well, should there be a separate LIMIT/OFFSET documentation
> page? Why have this stuff in two places? I had assumed that the
> LIMIT/OFFSET page would have all the specifies on these clauses, and
> that the SELECT page (which is kind of overwhelming as it is) would
> refer to it…
>
>

We have one page per main SQL verb (e.g. SELECT or CREATE TABLE). I
don't think we want to break it up more than that. One page for each
clause would be a nightmare to maintain.

cheers

andrew


From: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
To: Andrew Dunstan <andrew(at)dunslane(dot)net>
Cc: Robert Haas <robertmhaas(at)gmail(dot)com>, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, Bruce Momjian <bruce(at)momjian(dot)us>, PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: LIMIT NULL
Date: 2009-02-03 16:42:30
Message-ID: ADCF06DE-8958-44D0-9FC5-1DC54293ED84@kineticode.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Feb 3, 2009, at 8:40 AM, Andrew Dunstan wrote:

> We have one page per main SQL verb (e.g. SELECT or CREATE TABLE). I
> don't think we want to break it up more than that. One page for each
> clause would be a nightmare to maintain.

Then should the LIMIT/OFFSET page go away?

Best,

David


From: Rick Vernam <rickv(at)hobi(dot)com>
To: pgsql-hackers(at)postgresql(dot)org
Subject: Re: LIMIT NULL
Date: 2009-02-03 18:33:11
Message-ID: 200902031233.11726.rickv@hobi.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Tuesday 03 February 2009 10:42:30 am David E. Wheeler wrote:
> On Feb 3, 2009, at 8:40 AM, Andrew Dunstan wrote:
> > We have one page per main SQL verb (e.g. SELECT or CREATE TABLE). I
> > don't think we want to break it up more than that. One page for each
> > clause would be a nightmare to maintain.
>
> Then should the LIMIT/OFFSET page go away?
>
> Best,
>
> David

I agree that it's confusing when one piece of LIMIT documentation is not with
the rest.

If looking for information about limits, I would go here:
http://www.postgresql.org/docs/8.3/static/queries-limit.html
and consider it to be an authoritative source.
If somebody told me something about LIMIT that was not on that page, I'd say
to them to go back and double check the docs...


From: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
To: Rick Vernam <rickv(at)hobi(dot)com>
Cc: pgsql-hackers(at)postgresql(dot)org
Subject: Re: LIMIT NULL
Date: 2009-02-03 21:06:27
Message-ID: 15052.1233695187@sss.pgh.pa.us
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

Rick Vernam <rickv(at)hobi(dot)com> writes:
> If looking for information about limits, I would go here:
> http://www.postgresql.org/docs/8.3/static/queries-limit.html
> and consider it to be an authoritative source.

The reference documentation is *always* intended to be more complete and
more authoritative than the narrative description. If you don't think
so then you need to readjust your expectations.

regards, tom lane


From: Andrew Dunstan <andrew(at)dunslane(dot)net>
To: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
Cc: Robert Haas <robertmhaas(at)gmail(dot)com>, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, Bruce Momjian <bruce(at)momjian(dot)us>, PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: LIMIT NULL
Date: 2009-02-03 21:30:27
Message-ID: 4988B773.1040001@dunslane.net
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

David E. Wheeler wrote:
> On Feb 3, 2009, at 8:40 AM, Andrew Dunstan wrote:
>
>> We have one page per main SQL verb (e.g. SELECT or CREATE TABLE). I
>> don't think we want to break it up more than that. One page for each
>> clause would be a nightmare to maintain.
>
> Then should the LIMIT/OFFSET page go away?
>
>

I was referring to the reference section. I see you were referring to
the more descriptive but probably less complete Section II.

I see Section II says at the beginning: "Readers looking for a complete
description of a particular command should look into Part VI
<http://www.postgresql.org/docs/current/static/reference.html>.".

cheers

andrew


From: Rick Vernam <rickv(at)hobi(dot)com>
To: pgsql-hackers(at)postgresql(dot)org
Subject: Re: LIMIT NULL
Date: 2009-02-03 21:31:11
Message-ID: 200902031531.11626.rickv@hobi.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Tuesday 03 February 2009 3:06:27 pm Tom Lane wrote:
> Rick Vernam <rickv(at)hobi(dot)com> writes:
> > If looking for information about limits, I would go here:
> > http://www.postgresql.org/docs/8.3/static/queries-limit.html
> > and consider it to be an authoritative source.
>
> The reference documentation is *always* intended to be more complete and
> more authoritative than the narrative description. If you don't think
> so then you need to readjust your expectations.
>
> regards, tom lane

very well, I did not know that.
expectations readjusted. thanks.


From: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
To: Andrew Dunstan <andrew(at)dunslane(dot)net>
Cc: Robert Haas <robertmhaas(at)gmail(dot)com>, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, Bruce Momjian <bruce(at)momjian(dot)us>, PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: LIMIT NULL
Date: 2009-02-03 21:37:59
Message-ID: 0537CE75-9CFC-4D59-A748-E15588BF2CEE@kineticode.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Feb 3, 2009, at 1:30 PM, Andrew Dunstan wrote:

> I was referring to the reference section. I see you were referring
> to the more descriptive but probably less complete Section II.

Yes.

> I see Section II says at the beginning: "Readers looking for a
> complete description of a particular command should look into Part
> VI <http://www.postgresql.org/docs/current/static/reference.html>.".

Yes, but not on the page for the command, FWIW, which one often
reaches by doing a search on "LIMIT". Finding that page via search, I
would assume that it was comprehensive.

The division between what's documented in section II and what's in
section VI seems a but fuzzy, neh?

Best,

David


From: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
To: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
Cc: Rick Vernam <rickv(at)hobi(dot)com>, pgsql-hackers(at)postgresql(dot)org
Subject: Re: LIMIT NULL
Date: 2009-02-03 22:55:53
Message-ID: E39996F9-4509-4E3D-985A-B3C2C81DEBC4@kineticode.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Feb 3, 2009, at 1:06 PM, Tom Lane wrote:

> The reference documentation is *always* intended to be more complete
> and
> more authoritative than the narrative description. If you don't think
> so then you need to readjust your expectations.

Yes, but I didn't even know I was looking at a brief overview
document; I found it through search and thought it must be
authoritative.

David


From: Svenne Krap <svenne(at)krap(dot)dk>
To: pgsql-hackers(at)postgresql(dot)org
Subject: Re: LIMIT NULL
Date: 2009-02-04 13:05:21
Message-ID: 49899291.3030303@krap.dk
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Rick Vernam wrote:
>> The reference documentation is *always* intended to be more complete and
>> more authoritative than the narrative description. If you don't think
>> so then you need to readjust your expectations.
> very well, I did not know that.
> expectations readjusted. thanks.

Me neither. I wonder how many other long term users (I have used pgsql
for more than a decade - 6.2 was my first version if memory serves)
and have never caught that nuance either.

Maybe that should be printed as a note on the "narrative description
pages".. something like: "Note this is a simplified introduction to
the subject. For authorative description please see topic x in section
y (and link to it of course ;))

Svenne
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkmJkpEACgkQPPDUIBpvWQsY2ACdG3y9Ho2vW3z2OKePTy9jCkAq
QqEAnAn9J+ZOnAsohnPqbGCtLbfC6e7G
=FiGn
-----END PGP SIGNATURE-----


From: Andrew Dunstan <andrew(at)dunslane(dot)net>
To: Svenne Krap <svenne(at)krap(dot)dk>
Cc: pgsql-hackers(at)postgresql(dot)org
Subject: Re: LIMIT NULL
Date: 2009-02-04 13:25:31
Message-ID: 4989974B.9010202@dunslane.net
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

Svenne Krap wrote:
> Rick Vernam wrote:
>
>>> The reference documentation is *always* intended to be more complete and
>>> more authoritative than the narrative description. If you don't think
>>> so then you need to readjust your expectations.
>>>
>> very well, I did not know that.
>> expectations readjusted. thanks.
>>
>
> Me neither. I wonder how many other long term users (I have used pgsql
> for more than a decade - 6.2 was my first version if memory serves)
> and have never caught that nuance either.
>
> Maybe that should be printed as a note on the "narrative description
> pages".. something like: "Note this is a simplified introduction to
> the subject. For authorative description please see topic x in section
> y (and link to it of course ;))
>

In effect it does say that - perhaps not quite as explicitly as you
might have wanted. It says: "The information in this part is presented
in a narrative fashion in topical units. Readers looking for a complete
description of a particular command should look into Part VI. " (the
"PART VI" is a link).

cheers

andrew


From: Svenne Krap <svenne(at)krap(dot)dk>
To: pgsql-hackers(at)postgresql(dot)org
Subject: Re: LIMIT NULL
Date: 2009-02-04 14:41:55
Message-ID: 4989A933.2000103@krap.dk
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

Andrew Dunstan wrote:
>> Me neither. I wonder how many other long term users (I have used pgsql
>> for more than a decade - 6.2 was my first version if memory serves)
>> and have never caught that nuance either.
>>
>> Maybe that should be printed as a note on the "narrative description
>> pages".. something like: "Note this is a simplified introduction to
>> the subject. For authorative description please see topic x in section
>> y (and link to it of course ;))
>>
>
> In effect it does say that - perhaps not quite as explicitly as you
> might have wanted. It says: "The information in this part is presented
> in a narrative fashion in topical units. Readers looking for a
> complete description of a particular command should look into Part VI.
> " (the "PART VI" is a link).
Well... I meant on EVERY single page outside section VI (or whatever is
considered cannonical)

I believe most users today search instead of browse documentation... I
certainly do... that I have a decade of postgresql experience just helps
me to know that section VI.I is extremly important (but I learned that
through trial and error not by reading a small hint).

If I google "postgresql limit" the second link links to
http://www.postgresql.org/docs/8.3/interactive/queries-limit.html (for
some reason google strongly prefers version 7.3).
That page (which is the first you see if you search your way in) gives
me the following impressions (i.e. given my information gathering
heuristics):
- domain postgresql.org (=official)
- in the page title it states: PostgreSQL 8.3.5 Documentation (=yeah,
right place)
- Chapter 7. Queries (=reasonable)
- 7.6. LIMIT and OFFSET (= home free ;)

Which gives me every indication that I am the right place. Nowhere on
this page is the note, that there exists a better place (experience has
shown me, that the SELECT page in the SQL reference is far more
detailed, but that is unknown for a newbie user).

What I would like is that EVERY page, that is considered non-cannonical,
for the sake of useability has an end-note, that a better (more detailed
and more "correct") place exists and an indication of where to go..
which I believe would be
http://www.postgresql.org/docs/8.3/interactive/sql-select.html in the
choosen example.

/Svenne


From: Rick Vernam <rickv(at)hobi(dot)com>
To: pgsql-hackers(at)postgresql(dot)org
Subject: Re: LIMIT NULL
Date: 2009-02-04 15:24:26
Message-ID: 200902040924.26857.rickv@hobi.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Wednesday 04 February 2009 8:41:55 am Svenne Krap wrote:
> Andrew Dunstan wrote:
> >> Me neither. I wonder how many other long term users (I have used pgsql
> >> for more than a decade - 6.2 was my first version if memory serves)
> >> and have never caught that nuance either.
> >>
> >> Maybe that should be printed as a note on the "narrative description
> >> pages".. something like: "Note this is a simplified introduction to
> >> the subject. For authorative description please see topic x in section
> >> y (and link to it of course ;))
> >
> > In effect it does say that - perhaps not quite as explicitly as you
> > might have wanted. It says: "The information in this part is presented
> > in a narrative fashion in topical units. Readers looking for a
> > complete description of a particular command should look into Part VI.
> > " (the "PART VI" is a link).
>
> Well... I meant on EVERY single page outside section VI (or whatever is
> considered cannonical)
>
> I believe most users today search instead of browse documentation... I
> certainly do... that I have a decade of postgresql experience just helps
> me to know that section VI.I is extremly important (but I learned that
> through trial and error not by reading a small hint).
>
> If I google "postgresql limit" the second link links to
> http://www.postgresql.org/docs/8.3/interactive/queries-limit.html (for
> some reason google strongly prefers version 7.3).
> That page (which is the first you see if you search your way in) gives
> me the following impressions (i.e. given my information gathering
> heuristics):
> - domain postgresql.org (=official)
> - in the page title it states: PostgreSQL 8.3.5 Documentation (=yeah,
> right place)
> - Chapter 7. Queries (=reasonable)
> - 7.6. LIMIT and OFFSET (= home free ;)
>
> Which gives me every indication that I am the right place. Nowhere on
> this page is the note, that there exists a better place (experience has
> shown me, that the SELECT page in the SQL reference is far more
> detailed, but that is unknown for a newbie user).

Exactly what lead me to my conclusions.
I picked up PG during the 8.0 betas - so I've not been around too long, but
I've done enough that I no longer consider myself a "newbie user" ...

For the purpose of providing a use case from some random user:
I might have also arrived at the queries-limit page from:
http://www.postgresql.org/docs/current/static/
then clicking on II.7. taking me to:
http://www.postgresql.org/docs/current/static/queries.html
then clicking on 7.6, taking me to:
http://www.postgresql.org/docs/current/static/queries-limit.html

None of those pages say anything about the depth which the subject is covered,
or the status of the page as "reference".

Of all the (apparently reference) docs I've read, I've never arrived at them
through VI. Reference at
http://www.postgresql.org/docs/current/static/reference.html

So this is very educating for me - would it be out of line to ask, in this
forum, how one such as myself would know when arriving at
http://www.postgresql.org/docs/8.3/interactive/queries-limit.html from Google
or via the above described steps that the page is a not meant to be reference
only? Further, when one starts at the top of
<http://www.postgresql.org/docs/current/static/> and starts reading down, what
leads one to the reference page (at section VI) so that they may see that
statement about the depth of coverage when the topic they're looking for is in
section II?


From: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
To: Andrew Dunstan <andrew(at)dunslane(dot)net>
Cc: Svenne Krap <svenne(at)krap(dot)dk>, pgsql-hackers(at)postgresql(dot)org
Subject: Re: LIMIT NULL
Date: 2009-02-04 17:22:23
Message-ID: A73078CF-B266-42F0-91CA-1831C73205F4@kineticode.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Feb 4, 2009, at 5:25 AM, Andrew Dunstan wrote:

> In effect it does say that - perhaps not quite as explicitly as you
> might have wanted. It says: "The information in this part is
> presented in a narrative fashion in topical units. Readers looking
> for a complete description of a particular command should look into
> Part VI. " (the "PART VI" is a link).

Which would make sense if you were reading it as a book, from front to
back. But as Svenn, Rick, and I have shown, that's not how people find
PostgreSQL documentation. There should be cross references to the
proper pages in Part VI on every relevant page in the narrative
sections, IMHO.

Best,

David


From: Robert Haas <robertmhaas(at)gmail(dot)com>
To: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
Cc: Andrew Dunstan <andrew(at)dunslane(dot)net>, Svenne Krap <svenne(at)krap(dot)dk>, pgsql-hackers(at)postgresql(dot)org
Subject: Re: LIMIT NULL
Date: 2009-02-04 17:33:52
Message-ID: 603c8f070902040933h4fcecca6hef9b8f343b79b445@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Wed, Feb 4, 2009 at 12:22 PM, David E. Wheeler <david(at)kineticode(dot)com> wrote:
>> In effect it does say that - perhaps not quite as explicitly as you might
>> have wanted. It says: "The information in this part is presented in a
>> narrative fashion in topical units. Readers looking for a complete
>> description of a particular command should look into Part VI. " (the "PART
>> VI" is a link).
>
> Which would make sense if you were reading it as a book, from front to back.
> But as Svenn, Rick, and I have shown, that's not how people find PostgreSQL
> documentation. There should be cross references to the proper pages in Part
> VI on every relevant page in the narrative sections, IMHO.

Just to play devil's advocate, I have used the PostgreSQL
documentation for years and have long understood that the references
pages are the place to go if you really need the nitty-gritty on how a
particular command works. I agree that you might not realize this if
you just casually Google your way in, but I can't imagine that problem
is fixable. You'll just end up with a zillion cross-references that
will, overall, reduce the clarity and readability of the
documentation, which is overall very good.

Still, the queries-limit.html page includes this statement: "OFFSET 0
is the same as omitting the OFFSET clause." I don't see that there
would be anything bad or confusing about changing it to read this way:
"OFFSET 0 is the same as omitting the OFFSET clause, and LIMIT NULL is
the same as omitting the LIMIT clause." In fact, it seems nicely
symmetric.

...Robert


From: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
To: Robert Haas <robertmhaas(at)gmail(dot)com>
Cc: Andrew Dunstan <andrew(at)dunslane(dot)net>, Svenne Krap <svenne(at)krap(dot)dk>, pgsql-hackers(at)postgresql(dot)org
Subject: Re: LIMIT NULL
Date: 2009-02-04 17:50:24
Message-ID: A53AB70E-5F74-40B5-8EC6-23FB1FB0F2CE@kineticode.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Feb 4, 2009, at 9:33 AM, Robert Haas wrote:

> Just to play devil's advocate, I have used the PostgreSQL
> documentation for years and have long understood that the references
> pages are the place to go if you really need the nitty-gritty on how a
> particular command works. I agree that you might not realize this if
> you just casually Google your way in, but I can't imagine that problem
> is fixable. You'll just end up with a zillion cross-references that
> will, overall, reduce the clarity and readability of the
> documentation, which is overall very good.

I think that all pages that seem to document particular features
should cross-reference the reference pages in section VI, but not
necessarily vice-versa. I don't think that's asking for a lot. If
you're reading the narrative section, um, narratively, then you'll see
lots of "Look here for more on this topic when you're ready," and that
will be much more useful for the search-result-hit readers, too.

For myself, I've always used the reference documentation, and kind of
never really understood where some of the extra documentation of
certain features, like LIMIT/OFFSET, lived. I never realized there was
a narrative section. As a technically-minded geek, I go right to the
reference, and the other stuff is kind of a weird bonus that comes up
when I do a search.

So unless you're reading the documentation like a bound book, or had
glanced through each of the top-level pages of the TOC to familiarize
yourself with the structure, I'm not sure anyone would really
understand how the non-reference documentation was organized, or that
it wasn't meant to be authoritative.

> Still, the queries-limit.html page includes this statement: "OFFSET 0
> is the same as omitting the OFFSET clause." I don't see that there
> would be anything bad or confusing about changing it to read this way:
> "OFFSET 0 is the same as omitting the OFFSET clause, and LIMIT NULL is
> the same as omitting the LIMIT clause." In fact, it seems nicely
> symmetric.

My patch had done that, basically. The page mentions OFFSET ALL, and I
had just changed it to read OFFSET ALL or OFFSET NULL. Three little
words. :-)

Best,

David


From: Svenne Krap <svenne(at)krap(dot)dk>
To: pgsql-hackers(at)postgresql(dot)org
Subject: Re: LIMIT NULL
Date: 2009-02-04 18:04:58
Message-ID: 4989D8CA.70500@krap.dk
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

David E. Wheeler wrote:
> I think that all pages that seem to document particular features
> should cross-reference the reference pages in section VI, but not
> necessarily vice-versa. I don't think that's asking for a lot. If
> you're reading the narrative section, um, narratively, then you'll
> see lots of "Look here for more on this topic when you're ready,"
> and that will be much more useful for the search-result-hit readers,
> too.
>
That is my idea too... every non-cannonical (ie. non section VI) page
links to relevant section VI (mostly the SELECT one, if I am not
mistaken). No need to link from VI to non-VI or from VI to VI.
> For myself, I've always used the reference documentation, and kind
> of never really understood where some of the extra documentation of
> certain features, like LIMIT/OFFSET, lived. I never realized there
> was a narrative section. As a technically-minded geek, I go right to
> the reference, and the other stuff is kind of a weird bonus that
> comes up when I do a search.
I have the same experience, I also go directly for the most technical
parts. But even I sometimes search and hit those narrative ones....
Btw. there seems to be no section VI (i.e. non-narrative) page about
datatypes and functions... things there link to section II.
>
> So unless you're reading the documentation like a bound book, or had
> glanced through each of the top-level pages of the TOC to
> familiarize yourself with the structure, I'm not sure anyone would
> really understand how the non-reference documentation was organized,
> or that it wasn't meant to be authoritative.
I for sure haven't, and I use the docs almost daily and I never read
that passage about novice users before today.... simply because my
"intro-filler-text filter" had made me skip the text every time I
visited section II.

/Svenne
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkmJ2MoACgkQPPDUIBpvWQsMJACdGLdMirV/WjrzbF8ZLlHAqxoI
5nkAnRFnoaqDnrjzMtzkr7p7gUepEfzF
=4Z0b
-----END PGP SIGNATURE-----


From: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
To: Svenne Krap <svenne(at)krap(dot)dk>
Cc: pgsql-hackers(at)postgresql(dot)org
Subject: Re: LIMIT NULL
Date: 2009-02-04 18:53:37
Message-ID: 211BB439-51EE-450E-A4BC-4209122DC414@kineticode.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Feb 4, 2009, at 10:04 AM, Svenne Krap wrote:

> I have the same experience, I also go directly for the most technical
> parts. But even I sometimes search and hit those narrative ones....
> Btw. there seems to be no section VI (i.e. non-narrative) page about
> datatypes and functions... things there link to section II.

Yeah, so it should be that narrative sections should cross-reference
the appropriate reference sections for the features they describe. So
OFFSET/LIMIT should point to the SELECT reference, and…um, maybe the
data types and functions should be in section VI? Those are
references, no?

Best,

David


From: Jaime Casanova <jcasanov(at)systemguards(dot)com(dot)ec>
To: Robert Haas <robertmhaas(at)gmail(dot)com>
Cc: "David E(dot) Wheeler" <david(at)kineticode(dot)com>, Andrew Dunstan <andrew(at)dunslane(dot)net>, Svenne Krap <svenne(at)krap(dot)dk>, pgsql-hackers(at)postgresql(dot)org
Subject: Re: LIMIT NULL
Date: 2009-02-04 19:20:06
Message-ID: 3073cc9b0902041120j6536b33dt643728d0ee047fdd@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Wed, Feb 4, 2009 at 12:33 PM, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
>
> Still, the queries-limit.html page includes this statement: "OFFSET 0
> is the same as omitting the OFFSET clause." I don't see that there
> would be anything bad or confusing about changing it to read this way:
> "OFFSET 0 is the same as omitting the OFFSET clause, and LIMIT NULL is
> the same as omitting the LIMIT clause." In fact, it seems nicely
> symmetric.
>

good point...

can we just apply this one and let this discussion off?
or maybe remove the OFFSET part and point to the SQL COMMAND
references page? (doesn't seem appropiate to me to reject the LIMIT
comment and let the other one in there while they are almost the same)

--
Atentamente,
Jaime Casanova
Soporte y capacitación de PostgreSQL
Asesoría y desarrollo de sistemas
Guayaquil - Ecuador
Cel. +59387171157


From: Bruce Momjian <bruce(at)momjian(dot)us>
To: Jaime Casanova <jcasanov(at)systemguards(dot)com(dot)ec>
Cc: Robert Haas <robertmhaas(at)gmail(dot)com>, "David E(dot) Wheeler" <david(at)kineticode(dot)com>, Andrew Dunstan <andrew(at)dunslane(dot)net>, Svenne Krap <svenne(at)krap(dot)dk>, pgsql-hackers(at)postgresql(dot)org
Subject: Re: LIMIT NULL
Date: 2009-02-07 20:11:18
Message-ID: 200902072011.n17KBIj19241@momjian.us
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

Jaime Casanova wrote:
> On Wed, Feb 4, 2009 at 12:33 PM, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
> >
> > Still, the queries-limit.html page includes this statement: "OFFSET 0
> > is the same as omitting the OFFSET clause." I don't see that there
> > would be anything bad or confusing about changing it to read this way:
> > "OFFSET 0 is the same as omitting the OFFSET clause, and LIMIT NULL is
> > the same as omitting the LIMIT clause." In fact, it seems nicely
> > symmetric.
> >
>
> good point...
>
> can we just apply this one and let this discussion off?
> or maybe remove the OFFSET part and point to the SQL COMMAND
> references page? (doesn't seem appropiate to me to reject the LIMIT
> comment and let the other one in there while they are almost the same)

Patch attached and applied.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Attachment Content-Type Size
/rtmp/diff text/x-diff 1.2 KB

From: "David E(dot) Wheeler" <david(at)kineticode(dot)com>
To: Bruce Momjian <bruce(at)momjian(dot)us>
Cc: Jaime Casanova <jcasanov(at)systemguards(dot)com(dot)ec>, Robert Haas <robertmhaas(at)gmail(dot)com>, Andrew Dunstan <andrew(at)dunslane(dot)net>, Svenne Krap <svenne(at)krap(dot)dk>, pgsql-hackers(at)postgresql(dot)org
Subject: Re: LIMIT NULL
Date: 2009-02-07 21:35:07
Message-ID: 82C53974-125F-4CBB-AA1F-28E8A402DE1B@kineticode.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Lists: pgsql-hackers

On Feb 7, 2009, at 12:11 PM, Bruce Momjian wrote:

>> can we just apply this one and let this discussion off?
>> or maybe remove the OFFSET part and point to the SQL COMMAND
>> references page? (doesn't seem appropiate to me to reject the LIMIT
>> comment and let the other one in there while they are almost the
>> same)
>
> Patch attached and applied.

Thanks Bruce.

Best,

David