Skip to content

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

rmloveland
Copy link
Contributor

Fixes DOC-13310

@rmloveland rmloveland marked this pull request as draft May 29, 2025 20:45
Copy link

netlify bot commented May 29, 2025

Deploy Preview for cockroachdb-api-docs canceled.

Name Link
🔨 Latest commit a37be22
🔍 Latest deploy log https://app.netlify.com/projects/cockroachdb-api-docs/deploys/68473e28342bbb000857e41f

Copy link

github-actions bot commented May 29, 2025

Copy link

netlify bot commented May 29, 2025

Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Name Link
🔨 Latest commit a37be22
🔍 Latest deploy log https://app.netlify.com/projects/cockroachdb-interactivetutorials-docs/deploys/68473e28a4bfb600080379a5

Copy link

netlify bot commented May 29, 2025

Netlify Preview

Name Link
🔨 Latest commit a37be22
🔍 Latest deploy log https://app.netlify.com/projects/cockroachdb-docs/deploys/68473e2885ac8d0008d09835
😎 Deploy Preview https://deploy-preview-19674--cockroachdb-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@rmloveland rmloveland force-pushed the 20250529-DOC-13310-ctas-aost branch 3 times, most recently from bf54120 to 6b1ca8c Compare June 4, 2025 17:49
@rmloveland rmloveland force-pushed the 20250529-DOC-13310-ctas-aost branch from 0c99b3d to a8f42f6 Compare June 4, 2025 19:03
@rmloveland rmloveland marked this pull request as ready for review June 4, 2025 19:12
@rmloveland rmloveland requested review from rafiss and dikshant June 4, 2025 19:13
Copy link
Contributor

@rafiss rafiss left a 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.

@dikshant
Copy link

dikshant commented Jun 9, 2025

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.

Copy link

@dikshant dikshant left a 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!

@rmloveland rmloveland requested a review from taroface June 9, 2025 20:04
@rmloveland
Copy link
Contributor Author

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

Copy link
Contributor

@taroface taroface left a 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.
Copy link
Contributor

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 %}).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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();
~~~

Copy link
Contributor

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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
1. Get a timestamp from before the table is deleted:
1. Get a timestamp before the table is deleted in an upcoming step:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants