Adding reference topic and additional docs around temp_tablespaces (#8025)

* Adding reference topic and additional information around temp_tablespaces * Clarify comma-separated list

Adding reference topic and additional docs around temp_tablespaces (#8025)
* Adding reference topic and additional information around temp_tablespaces * Clarify comma-separated list
c2fa27d7 · David Yozie · GitHub · c46bf52f · c2fa27d7 · c2fa27d7
8 changed file
--- a/gpdb-doc/dita/admin_guide/ddl/ddl-tablespace.xml
+++ b/gpdb-doc/dita/admin_guide/ddl/ddl-tablespace.xml
@@ -53,6 +53,12 @@
 CREATE TABLE foo(i int);
 </codeblock>
      </p>
+      <p>There is also the <codeph>temp_tablespaces</codeph> configuration parameter, which
+        determines the placement of temporary tables and indexes, as well as temporary files that
+        are used for purposes such as sorting large data sets. This can be a comma-separate list of
+        tablespace names, rather than only one, so that the load associated with temporary objects
+        can be spread over multiple tablespaces. A random member of the list is picked each time a
+        temporary object is to be created.</p>
      <p>The tablespace associated with a database stores that database's system catalogs, temporary
        files created by server processes using that database, and is the default tablespace
        selected for tables and indexes created within the database, if no

--- a/gpdb-doc/dita/ref_guide/config_params/guc-list.xml
+++ b/gpdb-doc/dita/ref_guide/config_params/guc-list.xml
@@ -731,8 +731,7 @@
              <xref href="#stats_queue_level"/>
            </li>
            <li>
-              <xref href="#superuser_reserved_connections"/>
-            </li>
+              <xref href="#superuser_reserved_connections"/></li>
            <li>
              <xref href="#tcp_keepalives_count"/>
            </li>
@@ -745,6 +744,8 @@
            <li>
              <xref href="#temp_buffers"/>
            </li>
+            <li><xref href="#topic_k52_fqm_f3b" format="dita"/>
+            </li>
            <li>
              <xref href="#TimeZone"/>
            </li>
@@ -8758,6 +8759,51 @@ statement_mem = rg_perseg_mem / max_expected_concurrent_queries</codeblock></li>
      </table>
    </body>
  </topic>
+  <topic id="topic_k52_fqm_f3b">
+    <title>temp_tablespaces</title>
+    <body>
+      <p>Specifies tablespaces in which to create temporary objects (temp tables and indexes on temp
+        tables) when a <codeph>CREATE</codeph> command does not explicitly specify a tablespace.
+        Temporary files for purposes such as sorting large data sets are also created in these
+        tablespaces.</p>
+      <p>The value is a comma-separated list of names of tablespaces. When there is more than one name in the list,
+        Greenplum chooses a random member of the list each time a temporary object is to be created;
+        except that within a transaction, successively created temporary objects are placed in
+        successive tablespaces from the list. If the selected element of the list is an empty
+        string, Greenplum automatically uses the default tablespace of the current database
+        instead.</p>
+      <p>When <codeph>temp_tablespaces</codeph> is set interactively, specifying a nonexistent
+        tablespace is an error, as is specifying a tablespace for which the user does not have
+          <codeph>CREATE</codeph> privilege. However, when using a previously set value, nonexistent
+        tablespaces are ignored, as are tablespaces for which the user lacks <codeph>CREATE</codeph>
+        privilege. In particular, this rule applies when using a value set in
+          <codeph>postgresql.conf</codeph>.</p>
+      <p>The default value is an empty string, which results in all temporary objects being created
+        in the default tablespace of the current database.</p>
+      <p>See also <xref href="#default_tablespace" format="dita"/>.</p>
+      <table id="table_l52_fqm_f3b">
+        <tgroup cols="3">
+          <colspec colnum="1" colname="col1" colwidth="1*"/>
+          <colspec colnum="2" colname="col2" colwidth="1*"/>
+          <colspec colnum="3" colname="col3" colwidth="1*"/>
+          <thead>
+            <row>
+              <entry colname="col1">Value Range</entry>
+              <entry colname="col2">Default</entry>
+              <entry colname="col3">Set Classifications</entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry colname="col1">one or more tablespace names</entry>
+              <entry colname="col2">unset</entry>
+              <entry colname="col3">master<p>session</p><p>reload</p></entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+    </body>
+  </topic>
  <topic id="TimeZone">
    <title>TimeZone</title>
    <body>

--- a/gpdb-doc/dita/ref_guide/config_params/guc_category-list.xml
+++ b/gpdb-doc/dita/ref_guide/config_params/guc_category-list.xml
@@ -964,7 +964,7 @@
                <xref href="guc-list.xml#search_path" type="section">search_path</xref>
              </p><p>
                <xref href="guc-list.xml#statement_timeout" type="section">statement_timeout</xref>
-              </p><p>
+              </p><p><xref href="guc-list.xml#topic_k52_fqm_f3b"/></p><p>
                <xref href="guc-list.xml#vacuum_freeze_min_age" type="section"
                  >vacuum_freeze_min_age</xref>
              </p></stentry>

--- a/gpdb-doc/dita/ref_guide/config_params/guc_config.ditamap
+++ b/gpdb-doc/dita/ref_guide/config_params/guc_config.ditamap
@@ -270,6 +270,7 @@
            <topicref href="guc-list.xml#tcp_keepalives_idle"/>
            <topicref href="guc-list.xml#tcp_keepalives_interval"/>
            <topicref href="guc-list.xml#temp_buffers"/>
+            <topicref href="guc-list.xml#topic_k52_fqm_f3b"/>
            <topicref href="guc-list.xml#TimeZone"/>
            <topicref href="guc-list.xml#timezone_abbreviations"/>
            <topicref href="guc-list.xml#track_activity_query_size"/>

--- a/gpdb-doc/dita/ref_guide/sql_commands/CREATE_INDEX.xml
+++ b/gpdb-doc/dita/ref_guide/sql_commands/CREATE_INDEX.xml
@@ -236,7 +236,9 @@
                                                <varname>tablespace_name</varname>
                                        </pt>
                                        <pd>The tablespace in which to create the index. If not
-                                                specified, the default tablespace is used. </pd>
+                                                specified, the default tablespace is used, or <xref
+                                                  href="../config_params/guc-list.xml#topic_k52_fqm_f3b"
+                                                /> for indexes on temporary tables. </pd>
                                </plentry>
                                <plentry>
                                        <pt>

--- a/gpdb-doc/dita/ref_guide/sql_commands/CREATE_TABLE.xml
+++ b/gpdb-doc/dita/ref_guide/sql_commands/CREATE_TABLE.xml
@@ -560,13 +560,16 @@ CREATE [ [GLOBAL | LOCAL] {TEMPORARY | TEMP} | UNLOGGED ] TABLE [IF NOT EXISTS]
        <plentry>
          <pt>TABLESPACE <varname>tablespace</varname></pt>
          <pd>The name of the tablespace in which the new table is to be created. If not specified,
-            the database's default tablespace is used.</pd>
+            the database's default tablespace is used, or <xref
+              href="../config_params/guc-list.xml#topic_k52_fqm_f3b"/> if the table is
+            temporary.</pd>
        </plentry>
        <plentry>
          <pt>USING INDEX TABLESPACE <varname>tablespace</varname></pt>
          <pd>This clause allows selection of the tablespace in which the index associated with a
              <codeph>UNIQUE</codeph> or <codeph>PRIMARY KEY</codeph> constraint will be created. If
-            not specified, the database's default tablespace is used. </pd>
+            not specified, the database's default tablespace is used, or <xref
+              href="../config_params/guc-list.xml#topic_k52_fqm_f3b"/> if the table is temporary. </pd>
        </plentry>
        <plentry>
          <pt>DISTRIBUTED BY (<varname>column</varname> [<varname>opclass</varname>], [ ... ] )</pt>

--- a/gpdb-doc/dita/ref_guide/sql_commands/CREATE_TABLE_AS.xml
+++ b/gpdb-doc/dita/ref_guide/sql_commands/CREATE_TABLE_AS.xml
@@ -133,7 +133,8 @@
          <pt>TABLESPACE <varname>tablespace_name</varname></pt>
          <pd>The <varname>tablespace_name</varname> parameter is the name of the tablespace in
            which the new table is to be created. If not specified, the database's default
-            tablespace is used.</pd>
+            tablespace is used, or <xref href="../config_params/guc-list.xml#topic_k52_fqm_f3b"/> if
+            the table is temporary.</pd>
        </plentry>
        <plentry>
          <pt>AS <varname>query</varname></pt>

--- a/gpdb-doc/dita/ref_guide/sql_commands/DROP_TABLESPACE.xml
+++ b/gpdb-doc/dita/ref_guide/sql_commands/DROP_TABLESPACE.xml
@@ -2,11 +2,12 @@
 <!DOCTYPE topic
  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
 <topic id="topic1"><title id="dj20941">DROP TABLESPACE</title><body><p id="sql_command_desc">Removes a tablespace.</p><section id="section2"><title>Synopsis</title><codeblock id="sql_command_synopsis">DROP TABLESPACE [IF EXISTS] <varname>tablespacename</varname></codeblock></section><section id="section3"><title>Description</title><p><codeph>DROP TABLESPACE</codeph> removes a tablespace from the system.
-</p><p>A tablespace can only be dropped by its owner or a superuser. The
-tablespace must be empty of all database objects before it can be dropped.
-It is possible that objects in other databases may still reside in the
-tablespace even if no objects in the current database are using the tablespace.
-</p></section><section id="section4"><title>Parameters</title><parml><plentry><pt>IF EXISTS</pt><pd>Do not throw an error if the tablespace does not exist. A notice
+</p><p>A tablespace can only be dropped by its owner or a superuser. The tablespace must be empty of all
+        database objects before it can be dropped. It is possible that objects in other databases
+        may still reside in the tablespace even if no objects in the current database are using the
+        tablespace. Also, if the tablespace is listed in the <xref
+          href="../config_params/guc-list.xml#topic_k52_fqm_f3b"/> setting of any active session,
+        the <codeph>DROP</codeph> might fail due to temporary files residing in the tablespace.</p></section><section id="section4"><title>Parameters</title><parml><plentry><pt>IF EXISTS</pt><pd>Do not throw an error if the tablespace does not exist. A notice
 is issued in this case.</pd></plentry><plentry><pt><varname>tablespacename</varname></pt><pd>The name of the tablespace to remove.</pd></plentry></parml></section><section id="section5"><title>Examples</title><p>Remove the tablespace <codeph>mystuff</codeph>: </p><codeblock>DROP TABLESPACE mystuff;</codeblock></section><section id="section6"><title>Compatibility</title><p><codeph>DROP TABLESPACE</codeph> is a Greenplum Database extension.</p></section><section id="section7"><title>See Also</title><p><codeph><xref href="CREATE_TABLESPACE.xml#topic1" type="topic" format="dita"/></codeph>,
            <codeph><xref href="ALTER_TABLESPACE.xml#topic1" type="topic" format="dita"
        /></codeph></p></section></body></topic>