Add docs for CREATE TABLE ... AS OF SYSTEM TIME
#19674
Conversation
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
rmloveland
force-pushed
the
20250529-DOC-13310-ctas-aost
branch
3 times, most recently
from
bf54120 to
6b1ca8c
Compare
rmloveland
force-pushed
the
20250529-DOC-13310-ctas-aost
branch
from
0c99b3d to
a8f42f6
Compare
|
Yeah we also want the materialized view part to be documented. But I'll leave it to Rich to decide if he wants to do that in this PR or a new one. |
I'll do it in another PR! would rather get this smaller one now in so folks can start using this ASAP |
| @@ -22,6 +22,8 @@ When the results of a query are reused multiple times within a larger query, a v | |||
|
|
|||
| A view is also advisable when the results must be up-to-date; a view always retrieves the current data from the tables that the view query mentions. | |||
|
|
|||
| {% include_cached new-in.html version="v25.2" %} Use `CREATE TABLE t AS ...` with the [`AS OF SYSTEM TIME` clause](#populate-create-table-as-with-historical-data-using-as-of-system-time) to leverage [historical reads]({% link {{ page.version.version }}/as-of-system-time.md %}) to reduce contention and improve performance. | |||
There was a problem hiding this comment.
Is there a reason AS OF SYSTEM TIME isn't in the SQL diagram? I think that it should be, since it's present in other statements like https://www.cockroachlabs.com/docs/v25.2/select-clause https://www.cockroachlabs.com/docs/v25.2/restore https://www.cockroachlabs.com/docs/v25.2/begin-transaction
Oh, is it because this clause is folded into the SELECT statement that is under a param in the diagram? If so, it might be better to link the select_stmt row in the Parameters table to https://www.cockroachlabs.com/docs/v25.2/select-clause instead of the more complex selection-queries page, unless I'm missing a technical reason for doing so.
| The timestamp must be within the [garbage collection (GC) window]({% link {{ page.version.version }}/architecture/storage-layer.md %}#garbage-collection) of the source table for the data to be available. | ||
| {{site.data.alerts.end}} | ||
|
|
||
| The syntax for creating a new table from a historical table at a given timestamp is as follows; this example creates a new table at the most recent timestamp that can perform a [follower read]({% link {{ page.version.version }}/follower-reads.md %}). |
There was a problem hiding this comment.
| The syntax for creating a new table from a historical table at a given timestamp is as follows; this example creates a new table at the most recent timestamp that can perform a [follower read]({% link {{ page.version.version }}/follower-reads.md %}). | |
| The following example creates a new table at the most recent timestamp that can perform a [follower read]({% link {{ page.version.version }}/follower-reads.md %}). |
| AS SELECT * FROM vehicle_location_histories | ||
| AS OF SYSTEM TIME follower_read_timestamp(); | ||
| ~~~ | ||
|
|
There was a problem hiding this comment.
Is it possible to show some SELECT output with some meaningful timestamps? Or at least the usual CREATE TABLE AS output that confirms the table creation?
Also, when I tested this statement, i got an error ERROR: no database or schema specified. the statement only worked when i either ran the previous example first (CREATE TABLE users_ny_alt (id PRIMARY KEY FAMILY ids, name, city FAMILY locs, address, credit_card FAMILY payments) AS SELECT id, name, city, address, credit_card FROM users WHERE city = 'new york';) or specifed the AS table as movr.vehicle_location_histories. Could probably use a caveat or callout somewhere to set or specify the schema? I don't really understand this behavior.
| DROP TABLE customers; | ||
| ~~~ | ||
|
|
||
| 1. Restore the table using the [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}) clause: |
There was a problem hiding this comment.
| 1. Restore the table using the [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}) clause: | |
| 1. Restore the table using the [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}) clause and the timestamp you obtained before dropping the table: |
| INSERT INTO customers (id, name) VALUES (1, 'Alice'), (2, 'Bob'); | ||
| ~~~ | ||
|
|
||
| 1. Get a timestamp from before the table is deleted: |
There was a problem hiding this comment.
| 1. Get a timestamp from before the table is deleted: | |
| 1. Get a timestamp before the table is deleted in an upcoming step: |
Fixes DOC-13310