diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml index 30792f4..8ec15b6 100644 --- a/doc/src/sgml/queries.sgml +++ b/doc/src/sgml/queries.sgml @@ -2194,22 +2194,22 @@ SELECT n FROM t LIMIT 100; output anyway. + - A useful property of WITH queries is that they are evaluated - only once per execution of the parent query, even if they are referred to - more than once by the parent query or sibling WITH queries. - Thus, expensive calculations that are needed in multiple places can be - placed within a WITH query to avoid redundant work. Another - possible application is to prevent unwanted multiple evaluations of - functions with side-effects. - However, the other side of this coin is that the optimizer is less able to - push restrictions from the parent query down into a WITH query - than an ordinary subquery. The WITH query will generally be - evaluated as written, without suppression of rows that the parent query - might discard afterwards. (But, as mentioned above, evaluation might stop - early if the reference(s) to the query demand only a limited number of - rows.) + Currently in PostgreSQL, WITH queries + are evaluated only once per execution of the parent query, even if they are + referred to more than once by the parent query or sibling WITH + queries. While this behavior is likely desirable when the WITH + query contains a volatile function, in order to avoid multiple + evaluation problems, the behavior is often undesirable as the optimizer is + less able to push restrictions from the parent query down into the + WITH query than an ordinary subquery. For this reason, the + single evaluation guarantee should not be relied upon as this may be + relaxed in a future version of PostgreSQL in + cases where multiple evaluations of the query are semantically equivalent + to a single evaluation. + The examples above only show WITH being used with @@ -2306,10 +2306,7 @@ DELETE FROM parts Data-modifying statements in WITH are executed exactly once, and always to completion, independently of whether the primary query - reads all (or indeed any) of their output. Notice that this is different - from the rule for SELECT in WITH: as stated in the - previous section, execution of a SELECT is carried only as far - as the primary query demands its output. + reads all (or indeed any) of their output.