docs - add plan cache invalidation info (#2292)

* docs - add plan cache invalidation info * use correct postgres version, remove reuse statement

docs - add plan cache invalidation info (#2292)
* docs - add plan cache invalidation info * use correct postgres version, remove reuse statement
c7415020 · Lisa Owen · David Yozie · 41f2b966 · c7415020 · c7415020
3 changed file
--- a/gpdb-doc/dita/admin_guide/query/topics/functions-operators.xml
+++ b/gpdb-doc/dita/admin_guide/query/topics/functions-operators.xml
@@ -73,6 +73,7 @@
                    </tbody>
                </tgroup>
            </table>
+            <p>Refer to the PostgreSQL <xref href="https://www.postgresql.org/docs/8.3/static/xfunc-volatility.html" scope="external" format="html">Function Volatility Categories</xref> documentation for additional information about the Greenplum Database function volatility classifications.</p>
            <p>In Greenplum Database, data is divided up across segments — each segment is a
                distinct PostgreSQL database. To prevent inconsistent or unexpected results, do not
                execute functions classified as <codeph>VOLATILE</codeph> at the segment level if
@@ -100,6 +101,12 @@ SELECT foo();
                    (<codeph>rangeFuncs</codeph>) or functions that use the
                    <codeph>refCursor</codeph> datatype.</p>
        </body>
+    <topic id="topic281" xml:lang="en">
+        <title id="in1414519">Function Volatility and Plan Caching</title>
+        <body>
+            <p>There is relatively little difference between the <codeph>STABLE</codeph> and <codeph>IMMUTABLE</codeph> function volatility categories for simple interactive queries that are planned and immediately executed. It does not matter much whether a function is executed once during planning or once during query execution startup. But there is a big difference when you save the plan and reuse it later. If you mislabel a function <codeph>IMMUTABLE</codeph>, Greenplum Database may prematurely fold it to a constant during planning, possibly reusing a stale value during subsequent execution of the plan. You may run into this hazard when using <codeph>PREPARE</codeph>d statements, or when using languages such as PL/pgSQL that cache plans.</p>
+        </body>
+    </topic>
    </topic>
    <topic id="topic28" xml:lang="en">
        <title id="in141451">User-Defined Functions</title>

--- a/gpdb-doc/dita/ref_guide/extensions/pl_sql.xml
+++ b/gpdb-doc/dita/ref_guide/extensions/pl_sql.xml
@@ -9,6 +9,9 @@
      <li id="pt222286">
        <xref href="#topic2" type="topic" format="dita"/>
      </li>
+      <li id="pt222717">
+        <xref href="#topic67" type="topic" format="dita"/>
+      </li>
      <li id="pt222315">
        <xref href="#topic6" type="topic" format="dita"/>
      </li>
@@ -137,6 +140,18 @@ $$ LANGUAGE plpgsql;</codeblock>
      </topic>
    </topic>
  </topic>
+  <topic id="topic67" xml:lang="en">
+    <title id="pt21749299">PL/pgSQL Plan Caching</title>
+    <body>
+        <p>A PL/pgSQL function’s volatility classification has implications on how Greenplum Database caches plans that reference the function.  Refer to <xref href="../../admin_guide/query/topics/functions-operators.xml#topic281">Function Volatility and Plan Caching</xref> in the <cite>Greenplum Database Administrator
+              Guide</cite> for information on plan caching considerations for Greenplum Database function volatility categories.</p>
+        <p>When a PL/pgSQL function executes for the first time in a database session, the PL/pgSQL interpreter parses the function’s SQL expressions and commands. The interpreter creates a prepared execution plan as each expression and SQL command is first executed in the function. The PL/pgSQL interpreter reuses the execution plan for a specific expression and SQL command for the life of the database connection. While this reuse substantially reduces the total amount of time required to parse and generate plans, errors in a specific expression or command cannot be detected until run time when that part of the function is executed.</p>
+        <p>Greenplum Database will automatically re-plan a saved query plan if there is any schema change to any relation used in the query, or if any user-defined function used in the query is redefined. This makes the re-use of a prepared plan transparent in most cases.</p>
+        <p>The SQL commands that you use in a PL/pgSQL function must refer to the same tables and columns on every execution. You cannot use a parameter as the name of a table or a column in an SQL command.</p>
+        <p>PL/pgSQL caches a separate query plan for each combination of actual argument types in which you invoke a polymorphic function to ensure that data type differences do not cause unexpected failures.</p>
+        <p>Refer to the PostgreSQL <xref href="https://www.postgresql.org/docs/9.0/static/plpgsql-implementation.html#PLPGSQL-PLAN-CACHING" scope="external" format="html">Plan Caching</xref> documentation for a detailed discussion of plan caching considerations in the PL/pgSQL language.</p>
+    </body>
+  </topic>
  <topic id="topic6" xml:lang="en">
    <title id="pt217492">PL/pgSQL Examples</title>
    <body>

--- a/gpdb-doc/dita/ref_guide/sql_commands/REINDEX.xml
+++ b/gpdb-doc/dita/ref_guide/sql_commands/REINDEX.xml
@@ -28,9 +28,8 @@ momentarily takes exclusive lock on the parent table, blocking both writes
 and reads. The subsequent <codeph>CREATE INDEX</codeph> locks out writes
 but not reads; since the index is not there, no read will attempt to
 use it, meaning that there will be no blocking but reads may be forced
-into expensive sequential scans. Another important point is that the
-drop/create approach invalidates any cached query plans that use the
-index, while <codeph>REINDEX</codeph> does not.</p><p>Reindexing a single index or table requires being the owner of that
+into expensive sequential scans. 
+</p><p>Reindexing a single index or table requires being the owner of that
 index or table. Reindexing a database requires being the owner of the
 database (note that the owner can therefore rebuild indexes of tables
 owned by other users). Of course, superusers can always reindex anything.</p><p>If you suspect that shared global system catalog indexes are corrupted,