Update temp tables docs re: perf caveats vs CTEs #20221
Open
+15
−1
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
rafiss
approved these changes
Aug 27, 2025
taroface
approved these changes
Aug 28, 2025
| @@ -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 %}) may choose whether to materialize them. | |||
There was a problem hiding this comment.
Suggested change
| 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 %}) may choose whether to materialize them. | |
| 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. |
| @@ -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. | |||
There was a problem hiding this comment.
Can we say "slower than alternatives such as [x]"?
| ## 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. | ||
| - 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 job]({% link {{ page.version.version }}/show-jobs.md %}) and degrade overall cluster performance. |
There was a problem hiding this comment.
Suggested change
| - 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 job]({% link {{ page.version.version }}/show-jobs.md %}) and degrade overall cluster performance. | |
| - Avoid patterns that create and drop very large numbers of temporary 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. |
|
|
||
| - 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. | ||
| - 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 job]({% link {{ page.version.version }}/show-jobs.md %}) and degrade overall cluster performance. | ||
| - Prefer [common table expressions (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. |
There was a problem hiding this comment.
Suggested change
| - Prefer [common table expressions (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. | |
| - Prefer [common table expressions (CTEs)]({% link {{ page.version.version }}/common-table-expressions.md %}) for intermediate results where possible. If you do use temporary 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. |
| @@ -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). | |||
There was a problem hiding this comment.
Suggested change
| 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). | |
| For intermediate results, consider using [common table expressions (CTEs)]({% link {{ page.version.version }}/common-table-expressions.md %}#overview) instead of temporary tables. For more information, see [Performance considerations](#performance-considerations). |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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