Thread: Clarity in partial index example.

Clarity in partial index example.

From
PG Doc comments form
Date:
The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/11/indexes-partial.html
Description:

The example illustrating when a partial index can and cannot be used is a
little misleading. The query which can use the partial index is:
SELECT *
FROM access_log
WHERE url = '/index.html' AND client_ip = inet '212.78.10.32';

and the query which can't use the partial index is:
SELECT *
FROM access_log
WHERE client_ip = inet '192.168.100.23';

Maybe I am misunderstanding the concept here but url = '/index.html' doesn't
have any effect on this? If that's the case I would suggest either removing
it from the first query or adding it to the second query.

Re: Clarity in partial index example.

From
"Jonathan S. Katz"
Date:
On 4/3/19 4:20 PM, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/11/indexes-partial.html
> Description:
>
> The example illustrating when a partial index can and cannot be used is a
> little misleading. The query which can use the partial index is:
> SELECT *
> FROM access_log
> WHERE url = '/index.html' AND client_ip = inet '212.78.10.32';
>
> and the query which can't use the partial index is:
> SELECT *
> FROM access_log
> WHERE client_ip = inet '192.168.100.23';
>
> Maybe I am misunderstanding the concept here but url = '/index.html' doesn't
> have any effect on this? If that's the case I would suggest either removing
> it from the first query or adding it to the second query.

You're correct, the url = '/index.html' does not affect if the partial
index is used in the example.

Based on how the example is set up, I'd propose using the "url"
parameter in both examples. I've attached a patch that does this, with
some additional wording around the examples.

Thanks,

Jonathan

Attachment

Re: Clarity in partial index example.

From
Tom Lane
Date:
"Jonathan S. Katz" <jkatz@postgresql.org> writes:
> On 4/3/19 4:20 PM, PG Doc comments form wrote:
>> Maybe I am misunderstanding the concept here but url = '/index.html' doesn't
>> have any effect on this? If that's the case I would suggest either removing
>> it from the first query or adding it to the second query.

> You're correct, the url = '/index.html' does not affect if the partial
> index is used in the example.

> Based on how the example is set up, I'd propose using the "url"
> parameter in both examples. I've attached a patch that does this, with
> some additional wording around the examples.

Yeah, this seems unnecessarily confusing.  I tweaked your extra wording
a bit --- I didn't like referring to the index as covering a range,
because it's really excluding a range not including one.

Pushed.

            regards, tom lane



Re: Clarity in partial index example.

From
"Jonathan S. Katz"
Date:
On 4/3/19 6:30 PM, Tom Lane wrote:
> "Jonathan S. Katz" <jkatz@postgresql.org> writes:
>> On 4/3/19 4:20 PM, PG Doc comments form wrote:
>>> Maybe I am misunderstanding the concept here but url = '/index.html' doesn't
>>> have any effect on this? If that's the case I would suggest either removing
>>> it from the first query or adding it to the second query.
>
>> You're correct, the url = '/index.html' does not affect if the partial
>> index is used in the example.
>
>> Based on how the example is set up, I'd propose using the "url"
>> parameter in both examples. I've attached a patch that does this, with
>> some additional wording around the examples.
>
> Yeah, this seems unnecessarily confusing.  I tweaked your extra wording
> a bit --- I didn't like referring to the index as covering a range,
> because it's really excluding a range not including one.

You're right, that makes sense.

> Pushed.

Thanks!

Jonathan


Attachment