obsolete indexing method "rtree"
We removed the indexing method "rtree" in version 8.3 and replaced it with "gist". Until today there are some "rtree" heritages: * "CREATE INDEX ... USING rtree ..." is valid syntax and leads to the message "NOTICE: substituting access method gist for obsolete method rtree" * The documentation refers to the method in ref/comments.sgml and ref/create_index.sgml. * The documentation uses the term "R-Tree" in gist.sgml, seg.sgml, and xindex.sgml. That's ok because in this cases it refers to the abstract concept of R-trees and not to the eliminated implementation. Isn't it time to disallow this syntax and remove all references and messages? The situation concerning index types, access methods, operator classes, and index related extensions is complicate enough and hard to explain to newcomers. Every simplification should be welcomed. -- Jürgen Purtz
Re: obsolete indexing method "rtree"
=?UTF-8?Q?J=c3=bcrgen_Purtz?= writes: > We removed the indexing method "rtree" in version 8.3 and replaced it > with "gist". Until today there are some "rtree" heritages: > * "CREATE INDEX ... USING rtree ..." is valid syntax and leads to the > message "NOTICE: substituting access method gist for obsolete > method rtree" > * The documentation refers to the method in ref/comments.sgml and > ref/create_index.sgml. > * The documentation uses the term "R-Tree" in gist.sgml, seg.sgml, and > xindex.sgml. That's ok because in this cases it refers to the > abstract concept of R-trees and not to the eliminated implementation. > Isn't it time to disallow this syntax and remove all references and > messages? Why? It's not hurting anything to continue the substitution in CREATE INDEX. The example in comments.sgml is just an example, and is not meant to reflect a built-in object any more than the adjacent examples are. Possibly the comment in seg.sgml should be adjusted to refer to GiST indexes --- but then again, it's not entirely clear whether it's even still relevant for GiST indexes. Perhaps it's talking about a deficiency that was specific to the old rtree code. regards, tom lane
Re: Typo in the Section "3.6. Inheritance"
On Mon, Jul 27, 2020 at 02:47:07PM +, PG Doc comments form wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/12/tutorial-inheritance.html > Description: > > Hello Team, > > https://www.postgresql.org/docs/current/tutorial-inheritance.html > > There is the sentence in section 3.6: "State capitals have an extra column, > state, that shows their state." > I think it would be more correct to rewrite it as "Table capitals has > .", since "capitals" is the table name in this context, but not the > state. Agreed. Patch attached and applied through 9.5. -- Bruce Momjian https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml new file mode 100644 index f6c4627..27b6d47 *** a/doc/src/sgml/advanced.sgml --- b/doc/src/sgml/advanced.sgml *** CREATE TABLE capitals ( *** 628,635 parent, cities. The type of the column name is text, a native PostgreSQL ! type for variable length character strings. State capitals have ! an extra column, state, that shows their state. In PostgreSQL, a table can inherit from zero or more other tables. --- 628,636 parent, cities. The type of the column name is text, a native PostgreSQL ! type for variable length character strings. The ! capitals table has ! an extra column, state, which shows their states. In PostgreSQL, a table can inherit from zero or more other tables.
Re: Typo in the Section "3.6. Inheritance"
On Wed, Aug 5, 2020 at 05:12:43PM -0400, Bruce Momjian wrote: > ! type for variable length character strings. The > ! capitals table has > ! an extra column, state, which shows their > states. In -- Uh, I thought I was fixing this by changing "state" to "states", but I now think "state" was correct, right? -- Bruce Momjian https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee
Re: Procedures
On Tue, Aug 4, 2020 at 10:33:49AM +, PG Doc comments form wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/11/sql-createprocedure.html > Description: > > The information on procedures could helpfully include that the feature is > new from PostgreSQL 11 and give an explanation of how it differs from > functions. I found the information I needed here > https://dba.stackexchange.com/a/262662, but I think it would really benefit > others if the information was provided in the official documentation. We don't normally mention what release added a features. However, I do see your problem with finding that procedures can issue transaction control statements. I see this for procedures: https://www.postgresql.org/docs/12/xproc.html but that has no mention of transactions, just a mention of using CALL, then this pl/pgSQL section about transaction control mentions CALL: https://www.postgresql.org/docs/12/plpgsql-transactions.html Is this what you think needs improving? -- Bruce Momjian https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee
Re: need for "see also" section or similar thing at hub pages
On Tue, Aug 4, 2020 at 03:56:32PM +, PG Doc comments form wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/12/functions-textsearch.html > Description: > > A suggestion. This page, "functions-textsearch", is fine, and the best > place to explain functions like array_to_tsvector() and jsonb_to_tsvector(). > The suggestion is just to cite these native functions in the Guide's "hub > page" of respective prefixes... > > Ideal, for Guide reader, is to be informed about the existence of all array > functions in the Array's hub page, > https://www.postgresql.org/docs/current/functions-array.html , and all JSON > functions in the JSON's hub page > https://www.postgresql.org/docs/current/functions-json.html > > Simple citation anywhere in the hub page, or a simple "See also" section to > list the non-explained functions that can be also classifyed as valid > function for that hub page. Uh, I am not sure it helps to mention that there are text search-specific functions in the generic sections. -- Bruce Momjian https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee
Re: Typo in the Section "3.6. Inheritance"
On Wed, Aug 05, 2020 at 05:36:56PM -0400, Bruce Momjian wrote: > On Wed, Aug 5, 2020 at 05:12:43PM -0400, Bruce Momjian wrote: > > ! type for variable length character strings. The > > ! capitals table has > > ! an extra column, state, which shows their > > states. In > > -- > > Uh, I thought I was fixing this by changing "state" to "states", but I > now think "state" was correct, right? What if you used an entirely different wording for the second part of the sentence? Say, "which shows the state of each capital". -- Michael signature.asc Description: PGP signature
Re: Typo in the Section "3.6. Inheritance"
On Wed, Aug 5, 2020 at 10:41 PM Michael Paquier wrote: > On Wed, Aug 05, 2020 at 05:36:56PM -0400, Bruce Momjian wrote: > > On Wed, Aug 5, 2020 at 05:12:43PM -0400, Bruce Momjian wrote: > > > ! type for variable length character strings. The > > > ! capitals table has > > > ! an extra column, state, which shows > their states. In > > > -- > > > > Uh, I thought I was fixing this by changing "state" to "states", but I > > now think "state" was correct, right? The main wording problem with the direct phrasing shown here is the inability to clarify that while there are multiple capitals and multiple states each capital exists in a single, mutually exclusive, state. Frankly it doesn't seem wrong, or at least any worse than the general content on the page, and probably should just be left alone until someone writes a better tutorial. Tangentially, I personally think "additional" is a better word choice than "extra"; not enough to patch by itself but to consider if patching anyway. What if you used an entirely different wording for the second part of > the sentence? Say, "which shows the state of each capital". > The capitals table has an additional column, state, which holds a state abbreviation. As an aside, that field should be constrained NOT NULL and UNIQUE. I have no qualms using those features in a chapter named "Advanced Features". The cities table also doesn't have a PK (name, though in practice that is a poor choice), which it should, and the capitals table should have a unique index created over its inherited name field. The note at the bottom says as much but showing the additional code in an example seems worthwhile. Another option is to define capitals as: CREATE TABLE capitals ( capital_dedication date NOT NULL ) INHERITS (cities); "The capitals table has an additional column, capital_dedication, that holds the date on which the city became a capital." Removing "char" from the tutorial is a nice side-effect that we probably want to do even if we keep "state". The fact that this limited scope cities/capitals model is best defined using a single table with an "is_captial boolean not null" field sours me entirely as to the model choice for this page. David J.
