Document Iceberg time travel & snapshot queries

[findinpath]

Description

Document Iceberg time travel & snapshot queries

Related issues, pull requests, and links

Fixes #12745

There are 2 ongoing PRs both trying to offer (with different approaches) the ability to do time travel on metadata tables:

• Support snapshot queries on Iceberg system tables - custom IcebergSystemTableHandle extends SystemTableHandle #13854
• Support snapshot queries on Iceberg system tables - IcebergSystemTableHandle is a ConnectorTableHandle with custom instanceof handling in IcebergMetadata #13497

If any of the above mentioned PRs land, we'll need to update the documentation.

Documentation

( ) No documentation is needed.
(x) Sufficient documentation is included in this PR.
( ) Documentation PR is available with #prnumber.
( ) Documentation issue #issuenumber is filed, and can be handled later.

[phd3]

LGTM, % nits.

IIRC @electrum had an opinion on whether to document snapshot querying at all. but can't find relevant PR/issue now.

[phd3]

nit: can we avoid double newlines for uniformity in this file?

[hashhar]

If we have plans to use the new AS OF syntax for querying snapshots then I believe we should hold on documenting this for now since it'll likely require users to change queries on their end eventually.

[findinpath]

If we have plans to use the new AS OF syntax for querying snapshots then I believe we should hold on documenting this for now since it'll likely require users to change queries on their end eventually.

The functionality is already provided in Trino. I see currently no harm in documenting it.

[electrum]

I agree with @hashhar. We should implement the new AS OF functionality for Iceberg (it is already supported in the engine) and deprecate this existing functionality. Ideally, we can remove it in the future. Documenting it now will cause more people to use it and make it harder to remove later.

[electrum]

The existing Iceberg syntax is problematic since the number can mean both a specific snapshot ID or an "as of" timestamp. Due to the snapshot IDs being random and overlapping with the timestamp space, a query relying on it as a snapshot may return incorrect results if the timestamp value happens to be a snapshot ID.

It should be easy to implement the AS OF functionality for Iceberg. See the new ConnectorMetadata.isSupportedVersionType() and ConnectorMetadata.getTableHandle(ConnectorSession, SchemaTableName, Optional<ConnectorTableVersion>, Optional<ConnectorTableVersion>) APIs.

[phd3]

sounds good, seems like this is close: #10258 @findinpath we'd need docs after the above gets merged, so we can update this one afterwards or just create a new one.

[kbendick]

This looks good to me. Found my way over to some of these Iceberg documentation PRs based on questions asked in the Iceberg slack workspace. 👋

[kbendick]

Nit: an snapshot -> a snapshot.

This might be a good place to move the introduction of the hidden metadata table "$snapshots" as well.

Though given you're not touching that paragraph, it's totally up to you 🙂

[findinpath]

Modified to snapshots are identified by a snapshot ID

[kbendick]

My bad. I missed the comment from @phd3 above. I found my way here as there was a lot of discussion in the Iceberg slack workspace on Trino docs recently. But agreed with the comments above about potential collisions with snapshot ID and timestamps.