Nit: "Immutable" should be "pure"
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/12/sql-createindex.html
Description:
The adjective "immutable" describing the functions and operators used in an
index (see two occurrences in doc snippet below) is incorrect and should be
replaced with "pure". Both "pure" and "immutable" are in popular lexicon now
because of the interest in functional programming, so conflating the two can
happen, but the word immutable applies to data and pure applies to
functions. See https://en.wikipedia.org/wiki/Pure_function.
From the CREATE INDEX doc:
All functions and operators used in an index definition must be “immutable”,
that is, their results must depend only on their arguments and never on any
outside influence (such as the contents of another table or the current
time). This restriction ensures that the behavior of the index is
well-defined. To use a user-defined function in an index expression or WHERE
clause, remember to mark the function immutable when you create it.
On Thu, Nov 7, 2019 at 02:17:58PM +0000, PG Doc comments form wrote:
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/12/sql-createindex.html
Description:The adjective "immutable" describing the functions and operators used in an
index (see two occurrences in doc snippet below) is incorrect and should be
replaced with "pure". Both "pure" and "immutable" are in popular lexicon now
because of the interest in functional programming, so conflating the two can
happen, but the word immutable applies to data and pure applies to
functions. See https://en.wikipedia.org/wiki/Pure_function.From the CREATE INDEX doc:
All functions and operators used in an index definition must be “immutable”,
that is, their results must depend only on their arguments and never on any
outside influence (such as the contents of another table or the current
time). This restriction ensures that the behavior of the index is
well-defined. To use a user-defined function in an index expression or WHERE
clause, remember to mark the function immutable when you create it.
Well, we use IMMUTABLE as an option to CREATE FUNCTION so I don't see
how we can realign to the new word meanings without a lot of confusion:
CREATE [ OR REPLACE ] FUNCTION
name ( [ [ argmode ] [ argname ] argtype [ { DEFAULT | = } default_expr ] [, ...] ] )
[ RETURNS rettype
| RETURNS TABLE ( column_name column_type [, ...] ) ]
{ LANGUAGE lang_name
| TRANSFORM { FOR TYPE type_name } [, ... ]
| WINDOW
| IMMUTABLE | STABLE | VOLATILE | [ NOT ] LEAKPROOF
^^^^^^^^^
I think the best we can do is to mention that IMMUTABLE functions mean
pure, but I am not sure there is even enough demand for that, vs.
confusing people.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com
+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +
Bruce Momjian <bruce@momjian.us> writes:
On Thu, Nov 7, 2019 at 02:17:58PM +0000, PG Doc comments form wrote:
The adjective "immutable" describing the functions and operators used in an
index (see two occurrences in doc snippet below) is incorrect and should be
replaced with "pure".
I think the best we can do is to mention that IMMUTABLE functions mean
pure, but I am not sure there is even enough demand for that, vs.
confusing people.
Yeah. I don't think this terminology is nearly as universal
as the OP believes, so I don't feel a need to change anything.
If we adopt Corey's proposal to create a glossary [1]https://commitfest.postgresql.org/25/2305/, there'd be
room for a parenthetical comment like "(In some circles, "pure" is the
preferred term for this function property.)" in the glossary entry for
"immutable". I suspect it won't be the only entry that needs
cross-references to other terminology.
regards, tom lane
Thanks for the feedback folks. I had not seen the IMMUTABLE argument to CREATE FUNCTION and realize this change is too expensive.
This probably will not be the last you hear on this since pureness and immutability are all the rage in development circles.
Show quoted text
On Nov 7, 2019, at 12:38 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Bruce Momjian <bruce@momjian.us> writes:
On Thu, Nov 7, 2019 at 02:17:58PM +0000, PG Doc comments form wrote:
The adjective "immutable" describing the functions and operators used in an
index (see two occurrences in doc snippet below) is incorrect and should be
replaced with "pure".I think the best we can do is to mention that IMMUTABLE functions mean
pure, but I am not sure there is even enough demand for that, vs.
confusing people.Yeah. I don't think this terminology is nearly as universal
as the OP believes, so I don't feel a need to change anything.If we adopt Corey's proposal to create a glossary [1], there'd be
room for a parenthetical comment like "(In some circles, "pure" is the
preferred term for this function property.)" in the glossary entry for
"immutable". I suspect it won't be the only entry that needs
cross-references to other terminology.regards, tom lane