Removing "Included attributes in B-tree indexes" section from docs
I propose removing the "Included attributes in B-tree indexes"
top-level section of chapter 63 from the user facing documentation.
Chapter 63 concerns B-Tree operator classes themselves, in the
abstract, so the fact that an operator class isn't needed for extra
covering index columns isn't appropriate. It seems sufficient to only
mention this once, in the CREATE INDEX docs.
Attached patch shows what I have in mind -- the total removal of this
top-level section.
--
Peter Geoghegan
Attachments:
0001-Remove-INCLUDE-attributes-section-from-docs.patchtext/x-patch; charset=US-ASCII; name=0001-Remove-INCLUDE-attributes-section-from-docs.patchDownload
From 293f1fc93771fa6be65867f53aa507fb30137230 Mon Sep 17 00:00:00 2001
From: Peter Geoghegan <pg@bowt.ie>
Date: Fri, 15 Jun 2018 10:45:29 -0700
Subject: [PATCH] Remove INCLUDE attributes section from docs.
It doesn't seem useful to mention covering indexes in a chapter about
the behavior of B-Tree operator classes. The fact that INCLUDE columns
don't require a B-Tree operator class is already covered in the CREATE
INDEX documentation.
---
doc/src/sgml/btree.sgml | 17 -----------------
1 file changed, 17 deletions(-)
diff --git a/doc/src/sgml/btree.sgml b/doc/src/sgml/btree.sgml
index 336d026ea1..8bd0badb28 100644
--- a/doc/src/sgml/btree.sgml
+++ b/doc/src/sgml/btree.sgml
@@ -433,23 +433,6 @@ returns bool
</sect1>
-<sect1 id="btree-included-attributes">
- <title>Included attributes in B-tree indexes</title>
-
- <para>
- As of <productname>PostgreSQL</productname> 11.0 there is an optional
- INCLUDE clause, which allows to add non-key (included) attributes to index.
- Those included attributes allow more queries to benefit from index-only scans.
- We never use included attributes in ScanKeys for search. That allows us to
- include into B-tree any datatypes, even those which don't have suitable
- operator classes. Included columns only stored in regular tuples on leaf
- pages. All pivot tuples on non-leaf pages and highkey tuples are truncated
- to contain only key attributes. That helps to slightly reduce the size of
- index.
- </para>
-
-</sect1>
-
<sect1 id="btree-implementation">
<title>Implementation</title>
--
2.17.1
On 2018-Jun-15, Peter Geoghegan wrote:
I propose removing the "Included attributes in B-tree indexes"
top-level section of chapter 63 from the user facing documentation.
Hi Peter,
I don't necessarily object to the proposed change, but I think you
should generally wait a bit longer for others to react.
--
�lvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On Sat, Jun 16, 2018 at 8:51 PM, Alvaro Herrera
<alvherre@2ndquadrant.com> wrote:
I don't necessarily object to the proposed change, but I think you
should generally wait a bit longer for others to react.
What wait period do you think is appropriate in this case?
The doc section that I removed was a last minute addition to the
covering index commit, commit 8224de4f, something that I was heavily
involved in as a reviewer. I felt, rightly or wrongly, that I had
discretion to commit within a relatively short period of time (a
little over 24 hours) because of the specific circumstances: I knew
that the doc section was not well considered in the first place, I
thought that the question was clear cut, and I doubted that anyone
else would follow up at all.
--
Peter Geoghegan
On Sun, Jun 17, 2018 at 9:33 PM Peter Geoghegan <pg@bowt.ie> wrote:
On Sat, Jun 16, 2018 at 8:51 PM, Alvaro Herrera
<alvherre@2ndquadrant.com> wrote:I don't necessarily object to the proposed change, but I think you
should generally wait a bit longer for others to react.What wait period do you think is appropriate in this case?
The doc section that I removed was a last minute addition to the
covering index commit, commit 8224de4f, something that I was heavily
involved in as a reviewer. I felt, rightly or wrongly, that I had
discretion to commit within a relatively short period of time (a
little over 24 hours) because of the specific circumstances: I knew
that the doc section was not well considered in the first place, I
thought that the question was clear cut, and I doubted that anyone
else would follow up at all.
FWIW, I've no objections against removing this.
------
Alexander Korotkov
Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company
On 2018-Jun-17, Peter Geoghegan wrote:
On Sat, Jun 16, 2018 at 8:51 PM, Alvaro Herrera
<alvherre@2ndquadrant.com> wrote:I don't necessarily object to the proposed change, but I think you
should generally wait a bit longer for others to react.What wait period do you think is appropriate in this case?
One which includes at least half a working day in a different timezone.
You asked mid-afternoon on a Friday in a timezone pretty far west. I
think you could find people in their offices in Easter Island, but not
many more.
--
�lvaro Herrera https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
On Mon, Jun 18, 2018 at 10:21 AM, Alvaro Herrera
<alvherre@2ndquadrant.com> wrote:
One which includes at least half a working day in a different timezone.
You asked mid-afternoon on a Friday in a timezone pretty far west.
It was 11 am PST.
I'll make a note about this. It won't happen again.
--
Peter Geoghegan
On 2018-06-18 13:21:43 -0400, Alvaro Herrera wrote:
On 2018-Jun-17, Peter Geoghegan wrote:
On Sat, Jun 16, 2018 at 8:51 PM, Alvaro Herrera
<alvherre@2ndquadrant.com> wrote:I don't necessarily object to the proposed change, but I think you
should generally wait a bit longer for others to react.What wait period do you think is appropriate in this case?
One which includes at least half a working day in a different timezone.
You asked mid-afternoon on a Friday in a timezone pretty far west. I
think you could find people in their offices in Easter Island, but not
many more.
I think there's also a question of how much a patch is blocking you /
others. A shorter question period is more understandable if it's step
3/40, rather than 1/1...
Greetings,
Andres Freund
On Mon, Jun 18, 2018 at 1:31 PM, Andres Freund <andres@anarazel.de> wrote:
I think there's also a question of how much a patch is blocking you /
others. A shorter question period is more understandable if it's step
3/40, rather than 1/1...
Agreed. For non-critical stuff like this it seems like waiting 2 or 3
business days is a good idea.
Doesn't sound like there's any actual controversy in this case, though.
--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company
On 06/18/2018 01:31 PM, Andres Freund wrote:
On 2018-06-18 13:21:43 -0400, Alvaro Herrera wrote:
On 2018-Jun-17, Peter Geoghegan wrote:
On Sat, Jun 16, 2018 at 8:51 PM, Alvaro Herrera
<alvherre@2ndquadrant.com> wrote:I don't necessarily object to the proposed change, but I think you
should generally wait a bit longer for others to react.What wait period do you think is appropriate in this case?
One which includes at least half a working day in a different timezone.
You asked mid-afternoon on a Friday in a timezone pretty far west. I
think you could find people in their offices in Easter Island, but not
many more.I think there's also a question of how much a patch is blocking you /
others. A shorter question period is more understandable if it's step
3/40, rather than 1/1...
Yeah, but this would still apply for the first in a series of advertised
patches.
I usually try to wait at least a couple of days. I'm sure every
committer understands how you can feel the itch to push. I know I do.
cheers
andrew
--
Andrew Dunstan https://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services