Update temp tables docs re: perf caveats vs CTEs (#20221)

Fixes DOC-13355

Summary of changes:

- Update temp tables docs with a 'perf considerations' section that
  warns users about possible perf impacts incl. schema change GC risk,
  recommends CTEs

- Update temp table docs 'examples' section to mention CTEs as an
  alternative

- Update CTE docs to mention that they can be used instead of temp
  tables

- Update the feature availability page re: temp tables to add more info
  re: schema change GC risk

NB. Applied changes to supported versions v24.1+

Author: rmloveland

src/current/v24.1/cockroachdb-feature-availability.md

@@ -175,7 +175,7 @@ CockroachDB supports [altering the column types]({% link {{ page.version.version
 
 ### Temporary objects
 
-[Temporary tables]({% link {{ page.version.version }}/temporary-tables.md %}), [temporary views]({% link {{ page.version.version }}/views.md %}#temporary-views), and [temporary sequences]({% link {{ page.version.version }}/create-sequence.md %}#temporary-sequences) are in preview in CockroachDB. If you create too many temporary objects in a session, the performance of DDL operations will degrade. Performance limitations could persist long after creating the temporary objects. For more details, see [cockroachdb/cockroach#46260](https://github.com/cockroachdb/cockroach/issues/46260).
+[Temporary tables]({% link {{ page.version.version }}/temporary-tables.md %}), [temporary views]({% link {{ page.version.version }}/views.md %}#temporary-views), and [temporary sequences]({% link {{ page.version.version }}/create-sequence.md %}#temporary-sequences) are in preview in CockroachDB. If you create too many temporary objects in a session, the performance of DDL operations will degrade. Dropping large numbers of temporary objects in rapid succession can also enqueue many [schema change GC jobs]({% link {{ page.version.version }}/show-jobs.md %}), which may further degrade cluster performance. This performance degradation could persist long after creating the temporary objects. For more details, see [cockroachdb/cockroach#46260](https://github.com/cockroachdb/cockroach/issues/46260).
 
 To enable temporary objects, set the `experimental_enable_temp_tables` [session variable]({% link {{ page.version.version }}/show-vars.md %}) to `on`.
 

src/current/v24.1/common-table-expressions.md

@@ -9,6 +9,8 @@ A _common table expression_ (CTE), also called a `WITH` query, provides a shorth
 
 You can use CTEs in combination with [`SELECT` clauses]({% link {{ page.version.version }}/select-clause.md %}) and [`INSERT`]({% link {{ page.version.version }}/insert.md %}), [`DELETE`]({% link {{ page.version.version }}/delete.md %}), [`UPDATE`]({% link {{ page.version.version }}/update.md %}), and [`UPSERT`](upsert.html) data-modifying statements.
 
+For many workloads, CTEs are an effective alternative to [temporary tables]({% link {{ page.version.version }}/temporary-tables.md %}) for intermediate results within a single statement. CTEs avoid the [performance overhead of temp tables]({% link {{ page.version.version }}/temporary-tables.md %}#performance-considerations), and the [optimizer]({% link {{ page.version.version }}/cost-based-optimizer.md %}) can choose whether to materialize them.
+
 ## Synopsis
 
 <div>
@@ -474,3 +476,4 @@ CTEs containing statements (`INSERT`, `UPSERT`, `UPDATE`, `DELETE`) that modify
 - [Selection Queries]({% link {{ page.version.version }}/selection-queries.md %})
 - [Table Expressions]({% link {{ page.version.version }}/table-expressions.md %})
 - [`EXPLAIN`]({% link {{ page.version.version }}/explain.md %})
+- [Temporary tables]({% link {{ page.version.version }}/temporary-tables.md %})

src/current/v24.1/temporary-tables.md

@@ -30,6 +30,12 @@ CockroachDB also supports [temporary views]({% link {{ page.version.version }}/v
 
 By default, every 30 minutes CockroachDB cleans up all temporary objects that are not tied to an active session. You can change how often the cleanup job runs with the `sql.temp_object_cleaner.cleanup_interval` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}).
 
+## Performance considerations
+
+- Temporary tables are not optimized for performance. They use the same underlying mechanisms as "regular" tables, and may be slower than expected compared to alternatives such as [common table expressions (CTEs)]({% link {{ page.version.version }}/common-table-expressions.md %}).
+- Avoid patterns that create and drop very large numbers of temp tables in rapid succession. Creating and dropping large numbers of temp tables can enqueue many [schema change GC jobs]({% link {{ page.version.version }}/show-jobs.md %}) and degrade overall cluster performance.
+- Prefer [CTEs]({% link {{ page.version.version }}/common-table-expressions.md %}) for intermediate results where possible. If you do use temp tables instead of CTEs, consider reusing a small set of temp tables with [`TRUNCATE`]({% link {{ page.version.version }}/truncate.md %}) instead of repeatedly creating and dropping new ones. Always test both approaches for your workload.
+
 ## Temporary schemas
 
 Temp tables are not part of the `public` schema. Instead, when you create the first temp table for a session, CockroachDB generates a single temporary schema (`pg_temp_<id>`) for all of the temp tables, [temporary views]({% link {{ page.version.version }}/views.md %}#temporary-views), and [temporary sequences]({% link {{ page.version.version }}/create-sequence.md %}#temporary-sequences) in the current session for a database. In a session, you can reference the session's temporary schema as `pg_temp`.
@@ -40,6 +46,10 @@ Because the [`SHOW TABLES`]({% link {{ page.version.version }}/show-tables.md %}
 
 ## Examples
 
+{{site.data.alerts.callout_info}}
+For intermediate results, consider using [common table expressions (CTEs)]({% link {{ page.version.version }}/common-table-expressions.md %}#overview) instead of temp tables. For more information, see [Performance considerations](#performance-considerations).
+{{site.data.alerts.end}}
+
 To use temp tables, you need to set `experimental_enable_temp_tables` to `on`:
 
 {% include_cached copy-clipboard.html %}
@@ -221,3 +231,4 @@ SQLSTATE: 42P01
 - [`SHOW CREATE TABLE`]({% link {{ page.version.version }}/show-create.md %})
 - [Temporary views]({% link {{ page.version.version }}/views.md %}#temporary-views)
 - [Temporary sequences]({% link {{ page.version.version }}/create-sequence.md %}#temporary-sequences).
+- [Common table expressions (CTEs)]({% link {{ page.version.version }}/common-table-expressions.md %})

src/current/v24.3/cockroachdb-feature-availability.md

@@ -204,7 +204,7 @@ CockroachDB supports [altering the column types]({% link {{ page.version.version
 
 ### Temporary objects
 
-[Temporary tables]({% link {{ page.version.version }}/temporary-tables.md %}), [temporary views]({% link {{ page.version.version }}/views.md %}#temporary-views), and [temporary sequences]({% link {{ page.version.version }}/create-sequence.md %}#temporary-sequences) are in preview in CockroachDB. If you create too many temporary objects in a session, the performance of DDL operations will degrade. Performance limitations could persist long after creating the temporary objects. For more details, see [cockroachdb/cockroach#46260](https://github.com/cockroachdb/cockroach/issues/46260).
+[Temporary tables]({% link {{ page.version.version }}/temporary-tables.md %}), [temporary views]({% link {{ page.version.version }}/views.md %}#temporary-views), and [temporary sequences]({% link {{ page.version.version }}/create-sequence.md %}#temporary-sequences) are in preview in CockroachDB. If you create too many temporary objects in a session, the performance of DDL operations will degrade. Dropping large numbers of temporary objects in rapid succession can also enqueue many [schema change GC jobs]({% link {{ page.version.version }}/show-jobs.md %}), which may further degrade cluster performance. This performance degradation could persist long after creating the temporary objects. For more details, see [cockroachdb/cockroach#46260](https://github.com/cockroachdb/cockroach/issues/46260).
 
 To enable temporary objects, set the `experimental_enable_temp_tables` [session variable]({% link {{ page.version.version }}/show-vars.md %}) to `on`.
 

src/current/v24.3/common-table-expressions.md

@@ -9,6 +9,8 @@ A _common table expression_ (CTE), also called a `WITH` query, provides a shorth
 
 You can use CTEs in combination with [`SELECT` clauses]({% link {{ page.version.version }}/select-clause.md %}) and [`INSERT`]({% link {{ page.version.version }}/insert.md %}), [`DELETE`]({% link {{ page.version.version }}/delete.md %}), [`UPDATE`]({% link {{ page.version.version }}/update.md %}), and [`UPSERT`](upsert.html) data-modifying statements.
 
+For many workloads, CTEs are an effective alternative to [temporary tables]({% link {{ page.version.version }}/temporary-tables.md %}) for intermediate results within a single statement. CTEs avoid the [performance overhead of temp tables]({% link {{ page.version.version }}/temporary-tables.md %}#performance-considerations), and the [optimizer]({% link {{ page.version.version }}/cost-based-optimizer.md %}) can choose whether to materialize them.
+
 ## Synopsis
 
 <div>
@@ -474,3 +476,4 @@ CTEs containing statements (`INSERT`, `UPSERT`, `UPDATE`, `DELETE`) that modify
 - [Selection Queries]({% link {{ page.version.version }}/selection-queries.md %})
 - [Table Expressions]({% link {{ page.version.version }}/table-expressions.md %})
 - [`EXPLAIN`]({% link {{ page.version.version }}/explain.md %})
+- [Temporary tables]({% link {{ page.version.version }}/temporary-tables.md %})

src/current/v24.3/temporary-tables.md

@@ -30,6 +30,12 @@ CockroachDB also supports [temporary views]({% link {{ page.version.version }}/v
 
 By default, every 30 minutes CockroachDB cleans up all temporary objects that are not tied to an active session. You can change how often the cleanup job runs with the `sql.temp_object_cleaner.cleanup_interval` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}).
 
+## Performance considerations
+
+- Temporary tables are not optimized for performance. They use the same underlying mechanisms as "regular" tables, and may be slower than expected compared to alternatives such as [common table expressions (CTEs)]({% link {{ page.version.version }}/common-table-expressions.md %}).
+- Avoid patterns that create and drop very large numbers of temp tables in rapid succession. Creating and dropping large numbers of temp tables can enqueue many [schema change GC jobs]({% link {{ page.version.version }}/show-jobs.md %}) and degrade overall cluster performance.
+- Prefer [CTEs]({% link {{ page.version.version }}/common-table-expressions.md %}) for intermediate results where possible. If you do use temp tables instead of CTEs, consider reusing a small set of temp tables with [`TRUNCATE`]({% link {{ page.version.version }}/truncate.md %}) instead of repeatedly creating and dropping new ones. Always test both approaches for your workload.
+
 ## Temporary schemas
 
 Temp tables are not part of the `public` schema. Instead, when you create the first temp table for a session, CockroachDB generates a single temporary schema (`pg_temp_<id>`) for all of the temp tables, [temporary views]({% link {{ page.version.version }}/views.md %}#temporary-views), and [temporary sequences]({% link {{ page.version.version }}/create-sequence.md %}#temporary-sequences) in the current session for a database. In a session, you can reference the session's temporary schema as `pg_temp`.
@@ -40,6 +46,10 @@ Because the [`SHOW TABLES`]({% link {{ page.version.version }}/show-tables.md %}
 
 ## Examples
 
+{{site.data.alerts.callout_info}}
+For intermediate results, consider using [common table expressions (CTEs)]({% link {{ page.version.version }}/common-table-expressions.md %}#overview) instead of temp tables. For more information, see [Performance considerations](#performance-considerations).
+{{site.data.alerts.end}}
+
 To use temp tables, you need to set `experimental_enable_temp_tables` to `on`:
 
 {% include_cached copy-clipboard.html %}
@@ -221,3 +231,4 @@ SQLSTATE: 42P01
 - [`SHOW CREATE TABLE`]({% link {{ page.version.version }}/show-create.md %})
 - [Temporary views]({% link {{ page.version.version }}/views.md %}#temporary-views)
 - [Temporary sequences]({% link {{ page.version.version }}/create-sequence.md %}#temporary-sequences).
+- [Common table expressions (CTEs)]({% link {{ page.version.version }}/common-table-expressions.md %})

src/current/v25.1/cockroachdb-feature-availability.md

@@ -200,7 +200,7 @@ The [`SHOW RANGE ... FOR ROW`]({% link {{ page.version.version }}/show-range-for
 
 ### Temporary objects
 
-[Temporary tables]({% link {{ page.version.version }}/temporary-tables.md %}), [temporary views]({% link {{ page.version.version }}/views.md %}#temporary-views), and [temporary sequences]({% link {{ page.version.version }}/create-sequence.md %}#temporary-sequences) are in preview in CockroachDB. If you create too many temporary objects in a session, the performance of DDL operations will degrade. Performance limitations could persist long after creating the temporary objects. For more details, see [cockroachdb/cockroach#46260](https://github.com/cockroachdb/cockroach/issues/46260).
+[Temporary tables]({% link {{ page.version.version }}/temporary-tables.md %}), [temporary views]({% link {{ page.version.version }}/views.md %}#temporary-views), and [temporary sequences]({% link {{ page.version.version }}/create-sequence.md %}#temporary-sequences) are in preview in CockroachDB. If you create too many temporary objects in a session, the performance of DDL operations will degrade. Dropping large numbers of temporary objects in rapid succession can also enqueue many [schema change GC jobs]({% link {{ page.version.version }}/show-jobs.md %}), which may further degrade cluster performance. This performance degradation could persist long after creating the temporary objects. For more details, see [cockroachdb/cockroach#46260](https://github.com/cockroachdb/cockroach/issues/46260).
 
 To enable temporary objects, set the `experimental_enable_temp_tables` [session variable]({% link {{ page.version.version }}/show-vars.md %}) to `on`.
 

src/current/v25.1/common-table-expressions.md

@@ -9,6 +9,8 @@ A _common table expression_ (CTE), also called a `WITH` query, provides a shorth
 
 You can use CTEs in combination with [`SELECT` clauses]({% link {{ page.version.version }}/select-clause.md %}) and [`INSERT`]({% link {{ page.version.version }}/insert.md %}), [`DELETE`]({% link {{ page.version.version }}/delete.md %}), [`UPDATE`]({% link {{ page.version.version }}/update.md %}), and [`UPSERT`](upsert.html) data-modifying statements.
 
+For many workloads, CTEs are an effective alternative to [temporary tables]({% link {{ page.version.version }}/temporary-tables.md %}) for intermediate results within a single statement. CTEs avoid the [performance overhead of temp tables]({% link {{ page.version.version }}/temporary-tables.md %}#performance-considerations), and the [optimizer]({% link {{ page.version.version }}/cost-based-optimizer.md %}) can choose whether to materialize them.
+
 ## Synopsis
 
 <div>
@@ -474,3 +476,4 @@ CTEs containing statements (`INSERT`, `UPSERT`, `UPDATE`, `DELETE`) that modify
 - [Selection Queries]({% link {{ page.version.version }}/selection-queries.md %})
 - [Table Expressions]({% link {{ page.version.version }}/table-expressions.md %})
 - [`EXPLAIN`]({% link {{ page.version.version }}/explain.md %})
+- [Temporary tables]({% link {{ page.version.version }}/temporary-tables.md %})

src/current/v25.1/temporary-tables.md

@@ -30,6 +30,12 @@ CockroachDB also supports [temporary views]({% link {{ page.version.version }}/v
 
 By default, every 30 minutes CockroachDB cleans up all temporary objects that are not tied to an active session. You can change how often the cleanup job runs with the `sql.temp_object_cleaner.cleanup_interval` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}).
 
+## Performance considerations
+
+- Temporary tables are not optimized for performance. They use the same underlying mechanisms as "regular" tables, and may be slower than expected compared to alternatives such as [common table expressions (CTEs)]({% link {{ page.version.version }}/common-table-expressions.md %}).
+- Avoid patterns that create and drop very large numbers of temp tables in rapid succession. Creating and dropping large numbers of temp tables can enqueue many [schema change GC jobs]({% link {{ page.version.version }}/show-jobs.md %}) and degrade overall cluster performance.
+- Prefer [CTEs]({% link {{ page.version.version }}/common-table-expressions.md %}) for intermediate results where possible. If you do use temp tables instead of CTEs, consider reusing a small set of temp tables with [`TRUNCATE`]({% link {{ page.version.version }}/truncate.md %}) instead of repeatedly creating and dropping new ones. Always test both approaches for your workload.
+
 ## Temporary schemas
 
 Temp tables are not part of the `public` schema. Instead, when you create the first temp table for a session, CockroachDB generates a single temporary schema (`pg_temp_<id>`) for all of the temp tables, [temporary views]({% link {{ page.version.version }}/views.md %}#temporary-views), and [temporary sequences]({% link {{ page.version.version }}/create-sequence.md %}#temporary-sequences) in the current session for a database. In a session, you can reference the session's temporary schema as `pg_temp`.
@@ -40,6 +46,10 @@ Because the [`SHOW TABLES`]({% link {{ page.version.version }}/show-tables.md %}
 
 ## Examples
 
+{{site.data.alerts.callout_info}}
+For intermediate results, consider using [common table expressions (CTEs)]({% link {{ page.version.version }}/common-table-expressions.md %}#overview) instead of temp tables. For more information, see [Performance considerations](#performance-considerations).
+{{site.data.alerts.end}}
+
 To use temp tables, you need to set `experimental_enable_temp_tables` to `on`:
 
 {% include_cached copy-clipboard.html %}
@@ -221,3 +231,4 @@ SQLSTATE: 42P01
 - [`SHOW CREATE TABLE`]({% link {{ page.version.version }}/show-create.md %})
 - [Temporary views]({% link {{ page.version.version }}/views.md %}#temporary-views)
 - [Temporary sequences]({% link {{ page.version.version }}/create-sequence.md %}#temporary-sequences).
+- [Common table expressions (CTEs)]({% link {{ page.version.version }}/common-table-expressions.md %})

src/current/v25.2/cockroachdb-feature-availability.md

@@ -214,7 +214,7 @@ The [`SHOW RANGE ... FOR ROW`]({% link {{ page.version.version }}/show-range-for
 
 ### Temporary objects
 
-[Temporary tables]({% link {{ page.version.version }}/temporary-tables.md %}), [temporary views]({% link {{ page.version.version }}/views.md %}#temporary-views), and [temporary sequences]({% link {{ page.version.version }}/create-sequence.md %}#temporary-sequences) are in preview in CockroachDB. If you create too many temporary objects in a session, the performance of DDL operations will degrade. Performance limitations could persist long after creating the temporary objects. For more details, see [cockroachdb/cockroach#46260](https://github.com/cockroachdb/cockroach/issues/46260).
+[Temporary tables]({% link {{ page.version.version }}/temporary-tables.md %}), [temporary views]({% link {{ page.version.version }}/views.md %}#temporary-views), and [temporary sequences]({% link {{ page.version.version }}/create-sequence.md %}#temporary-sequences) are in preview in CockroachDB. If you create too many temporary objects in a session, the performance of DDL operations will degrade. Dropping large numbers of temporary objects in rapid succession can also enqueue many [schema change GC jobs]({% link {{ page.version.version }}/show-jobs.md %}), which may further degrade cluster performance. This performance degradation could persist long after creating the temporary objects. For more details, see [cockroachdb/cockroach#46260](https://github.com/cockroachdb/cockroach/issues/46260).
 
 To enable temporary objects, set the `experimental_enable_temp_tables` [session variable]({% link {{ page.version.version }}/show-vars.md %}) to `on`.