Thread: [PATCH] Add section headings to index types doc
[PATCH] Add section headings to index types doc
From
ilmari@ilmari.org (Dagfinn Ilmari Mannsåker)
Date:
Hi hackers,
Every time I have to look up what kinds of operations each index type is
suitable for, I get annoyed by the index types page being virtually
unskimmable due to not having headings for each index type.
Attached is a patch that adds <sect2> tags for each index type to make
it easier to see where the description of each one starts.
- ilmari
--
"The surreality of the universe tends towards a maximum" -- Skud's Law
"Never formulate a law or axiom that you're not prepared to live with
the consequences of." -- Skud's Meta-Law
From 57d9550b9286e7f6298763bb51d45393aa2eab4e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= <ilmari@ilmari.org>
Date: Fri, 31 Jul 2020 10:20:48 +0100
Subject: [PATCH] Add section headers to index types doc
This makes it easier to compare the properties of different index
types at a glance.
---
doc/src/sgml/indices.sgml | 460 ++++++++++++++++++++------------------
1 file changed, 242 insertions(+), 218 deletions(-)
diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml
index 28adaba72d..332d161547 100644
--- a/doc/src/sgml/indices.sgml
+++ b/doc/src/sgml/indices.sgml
@@ -122,244 +122,268 @@
B-tree indexes, which fit the most common situations.
</para>
- <para>
- <indexterm>
- <primary>index</primary>
- <secondary>B-tree</secondary>
- </indexterm>
- <indexterm>
- <primary>B-tree</primary>
- <see>index</see>
- </indexterm>
- B-trees can handle equality and range queries on data that can be sorted
- into some ordering.
- In particular, the <productname>PostgreSQL</productname> query planner
- will consider using a B-tree index whenever an indexed column is
- involved in a comparison using one of these operators:
+ <sect2 id="indexes-types-btree">
+ <title>B-tree</title>
- <simplelist>
- <member><literal><</literal></member>
- <member><literal><=</literal></member>
- <member><literal>=</literal></member>
- <member><literal>>=</literal></member>
- <member><literal>></literal></member>
- </simplelist>
+ <para>
+ <indexterm>
+ <primary>index</primary>
+ <secondary>B-tree</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>B-tree</primary>
+ <see>index</see>
+ </indexterm>
+ B-trees can handle equality and range queries on data that can be sorted
+ into some ordering.
+ In particular, the <productname>PostgreSQL</productname> query planner
+ will consider using a B-tree index whenever an indexed column is
+ involved in a comparison using one of these operators:
- Constructs equivalent to combinations of these operators, such as
- <literal>BETWEEN</literal> and <literal>IN</literal>, can also be implemented with
- a B-tree index search. Also, an <literal>IS NULL</literal> or <literal>IS NOT
- NULL</literal> condition on an index column can be used with a B-tree index.
- </para>
+ <simplelist>
+ <member><literal><</literal></member>
+ <member><literal><=</literal></member>
+ <member><literal>=</literal></member>
+ <member><literal>>=</literal></member>
+ <member><literal>></literal></member>
+ </simplelist>
- <para>
- The optimizer can also use a B-tree index for queries involving the
- pattern matching operators <literal>LIKE</literal> and <literal>~</literal>
- <emphasis>if</emphasis> the pattern is a constant and is anchored to
- the beginning of the string — for example, <literal>col LIKE
- 'foo%'</literal> or <literal>col ~ '^foo'</literal>, but not
- <literal>col LIKE '%bar'</literal>. However, if your database does not
- use the C locale you will need to create the index with a special
- operator class to support indexing of pattern-matching queries; see
- <xref linkend="indexes-opclass"/> below. It is also possible to use
- B-tree indexes for <literal>ILIKE</literal> and
- <literal>~*</literal>, but only if the pattern starts with
- non-alphabetic characters, i.e., characters that are not affected by
- upper/lower case conversion.
- </para>
+ Constructs equivalent to combinations of these operators, such as
+ <literal>BETWEEN</literal> and <literal>IN</literal>, can also be implemented with
+ a B-tree index search. Also, an <literal>IS NULL</literal> or <literal>IS NOT
+ NULL</literal> condition on an index column can be used with a B-tree index.
+ </para>
- <para>
- B-tree indexes can also be used to retrieve data in sorted order.
- This is not always faster than a simple scan and sort, but it is
- often helpful.
- </para>
+ <para>
+ The optimizer can also use a B-tree index for queries involving the
+ pattern matching operators <literal>LIKE</literal> and <literal>~</literal>
+ <emphasis>if</emphasis> the pattern is a constant and is anchored to
+ the beginning of the string — for example, <literal>col LIKE
+ 'foo%'</literal> or <literal>col ~ '^foo'</literal>, but not
+ <literal>col LIKE '%bar'</literal>. However, if your database does not
+ use the C locale you will need to create the index with a special
+ operator class to support indexing of pattern-matching queries; see
+ <xref linkend="indexes-opclass"/> below. It is also possible to use
+ B-tree indexes for <literal>ILIKE</literal> and
+ <literal>~*</literal>, but only if the pattern starts with
+ non-alphabetic characters, i.e., characters that are not affected by
+ upper/lower case conversion.
+ </para>
- <para>
- <indexterm>
- <primary>index</primary>
- <secondary>hash</secondary>
- </indexterm>
- <indexterm>
- <primary>hash</primary>
- <see>index</see>
- </indexterm>
- Hash indexes can only handle simple equality comparisons.
- The query planner will consider using a hash index whenever an
- indexed column is involved in a comparison using the
- <literal>=</literal> operator.
- The following command is used to create a hash index:
-<synopsis>
-CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable> USING HASH
(<replaceable>column</replaceable>);
-</synopsis>
- </para>
+ <para>
+ B-tree indexes can also be used to retrieve data in sorted order.
+ This is not always faster than a simple scan and sort, but it is
+ often helpful.
+ </para>
+ </sect2>
- <para>
- <indexterm>
- <primary>index</primary>
- <secondary>GiST</secondary>
- </indexterm>
- <indexterm>
- <primary>GiST</primary>
- <see>index</see>
- </indexterm>
- GiST indexes are not a single kind of index, but rather an infrastructure
- within which many different indexing strategies can be implemented.
- Accordingly, the particular operators with which a GiST index can be
- used vary depending on the indexing strategy (the <firstterm>operator
- class</firstterm>). As an example, the standard distribution of
- <productname>PostgreSQL</productname> includes GiST operator classes
- for several two-dimensional geometric data types, which support indexed
- queries using these operators:
+ <sect2 id="indexes-types-hash">
+ <title>Hash</title>
- <simplelist>
- <member><literal><<</literal></member>
- <member><literal>&<</literal></member>
- <member><literal>&></literal></member>
- <member><literal>>></literal></member>
- <member><literal><<|</literal></member>
- <member><literal>&<|</literal></member>
- <member><literal>|&></literal></member>
- <member><literal>|>></literal></member>
- <member><literal>@></literal></member>
- <member><literal><@</literal></member>
- <member><literal>~=</literal></member>
- <member><literal>&&</literal></member>
- </simplelist>
+ <para>
+ <indexterm>
+ <primary>index</primary>
+ <secondary>hash</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>hash</primary>
+ <see>index</see>
+ </indexterm>
+ Hash indexes can only handle simple equality comparisons.
+ The query planner will consider using a hash index whenever an
+ indexed column is involved in a comparison using the
+ <literal>=</literal> operator.
+ The following command is used to create a hash index:
+ <synopsis>
+ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable> USING HASH
(<replaceable>column</replaceable>);
+ </synopsis>
+ </para>
+ </sect2>
- (See <xref linkend="functions-geometry"/> for the meaning of
- these operators.)
- The GiST operator classes included in the standard distribution are
- documented in <xref linkend="gist-builtin-opclasses-table"/>.
- Many other GiST operator
- classes are available in the <literal>contrib</literal> collection or as separate
- projects. For more information see <xref linkend="gist"/>.
- </para>
+ <sect2 id="indexes-type-gist">
+ <title>GiST</title>
- <para>
- GiST indexes are also capable of optimizing <quote>nearest-neighbor</quote>
- searches, such as
-<programlisting><![CDATA[
-SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
-]]>
-</programlisting>
- which finds the ten places closest to a given target point. The ability
- to do this is again dependent on the particular operator class being used.
- In <xref linkend="gist-builtin-opclasses-table"/>, operators that can be
- used in this way are listed in the column <quote>Ordering Operators</quote>.
- </para>
+ <para>
+ <indexterm>
+ <primary>index</primary>
+ <secondary>GiST</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>GiST</primary>
+ <see>index</see>
+ </indexterm>
+ GiST indexes are not a single kind of index, but rather an infrastructure
+ within which many different indexing strategies can be implemented.
+ Accordingly, the particular operators with which a GiST index can be
+ used vary depending on the indexing strategy (the <firstterm>operator
+ class</firstterm>). As an example, the standard distribution of
+ <productname>PostgreSQL</productname> includes GiST operator classes
+ for several two-dimensional geometric data types, which support indexed
+ queries using these operators:
- <para>
- <indexterm>
- <primary>index</primary>
- <secondary>SP-GiST</secondary>
- </indexterm>
- <indexterm>
- <primary>SP-GiST</primary>
- <see>index</see>
- </indexterm>
- SP-GiST indexes, like GiST indexes, offer an infrastructure that supports
- various kinds of searches. SP-GiST permits implementation of a wide range
- of different non-balanced disk-based data structures, such as quadtrees,
- k-d trees, and radix trees (tries). As an example, the standard distribution of
- <productname>PostgreSQL</productname> includes SP-GiST operator classes
- for two-dimensional points, which support indexed
- queries using these operators:
+ <simplelist>
+ <member><literal><<</literal></member>
+ <member><literal>&<</literal></member>
+ <member><literal>&></literal></member>
+ <member><literal>>></literal></member>
+ <member><literal><<|</literal></member>
+ <member><literal>&<|</literal></member>
+ <member><literal>|&></literal></member>
+ <member><literal>|>></literal></member>
+ <member><literal>@></literal></member>
+ <member><literal><@</literal></member>
+ <member><literal>~=</literal></member>
+ <member><literal>&&</literal></member>
+ </simplelist>
- <simplelist>
- <member><literal><<</literal></member>
- <member><literal>>></literal></member>
- <member><literal>~=</literal></member>
- <member><literal><@</literal></member>
- <member><literal><^</literal></member>
- <member><literal>>^</literal></member>
- </simplelist>
+ (See <xref linkend="functions-geometry"/> for the meaning of
+ these operators.)
+ The GiST operator classes included in the standard distribution are
+ documented in <xref linkend="gist-builtin-opclasses-table"/>.
+ Many other GiST operator
+ classes are available in the <literal>contrib</literal> collection or as separate
+ projects. For more information see <xref linkend="gist"/>.
+ </para>
- (See <xref linkend="functions-geometry"/> for the meaning of
- these operators.)
- The SP-GiST operator classes included in the standard distribution are
- documented in <xref linkend="spgist-builtin-opclasses-table"/>.
- For more information see <xref linkend="spgist"/>.
- </para>
+ <para>
+ GiST indexes are also capable of optimizing <quote>nearest-neighbor</quote>
+ searches, such as
+ <programlisting><![CDATA[
+ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
+ ]]>
+ </programlisting>
+ which finds the ten places closest to a given target point. The ability
+ to do this is again dependent on the particular operator class being used.
+ In <xref linkend="gist-builtin-opclasses-table"/>, operators that can be
+ used in this way are listed in the column <quote>Ordering Operators</quote>.
+ </para>
+ </sect2>
- <para>
- Like GiST, SP-GiST supports <quote>nearest-neighbor</quote> searches.
- For SP-GiST operator classes that support distance ordering, the
- corresponding operator is specified in the <quote>Ordering Operators</quote>
- column in <xref linkend="spgist-builtin-opclasses-table"/>.
- </para>
+ <sect2 id="indexes-type-spgist">
+ <title>SP-GiST</title>
- <para>
- <indexterm>
- <primary>index</primary>
- <secondary>GIN</secondary>
- </indexterm>
- <indexterm>
- <primary>GIN</primary>
- <see>index</see>
- </indexterm>
- GIN indexes are <quote>inverted indexes</quote> which are appropriate for
- data values that contain multiple component values, such as arrays. An
- inverted index contains a separate entry for each component value, and
- can efficiently handle queries that test for the presence of specific
- component values.
- </para>
+ <para>
+ <indexterm>
+ <primary>index</primary>
+ <secondary>SP-GiST</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>SP-GiST</primary>
+ <see>index</see>
+ </indexterm>
+ SP-GiST indexes, like GiST indexes, offer an infrastructure that supports
+ various kinds of searches. SP-GiST permits implementation of a wide range
+ of different non-balanced disk-based data structures, such as quadtrees,
+ k-d trees, and radix trees (tries). As an example, the standard distribution of
+ <productname>PostgreSQL</productname> includes SP-GiST operator classes
+ for two-dimensional points, which support indexed
+ queries using these operators:
- <para>
- Like GiST and SP-GiST, GIN can support
- many different user-defined indexing strategies, and the particular
- operators with which a GIN index can be used vary depending on the
- indexing strategy.
- As an example, the standard distribution of
- <productname>PostgreSQL</productname> includes a GIN operator class
- for arrays, which supports indexed queries using these operators:
+ <simplelist>
+ <member><literal><<</literal></member>
+ <member><literal>>></literal></member>
+ <member><literal>~=</literal></member>
+ <member><literal><@</literal></member>
+ <member><literal><^</literal></member>
+ <member><literal>>^</literal></member>
+ </simplelist>
- <simplelist>
- <member><literal><@</literal></member>
- <member><literal>@></literal></member>
- <member><literal>=</literal></member>
- <member><literal>&&</literal></member>
- </simplelist>
+ (See <xref linkend="functions-geometry"/> for the meaning of
+ these operators.)
+ The SP-GiST operator classes included in the standard distribution are
+ documented in <xref linkend="spgist-builtin-opclasses-table"/>.
+ For more information see <xref linkend="spgist"/>.
+ </para>
- (See <xref linkend="functions-array"/> for the meaning of
- these operators.)
- The GIN operator classes included in the standard distribution are
- documented in <xref linkend="gin-builtin-opclasses-table"/>.
- Many other GIN operator
- classes are available in the <literal>contrib</literal> collection or as separate
- projects. For more information see <xref linkend="gin"/>.
- </para>
+ <para>
+ Like GiST, SP-GiST supports <quote>nearest-neighbor</quote> searches.
+ For SP-GiST operator classes that support distance ordering, the
+ corresponding operator is specified in the <quote>Ordering Operators</quote>
+ column in <xref linkend="spgist-builtin-opclasses-table"/>.
+ </para>
+ </sect2>
- <para>
- <indexterm>
- <primary>index</primary>
- <secondary>BRIN</secondary>
- </indexterm>
- <indexterm>
- <primary>BRIN</primary>
- <see>index</see>
- </indexterm>
- BRIN indexes (a shorthand for Block Range INdexes) store summaries about
- the values stored in consecutive physical block ranges of a table.
- Like GiST, SP-GiST and GIN,
- BRIN can support many different indexing strategies,
- and the particular operators with which a BRIN index can be used
- vary depending on the indexing strategy.
- For data types that have a linear sort order, the indexed data
- corresponds to the minimum and maximum values of the
- values in the column for each block range. This supports indexed queries
- using these operators:
+ <sect2 id="indexes-types-gin">
+ <title>GIN</title>
- <simplelist>
- <member><literal><</literal></member>
- <member><literal><=</literal></member>
- <member><literal>=</literal></member>
- <member><literal>>=</literal></member>
- <member><literal>></literal></member>
- </simplelist>
+ <para>
+ <indexterm>
+ <primary>index</primary>
+ <secondary>GIN</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>GIN</primary>
+ <see>index</see>
+ </indexterm>
+ GIN indexes are <quote>inverted indexes</quote> which are appropriate for
+ data values that contain multiple component values, such as arrays. An
+ inverted index contains a separate entry for each component value, and
+ can efficiently handle queries that test for the presence of specific
+ component values.
+ </para>
- The BRIN operator classes included in the standard distribution are
- documented in <xref linkend="brin-builtin-opclasses-table"/>.
- For more information see <xref linkend="brin"/>.
- </para>
+ <para>
+ Like GiST and SP-GiST, GIN can support
+ many different user-defined indexing strategies, and the particular
+ operators with which a GIN index can be used vary depending on the
+ indexing strategy.
+ As an example, the standard distribution of
+ <productname>PostgreSQL</productname> includes a GIN operator class
+ for arrays, which supports indexed queries using these operators:
+
+ <simplelist>
+ <member><literal><@</literal></member>
+ <member><literal>@></literal></member>
+ <member><literal>=</literal></member>
+ <member><literal>&&</literal></member>
+ </simplelist>
+
+ (See <xref linkend="functions-array"/> for the meaning of
+ these operators.)
+ The GIN operator classes included in the standard distribution are
+ documented in <xref linkend="gin-builtin-opclasses-table"/>.
+ Many other GIN operator
+ classes are available in the <literal>contrib</literal> collection or as separate
+ projects. For more information see <xref linkend="gin"/>.
+ </para>
+ </sect2>
+
+ <sect2 id="indexes-types-brin">
+ <title>BRIN</title>
+
+ <para>
+ <indexterm>
+ <primary>index</primary>
+ <secondary>BRIN</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>BRIN</primary>
+ <see>index</see>
+ </indexterm>
+ BRIN indexes (a shorthand for Block Range INdexes) store summaries about
+ the values stored in consecutive physical block ranges of a table.
+ Like GiST, SP-GiST and GIN,
+ BRIN can support many different indexing strategies,
+ and the particular operators with which a BRIN index can be used
+ vary depending on the indexing strategy.
+ For data types that have a linear sort order, the indexed data
+ corresponds to the minimum and maximum values of the
+ values in the column for each block range. This supports indexed queries
+ using these operators:
+
+ <simplelist>
+ <member><literal><</literal></member>
+ <member><literal><=</literal></member>
+ <member><literal>=</literal></member>
+ <member><literal>>=</literal></member>
+ <member><literal>></literal></member>
+ </simplelist>
+
+ The BRIN operator classes included in the standard distribution are
+ documented in <xref linkend="brin-builtin-opclasses-table"/>.
+ For more information see <xref linkend="brin"/>.
+ </para>
+ </sect2>
</sect1>
--
2.27.0
Re: [PATCH] Add section headings to index types doc
From
ilmari@ilmari.org (Dagfinn Ilmari Mannsåker)
Date:
ilmari@ilmari.org (Dagfinn Ilmari Mannsåker) writes: > Hi hackers, > > Every time I have to look up what kinds of operations each index type is > suitable for, I get annoyed by the index types page being virtually > unskimmable due to not having headings for each index type. > > Attached is a patch that adds <sect2> tags for each index type to make > it easier to see where the description of each one starts. Added to the next commitfest: https://commitfest.postgresql.org/29/2665/ Also, for easier review, here's the `git diff -w` output, since the <sect2> tags caused most of the page to have to be renidented. Tangentially, does anyone know of a tool to strip whitespace changes from an existing diff, as if it had been generated with `-w` in the first place? diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml index 28adaba72d..332d161547 100644 --- a/doc/src/sgml/indices.sgml +++ b/doc/src/sgml/indices.sgml @@ -122,6 +122,9 @@ B-tree indexes, which fit the most common situations. </para> + <sect2 id="indexes-types-btree"> + <title>B-tree</title> + <para> <indexterm> <primary>index</primary> @@ -172,6 +175,10 @@ This is not always faster than a simple scan and sort, but it is often helpful. </para> + </sect2> + + <sect2 id="indexes-types-hash"> + <title>Hash</title> <para> <indexterm> @@ -191,6 +198,10 @@ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable> USING HASH (<replaceable>column</replaceable>); </synopsis> </para> + </sect2> + + <sect2 id="indexes-type-gist"> + <title>GiST</title> <para> <indexterm> @@ -246,6 +257,10 @@ In <xref linkend="gist-builtin-opclasses-table"/>, operators that can be used in this way are listed in the column <quote>Ordering Operators</quote>. </para> + </sect2> + + <sect2 id="indexes-type-spgist"> + <title>SP-GiST</title> <para> <indexterm> @@ -286,6 +301,10 @@ corresponding operator is specified in the <quote>Ordering Operators</quote> column in <xref linkend="spgist-builtin-opclasses-table"/>. </para> + </sect2> + + <sect2 id="indexes-types-gin"> + <title>GIN</title> <para> <indexterm> @@ -327,6 +346,10 @@ classes are available in the <literal>contrib</literal> collection or as separate projects. For more information see <xref linkend="gin"/>. </para> + </sect2> + + <sect2 id="indexes-types-brin"> + <title>BRIN</title> <para> <indexterm> @@ -360,6 +383,7 @@ documented in <xref linkend="brin-builtin-opclasses-table"/>. For more information see <xref linkend="brin"/>. </para> + </sect2> </sect1> - ilmari -- "A disappointingly low fraction of the human race is, at any given time, on fire." - Stig Sandbeck Mathisen
On Mon, Aug 3, 2020 at 1:32 PM Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> wrote:
ilmari@ilmari.org (Dagfinn Ilmari Mannsåker) writes:
> Hi hackers,
>
> Every time I have to look up what kinds of operations each index type is
> suitable for, I get annoyed by the index types page being virtually
> unskimmable due to not having headings for each index type.
>
> Attached is a patch that adds <sect2> tags for each index type to make
> it easier to see where the description of each one starts.
Added to the next commitfest:
https://commitfest.postgresql.org/29/2665/
Also, for easier review, here's the `git diff -w` output, since the
<sect2> tags caused most of the page to have to be renidented.
Tangentially, does anyone know of a tool to strip whitespace changes
from an existing diff, as if it had been generated with `-w` in the
first place?
I think you can do something like:
combinediff -w 0001-Add-section-headers-to-index-types-doc.patch /dev/null
(combinediff requires two diffs, but one can be /dev/null)
ilmari@ilmari.org (Dagfinn Ilmari =?utf-8?Q?Manns=C3=A5ker?=) writes:
> Also, for easier review, here's the `git diff -w` output, since the
> <sect2> tags caused most of the page to have to be renidented.
TBH, I'd suggest just not being anal about whether the indentation
nesting is perfect ;-). There are certainly plenty of places in
the SGML files today where it is not. And for something like this,
I doubt the gain is worth the loss of "git blame" tracking and
possible back-patching hazards.
I'm a compulsive neatnik when it comes to indentation of the
C code, but much less so about the SGML docs. YMMV of course.
regards, tom lane
The following review has been posted through the commitfest application:
make installcheck-world: not tested
Implements feature: not tested
Spec compliant: not tested
Documentation: tested, passed
a) I'm wondering if we should apply one more change to this page. The line-by-line listing of operators occupies much
space.What do you think about an inline list (in a separate line) of the operators?
old source:
<simplelist>
<member><literal><</literal></member>
<member><literal><=</literal></member>
<member><literal>=</literal></member>
<member><literal>>=</literal></member>
<member><literal>></literal></member>
</simplelist>
new source:
<synopsis>< <= = >= ></synopsis>
It looks nice in HTML as well as in PDF.
b) I'm in favor of the indentation of all affected lines as it is done in the patch.
The new status of this patch is: Waiting on Author
On Mon, Aug 10, 2020 at 12:52:17PM +0000, Jürgen Purtz wrote: > The new status of this patch is: Waiting on Author This has not been answered yet, so I have marked the patch as returned with feedback. -- Michael
Attachment
Re: [PATCH] Add section headings to index types doc
From
ilmari@ilmari.org (Dagfinn Ilmari Mannsåker)
Date:
Michael Paquier <michael@paquier.xyz> writes:
> On Mon, Aug 10, 2020 at 12:52:17PM +0000, Jürgen Purtz wrote:
>> The new status of this patch is: Waiting on Author
>
> This has not been answered yet, so I have marked the patch as returned
> with feedback.
Updated patch attached, wich reformats the operator lists as requested
by Jürgen, and skips the reindentation as suggested by Tom.
The reindentation patch is attached separately, in case the committer
decides they want it properly indented after all.
- ilmari
--
- Twitter seems more influential [than blogs] in the 'gets reported in
the mainstream press' sense at least. - Matt McLeod
- That'd be because the content of a tweet is easier to condense down
to a mainstream media article. - Calle Dybedahl
From 84522dc77afd1b8ce0bf111279302888d9d3edcb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= <ilmari@ilmari.org>
Date: Fri, 31 Jul 2020 10:20:48 +0100
Subject: [PATCH] Add section headers to index types doc
This makes it easier to compare the properties of different index
types at a glance.
In passing, make the index operator lists a single line each.
---
doc/src/sgml/indices.sgml | 81 +++++++++++++++++++--------------------
1 file changed, 39 insertions(+), 42 deletions(-)
diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml
index 671299ff05..f22253f4c3 100644
--- a/doc/src/sgml/indices.sgml
+++ b/doc/src/sgml/indices.sgml
@@ -122,6 +122,9 @@
B-tree indexes, which fit the most common situations.
</para>
+ <sect2 id="indexes-types-btree">
+ <title>B-tree</title>
+
<para>
<indexterm>
<primary>index</primary>
@@ -137,13 +140,9 @@
will consider using a B-tree index whenever an indexed column is
involved in a comparison using one of these operators:
- <simplelist>
- <member><literal><</literal></member>
- <member><literal><=</literal></member>
- <member><literal>=</literal></member>
- <member><literal>>=</literal></member>
- <member><literal>></literal></member>
- </simplelist>
+<synopsis>
+< <= = >= >
+</synopsis>
Constructs equivalent to combinations of these operators, such as
<literal>BETWEEN</literal> and <literal>IN</literal>, can also be implemented with
@@ -172,6 +171,10 @@
This is not always faster than a simple scan and sort, but it is
often helpful.
</para>
+ </sect2>
+
+ <sect2 id="indexes-types-hash">
+ <title>Hash</title>
<para>
<indexterm>
@@ -191,6 +194,10 @@
CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable> USING HASH
(<replaceable>column</replaceable>);
</synopsis>
</para>
+ </sect2>
+
+ <sect2 id="indexes-type-gist">
+ <title>GiST</title>
<para>
<indexterm>
@@ -210,20 +217,9 @@
for several two-dimensional geometric data types, which support indexed
queries using these operators:
- <simplelist>
- <member><literal><<</literal></member>
- <member><literal>&<</literal></member>
- <member><literal>&></literal></member>
- <member><literal>>></literal></member>
- <member><literal><<|</literal></member>
- <member><literal>&<|</literal></member>
- <member><literal>|&></literal></member>
- <member><literal>|>></literal></member>
- <member><literal>@></literal></member>
- <member><literal><@</literal></member>
- <member><literal>~=</literal></member>
- <member><literal>&&</literal></member>
- </simplelist>
+<synopsis>
+<< &< &> >> <<| &<| |&>
|>> @> <@ ~= &&
+</synopsis>
(See <xref linkend="functions-geometry"/> for the meaning of
these operators.)
@@ -246,6 +242,10 @@
In <xref linkend="gist-builtin-opclasses-table"/>, operators that can be
used in this way are listed in the column <quote>Ordering Operators</quote>.
</para>
+ </sect2>
+
+ <sect2 id="indexes-type-spgist">
+ <title>SP-GiST</title>
<para>
<indexterm>
@@ -264,14 +264,9 @@
for two-dimensional points, which support indexed
queries using these operators:
- <simplelist>
- <member><literal><<</literal></member>
- <member><literal>>></literal></member>
- <member><literal>~=</literal></member>
- <member><literal><@</literal></member>
- <member><literal><^</literal></member>
- <member><literal>>^</literal></member>
- </simplelist>
+<synopsis>
+<< >> ~= <@ <^ >^
+</synopsis>
(See <xref linkend="functions-geometry"/> for the meaning of
these operators.)
@@ -286,6 +281,10 @@
corresponding operator is specified in the <quote>Ordering Operators</quote>
column in <xref linkend="spgist-builtin-opclasses-table"/>.
</para>
+ </sect2>
+
+ <sect2 id="indexes-types-gin">
+ <title>GIN</title>
<para>
<indexterm>
@@ -312,12 +311,9 @@
<productname>PostgreSQL</productname> includes a GIN operator class
for arrays, which supports indexed queries using these operators:
- <simplelist>
- <member><literal><@</literal></member>
- <member><literal>@></literal></member>
- <member><literal>=</literal></member>
- <member><literal>&&</literal></member>
- </simplelist>
+<synopsis>
+<@ @> = &&
+</synopsis>
(See <xref linkend="functions-array"/> for the meaning of
these operators.)
@@ -327,6 +323,10 @@
classes are available in the <literal>contrib</literal> collection or as separate
projects. For more information see <xref linkend="gin"/>.
</para>
+ </sect2>
+
+ <sect2 id="indexes-types-brin">
+ <title>BRIN</title>
<para>
<indexterm>
@@ -348,18 +348,15 @@
values in the column for each block range. This supports indexed queries
using these operators:
- <simplelist>
- <member><literal><</literal></member>
- <member><literal><=</literal></member>
- <member><literal>=</literal></member>
- <member><literal>>=</literal></member>
- <member><literal>></literal></member>
- </simplelist>
+<synopsis>
+< <= = >= >
+</synopsis>
The BRIN operator classes included in the standard distribution are
documented in <xref linkend="brin-builtin-opclasses-table"/>.
For more information see <xref linkend="brin"/>.
</para>
+ </sect2>
</sect1>
--
2.27.0
From 2a75f535e60e89ed7e2276f4775395162f364e8c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= <ilmari@ilmari.org>
Date: Tue, 1 Sep 2020 11:48:59 +0100
Subject: [PATCH 2/2] Reindent index types docs after previous commit
The previous commit wrapped each index type descripiton in a `<sect2>`
tag, but avoided reidenting for ease of review. This commit reindents
everything, except the `<synopsis>` and `<programlisting>` tags, which
appear to need to be in column zero.
---
doc/src/sgml/indices.sgml | 338 +++++++++++++++++++-------------------
1 file changed, 169 insertions(+), 169 deletions(-)
diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml
index f22253f4c3..3e11d3917f 100644
--- a/doc/src/sgml/indices.sgml
+++ b/doc/src/sgml/indices.sgml
@@ -125,237 +125,237 @@
<sect2 id="indexes-types-btree">
<title>B-tree</title>
- <para>
- <indexterm>
- <primary>index</primary>
- <secondary>B-tree</secondary>
- </indexterm>
- <indexterm>
- <primary>B-tree</primary>
- <see>index</see>
- </indexterm>
- B-trees can handle equality and range queries on data that can be sorted
- into some ordering.
- In particular, the <productname>PostgreSQL</productname> query planner
- will consider using a B-tree index whenever an indexed column is
- involved in a comparison using one of these operators:
+ <para>
+ <indexterm>
+ <primary>index</primary>
+ <secondary>B-tree</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>B-tree</primary>
+ <see>index</see>
+ </indexterm>
+ B-trees can handle equality and range queries on data that can be sorted
+ into some ordering.
+ In particular, the <productname>PostgreSQL</productname> query planner
+ will consider using a B-tree index whenever an indexed column is
+ involved in a comparison using one of these operators:
<synopsis>
< <= = >= >
</synopsis>
- Constructs equivalent to combinations of these operators, such as
- <literal>BETWEEN</literal> and <literal>IN</literal>, can also be implemented with
- a B-tree index search. Also, an <literal>IS NULL</literal> or <literal>IS NOT
- NULL</literal> condition on an index column can be used with a B-tree index.
- </para>
+ Constructs equivalent to combinations of these operators, such as
+ <literal>BETWEEN</literal> and <literal>IN</literal>, can also be implemented with
+ a B-tree index search. Also, an <literal>IS NULL</literal> or <literal>IS NOT
+ NULL</literal> condition on an index column can be used with a B-tree index.
+ </para>
- <para>
- The optimizer can also use a B-tree index for queries involving the
- pattern matching operators <literal>LIKE</literal> and <literal>~</literal>
- <emphasis>if</emphasis> the pattern is a constant and is anchored to
- the beginning of the string — for example, <literal>col LIKE
- 'foo%'</literal> or <literal>col ~ '^foo'</literal>, but not
- <literal>col LIKE '%bar'</literal>. However, if your database does not
- use the C locale you will need to create the index with a special
- operator class to support indexing of pattern-matching queries; see
- <xref linkend="indexes-opclass"/> below. It is also possible to use
- B-tree indexes for <literal>ILIKE</literal> and
- <literal>~*</literal>, but only if the pattern starts with
- non-alphabetic characters, i.e., characters that are not affected by
- upper/lower case conversion.
- </para>
+ <para>
+ The optimizer can also use a B-tree index for queries involving the
+ pattern matching operators <literal>LIKE</literal> and <literal>~</literal>
+ <emphasis>if</emphasis> the pattern is a constant and is anchored to
+ the beginning of the string — for example, <literal>col LIKE
+ 'foo%'</literal> or <literal>col ~ '^foo'</literal>, but not
+ <literal>col LIKE '%bar'</literal>. However, if your database does not
+ use the C locale you will need to create the index with a special
+ operator class to support indexing of pattern-matching queries; see
+ <xref linkend="indexes-opclass"/> below. It is also possible to use
+ B-tree indexes for <literal>ILIKE</literal> and
+ <literal>~*</literal>, but only if the pattern starts with
+ non-alphabetic characters, i.e., characters that are not affected by
+ upper/lower case conversion.
+ </para>
- <para>
- B-tree indexes can also be used to retrieve data in sorted order.
- This is not always faster than a simple scan and sort, but it is
- often helpful.
- </para>
+ <para>
+ B-tree indexes can also be used to retrieve data in sorted order.
+ This is not always faster than a simple scan and sort, but it is
+ often helpful.
+ </para>
</sect2>
<sect2 id="indexes-types-hash">
<title>Hash</title>
- <para>
- <indexterm>
- <primary>index</primary>
- <secondary>hash</secondary>
- </indexterm>
- <indexterm>
- <primary>hash</primary>
- <see>index</see>
- </indexterm>
- Hash indexes can only handle simple equality comparisons.
- The query planner will consider using a hash index whenever an
- indexed column is involved in a comparison using the
- <literal>=</literal> operator.
- The following command is used to create a hash index:
+ <para>
+ <indexterm>
+ <primary>index</primary>
+ <secondary>hash</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>hash</primary>
+ <see>index</see>
+ </indexterm>
+ Hash indexes can only handle simple equality comparisons.
+ The query planner will consider using a hash index whenever an
+ indexed column is involved in a comparison using the
+ <literal>=</literal> operator.
+ The following command is used to create a hash index:
<synopsis>
CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable> USING HASH
(<replaceable>column</replaceable>);
</synopsis>
- </para>
+ </para>
</sect2>
<sect2 id="indexes-type-gist">
<title>GiST</title>
- <para>
- <indexterm>
- <primary>index</primary>
- <secondary>GiST</secondary>
- </indexterm>
- <indexterm>
- <primary>GiST</primary>
- <see>index</see>
- </indexterm>
- GiST indexes are not a single kind of index, but rather an infrastructure
- within which many different indexing strategies can be implemented.
- Accordingly, the particular operators with which a GiST index can be
- used vary depending on the indexing strategy (the <firstterm>operator
- class</firstterm>). As an example, the standard distribution of
- <productname>PostgreSQL</productname> includes GiST operator classes
- for several two-dimensional geometric data types, which support indexed
- queries using these operators:
+ <para>
+ <indexterm>
+ <primary>index</primary>
+ <secondary>GiST</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>GiST</primary>
+ <see>index</see>
+ </indexterm>
+ GiST indexes are not a single kind of index, but rather an infrastructure
+ within which many different indexing strategies can be implemented.
+ Accordingly, the particular operators with which a GiST index can be
+ used vary depending on the indexing strategy (the <firstterm>operator
+ class</firstterm>). As an example, the standard distribution of
+ <productname>PostgreSQL</productname> includes GiST operator classes
+ for several two-dimensional geometric data types, which support indexed
+ queries using these operators:
<synopsis>
<< &< &> >> <<| &<| |&>
|>> @> <@ ~= &&
</synopsis>
- (See <xref linkend="functions-geometry"/> for the meaning of
- these operators.)
- The GiST operator classes included in the standard distribution are
- documented in <xref linkend="gist-builtin-opclasses-table"/>.
- Many other GiST operator
- classes are available in the <literal>contrib</literal> collection or as separate
- projects. For more information see <xref linkend="gist"/>.
- </para>
+ (See <xref linkend="functions-geometry"/> for the meaning of
+ these operators.)
+ The GiST operator classes included in the standard distribution are
+ documented in <xref linkend="gist-builtin-opclasses-table"/>.
+ Many other GiST operator
+ classes are available in the <literal>contrib</literal> collection or as separate
+ projects. For more information see <xref linkend="gist"/>.
+ </para>
- <para>
- GiST indexes are also capable of optimizing <quote>nearest-neighbor</quote>
- searches, such as
+ <para>
+ GiST indexes are also capable of optimizing <quote>nearest-neighbor</quote>
+ searches, such as
<programlisting><![CDATA[
SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
]]>
</programlisting>
- which finds the ten places closest to a given target point. The ability
- to do this is again dependent on the particular operator class being used.
- In <xref linkend="gist-builtin-opclasses-table"/>, operators that can be
- used in this way are listed in the column <quote>Ordering Operators</quote>.
- </para>
+ which finds the ten places closest to a given target point. The ability
+ to do this is again dependent on the particular operator class being used.
+ In <xref linkend="gist-builtin-opclasses-table"/>, operators that can be
+ used in this way are listed in the column <quote>Ordering Operators</quote>.
+ </para>
</sect2>
<sect2 id="indexes-type-spgist">
<title>SP-GiST</title>
- <para>
- <indexterm>
- <primary>index</primary>
- <secondary>SP-GiST</secondary>
- </indexterm>
- <indexterm>
- <primary>SP-GiST</primary>
- <see>index</see>
- </indexterm>
- SP-GiST indexes, like GiST indexes, offer an infrastructure that supports
- various kinds of searches. SP-GiST permits implementation of a wide range
- of different non-balanced disk-based data structures, such as quadtrees,
- k-d trees, and radix trees (tries). As an example, the standard distribution of
- <productname>PostgreSQL</productname> includes SP-GiST operator classes
- for two-dimensional points, which support indexed
- queries using these operators:
+ <para>
+ <indexterm>
+ <primary>index</primary>
+ <secondary>SP-GiST</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>SP-GiST</primary>
+ <see>index</see>
+ </indexterm>
+ SP-GiST indexes, like GiST indexes, offer an infrastructure that supports
+ various kinds of searches. SP-GiST permits implementation of a wide range
+ of different non-balanced disk-based data structures, such as quadtrees,
+ k-d trees, and radix trees (tries). As an example, the standard distribution of
+ <productname>PostgreSQL</productname> includes SP-GiST operator classes
+ for two-dimensional points, which support indexed
+ queries using these operators:
<synopsis>
<< >> ~= <@ <^ >^
</synopsis>
- (See <xref linkend="functions-geometry"/> for the meaning of
- these operators.)
- The SP-GiST operator classes included in the standard distribution are
- documented in <xref linkend="spgist-builtin-opclasses-table"/>.
- For more information see <xref linkend="spgist"/>.
- </para>
+ (See <xref linkend="functions-geometry"/> for the meaning of
+ these operators.)
+ The SP-GiST operator classes included in the standard distribution are
+ documented in <xref linkend="spgist-builtin-opclasses-table"/>.
+ For more information see <xref linkend="spgist"/>.
+ </para>
- <para>
- Like GiST, SP-GiST supports <quote>nearest-neighbor</quote> searches.
- For SP-GiST operator classes that support distance ordering, the
- corresponding operator is specified in the <quote>Ordering Operators</quote>
- column in <xref linkend="spgist-builtin-opclasses-table"/>.
- </para>
+ <para>
+ Like GiST, SP-GiST supports <quote>nearest-neighbor</quote> searches.
+ For SP-GiST operator classes that support distance ordering, the
+ corresponding operator is specified in the <quote>Ordering Operators</quote>
+ column in <xref linkend="spgist-builtin-opclasses-table"/>.
+ </para>
</sect2>
<sect2 id="indexes-types-gin">
<title>GIN</title>
- <para>
- <indexterm>
- <primary>index</primary>
- <secondary>GIN</secondary>
- </indexterm>
- <indexterm>
- <primary>GIN</primary>
- <see>index</see>
- </indexterm>
- GIN indexes are <quote>inverted indexes</quote> which are appropriate for
- data values that contain multiple component values, such as arrays. An
- inverted index contains a separate entry for each component value, and
- can efficiently handle queries that test for the presence of specific
- component values.
- </para>
+ <para>
+ <indexterm>
+ <primary>index</primary>
+ <secondary>GIN</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>GIN</primary>
+ <see>index</see>
+ </indexterm>
+ GIN indexes are <quote>inverted indexes</quote> which are appropriate for
+ data values that contain multiple component values, such as arrays. An
+ inverted index contains a separate entry for each component value, and
+ can efficiently handle queries that test for the presence of specific
+ component values.
+ </para>
- <para>
- Like GiST and SP-GiST, GIN can support
- many different user-defined indexing strategies, and the particular
- operators with which a GIN index can be used vary depending on the
- indexing strategy.
- As an example, the standard distribution of
- <productname>PostgreSQL</productname> includes a GIN operator class
- for arrays, which supports indexed queries using these operators:
+ <para>
+ Like GiST and SP-GiST, GIN can support
+ many different user-defined indexing strategies, and the particular
+ operators with which a GIN index can be used vary depending on the
+ indexing strategy.
+ As an example, the standard distribution of
+ <productname>PostgreSQL</productname> includes a GIN operator class
+ for arrays, which supports indexed queries using these operators:
<synopsis>
<@ @> = &&
</synopsis>
- (See <xref linkend="functions-array"/> for the meaning of
- these operators.)
- The GIN operator classes included in the standard distribution are
- documented in <xref linkend="gin-builtin-opclasses-table"/>.
- Many other GIN operator
- classes are available in the <literal>contrib</literal> collection or as separate
- projects. For more information see <xref linkend="gin"/>.
- </para>
+ (See <xref linkend="functions-array"/> for the meaning of
+ these operators.)
+ The GIN operator classes included in the standard distribution are
+ documented in <xref linkend="gin-builtin-opclasses-table"/>.
+ Many other GIN operator
+ classes are available in the <literal>contrib</literal> collection or as separate
+ projects. For more information see <xref linkend="gin"/>.
+ </para>
</sect2>
<sect2 id="indexes-types-brin">
<title>BRIN</title>
- <para>
- <indexterm>
- <primary>index</primary>
- <secondary>BRIN</secondary>
- </indexterm>
- <indexterm>
- <primary>BRIN</primary>
- <see>index</see>
- </indexterm>
- BRIN indexes (a shorthand for Block Range INdexes) store summaries about
- the values stored in consecutive physical block ranges of a table.
- Like GiST, SP-GiST and GIN,
- BRIN can support many different indexing strategies,
- and the particular operators with which a BRIN index can be used
- vary depending on the indexing strategy.
- For data types that have a linear sort order, the indexed data
- corresponds to the minimum and maximum values of the
- values in the column for each block range. This supports indexed queries
- using these operators:
+ <para>
+ <indexterm>
+ <primary>index</primary>
+ <secondary>BRIN</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>BRIN</primary>
+ <see>index</see>
+ </indexterm>
+ BRIN indexes (a shorthand for Block Range INdexes) store summaries about
+ the values stored in consecutive physical block ranges of a table.
+ Like GiST, SP-GiST and GIN,
+ BRIN can support many different indexing strategies,
+ and the particular operators with which a BRIN index can be used
+ vary depending on the indexing strategy.
+ For data types that have a linear sort order, the indexed data
+ corresponds to the minimum and maximum values of the
+ values in the column for each block range. This supports indexed queries
+ using these operators:
<synopsis>
< <= = >= >
</synopsis>
- The BRIN operator classes included in the standard distribution are
- documented in <xref linkend="brin-builtin-opclasses-table"/>.
- For more information see <xref linkend="brin"/>.
- </para>
+ The BRIN operator classes included in the standard distribution are
+ documented in <xref linkend="brin-builtin-opclasses-table"/>.
+ For more information see <xref linkend="brin"/>.
+ </para>
</sect2>
</sect1>
--
2.27.0
On 30/09/2020 14:25, Dagfinn Ilmari Mannsåker wrote: > Michael Paquier <michael@paquier.xyz> writes: > >> On Mon, Aug 10, 2020 at 12:52:17PM +0000, Jürgen Purtz wrote: >>> The new status of this patch is: Waiting on Author >> >> This has not been answered yet, so I have marked the patch as returned >> with feedback. > > Updated patch attached, wich reformats the operator lists as requested > by Jürgen, and skips the reindentation as suggested by Tom. I wonder if "synopsis" is the right markup for the operator lists. I'm not too familiar with SGML, but the closest similar list I could find is this in create_operator.sgml: > The operator name is a sequence of up to <symbol>NAMEDATALEN</symbol>-1 > (63 by default) characters from the following list: > <literallayout> > + - * / < > = ~ ! @ # % ^ & | ` ? > </literallayout> Reading up on the meaning of "literallayout" at https://tdg.docbook.org/tdg/4.5/literallayout.html, though, it doesn't sound quite right either. Maybe "<simplelist type=horiz'>" ? - Heikki
On 30.09.20 14:53, Heikki Linnakangas wrote:
On 30/09/2020 14:25, Dagfinn Ilmari Mannsåker wrote:Michael Paquier <michael@paquier.xyz> writes:On Mon, Aug 10, 2020 at 12:52:17PM +0000, Jürgen Purtz wrote:The new status of this patch is: Waiting on Author
This has not been answered yet, so I have marked the patch as returned
with feedback.
Updated patch attached, wich reformats the operator lists as requested
by Jürgen, and skips the reindentation as suggested by Tom.
I wonder if "synopsis" is the right markup for the operator lists. I'm not too familiar with SGML, but the closest similar list I could find is this in create_operator.sgml:The operator name is a sequence of up to <symbol>NAMEDATALEN</symbol>-1
(63 by default) characters from the following list:
<literallayout>
+ - * / < > = ~ ! @ # % ^ & | ` ?
</literallayout>
Reading up on the meaning of "literallayout" at https://tdg.docbook.org/tdg/4.5/literallayout.html, though, it doesn't sound quite right either. Maybe "<simplelist type=horiz'>" ?
- Heikki
<literallyout> loses the aqua background color (in comparison to the existing documentation).
<simplelist type="horiz" columns="5"><member><literal><</literal></member> ... is very chatty: it needs the additional 'columns' attribute and the additional 'member' element.
Therefor I am in favor of the <synopsis> solution as given in the last patch of Dagfinn.
Playing around I found another solution, which also looks quite good. The chapter uses operators within the text flow at different places. All of them are embedded in a <literal> element (inline). Using this <literal> element also for the index-specific operators, the reading of the page gets easier and the rendering is consistent. But the drawback is that these operator are no longer accentuated. Because they 'represents' the possible access methods per index-type, one can argue that they should be shown in a special way, eg.: in a separate paragraph as in Dagfin's patch. (I suppose that this was the original intention of the huge number of line-breaks.) It would look like the following, but I don't recommend to use it:
--
Jürgen Purtz
Attachment
On Wed, Sep 30, 2020 at 4:25 AM Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> wrote:
Michael Paquier <michael@paquier.xyz> writes:
> On Mon, Aug 10, 2020 at 12:52:17PM +0000, Jürgen Purtz wrote:
>> The new status of this patch is: Waiting on Author
>
> This has not been answered yet, so I have marked the patch as returned
> with feedback.
Updated patch attached, wich reformats the operator lists as requested
by Jürgen,
A couple of things:
One, I would place the equality operator for hash inside a standalone synopsis just like all of the others.
Two, why is hash special in having its create index command provided here? (I notice this isn't the fault of this patch but it stands out when reviewing it)
I would suggest rewording hash to look more like the others and add a link to the "CREATE INDEX" command from the chapter preamble.
and skips the reindentation as suggested by Tom.
Agreed
David J.
On 21.10.20 23:12, David G. Johnston wrote:
okOn Wed, Sep 30, 2020 at 4:25 AM Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> wrote:Michael Paquier <michael@paquier.xyz> writes:
> On Mon, Aug 10, 2020 at 12:52:17PM +0000, Jürgen Purtz wrote:
>> The new status of this patch is: Waiting on Author
>
> This has not been answered yet, so I have marked the patch as returned
> with feedback.
Updated patch attached, wich reformats the operator lists as requested
by Jürgen,A couple of things:One, I would place the equality operator for hash inside a standalone synopsis just like all of the others.
yes, this looks odd.Two, why is hash special in having its create index command provided here? (I notice this isn't the fault of this patch but it stands out when reviewing it)
okI would suggest rewording hash to look more like the others
is the link necessary?and add a link to the "CREATE INDEX" command from the chapter preamble.
and skips the reindentation as suggested by Tom.AgreedDavid J.
--
J. Purtz
On Fri, Oct 23, 2020 at 3:18 AM Jürgen Purtz <juergen@purtz.de> wrote:
is the link necessary?and add a link to the "CREATE INDEX" command from the chapter preamble.
I suppose it would make more sense to add it to the previous section - the introduction page. I do think having a link (or more than one) to CREATE INDEX from the Indexes chapter is reader friendly. Having links to SQL commands is never truly necessary - the reader knows a SQL command reference exists and the name of the command allows them to find the correct page.
David J.
On 23.10.20 18:08, David G. Johnston wrote:
I'm afraid I haven't grasped everything of your intentions and suggestions of your last two mails.On Fri, Oct 23, 2020 at 3:18 AM Jürgen Purtz <juergen@purtz.de> wrote:is the link necessary?and add a link to the "CREATE INDEX" command from the chapter preamble.I suppose it would make more sense to add it to the previous section - the introduction page. I do think having a link (or more than one) to CREATE INDEX from the Indexes chapter is reader friendly. Having links to SQL commands is never truly necessary - the reader knows a SQL command reference exists and the name of the command allows them to find the correct page.David J.
- equal operator in standalone paragraph: ok, integrated.
- shift "create index ... using HASH" to a different place: You suggest shifting the statement or a link to the previous (sub-)chapter "11.1 Introduction"? But there is already a "create index" example. Please read my suggestion/modification in the first paragraph of the "11.2 Index Types" page.
- "rewording hash": I don't know what is missing here. But I have added a few words about the nature of this index type.
Attached are two patches: a) summary against master and b) standalone of my current changes.
--
J. Purtz
Attachment
=?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de> writes:
> Attached are two patches: a) summary against master and b) standalone of
> my current changes.
This was a bit confused ... as submitted, the patch wanted to commit
a couple of patchfiles. I sorted it out I believe, and pushed with
a little additional fiddling of my own.
I did not commit the reindentation of existing text --- I don't think
it's worth adding "git blame" noise for.
regards, tom lane