-
Notifications
You must be signed in to change notification settings - Fork 469
Add docs for CREATE TABLE ... AS OF SYSTEM TIME
#19674
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
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. |
bf54120
to
6b1ca8c
Compare
0c99b3d
to
a8f42f6
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
these changes lgtm!
i wasn't sure if @dikshant also wanted to have CREATE MATERIALIZED VIEW ... AS OF SYSTEM TIME
documented. i'll leave that decision to him.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Overall LGTM but One more example that I think we should add!
I'll do it in another PR! would rather get this smaller one now in so folks can start using this ASAP |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Couple suggestions...
@@ -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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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