docs: document the tiered data and Iceberg format version sync properties

[alejandrodnm]

Describe your changes

Two tigerlake.* table properties shipped in timescaledb-lake 0.7.2 without docs. Both are set on the ALTER TABLE statement that starts an Iceberg sync, so both belong on the same page.

Tiered data. Syncing tiered data used to be impossible, and this page listed it as a flat limitation. It is now opt-in per table via tigerlake.enable_tiered_reads, so the limitation is no longer absolute. Adds a Tiered data subsection covering how to turn it on, the fact that it can only be set in the statement that starts the sync, its independence from the timescaledb.enable_tiered_reads GUC, and the snapshot cost of including tiered history. The limitation bullet becomes conditional rather than absolute.

Iceberg format version. tigerlake.iceberg_spec_version was never documented at all; the docs had no mention of Iceberg format versions anywhere. Adds an Iceberg format version subsection covering the accepted values, the v3 default for new syncs, the set-at-sync-start restriction, and the fact that tables that started syncing before the property existed stay on v2.

Both properties are also added to the reference ALTER TABLE statement and its option list.

Every behavioral claim was verified against the extension source (timescaledb-lake) rather than inferred: the accepted values, the set-at-sync-start restriction, and the errors on changing either property afterwards come from the validation in src/sync_config.rs; the defaults come from sql/tables.sql; and the "pre-existing syncs stay on v2" behavior comes from the upgrade script in sql/latest-dev.sql.

Affected pages

• /integrate/connectors/destination/tigerlake

• 🧪 Component kitchen sink — check for visual regressions if you changed components, styles, or dependencies.

Related Issues

Issue: #number

Extension side: timescale/timescaledb-lake#142 added iceberg_spec_version, timescale/timescaledb-lake#148 added enable_tiered_reads, and timescale/timescaledb-lake#151 fixes the latter's upgrade path.

Checklist before requesting a review

• - This is ready for review. If not, raise as a draft PR
• - I have reviewed my changes.
• - I have confirmed the content is technically accurate.
• - I have tested any code that is added or updated on the latest available version.
• - I have confirmed the content is free of typos or grammar errors.
• - I have verified all images and videos are clear and match production (or dev for unreleased features).
• - I have checked the component kitchen sink for any visual breakage (only needed if you changed components, styles, or dependencies). A link to this PR's own preview appears under Affected pages once the build deploys.
• - This references a feature that is public. If not, add a note and we can schedule the merge for after the feature release.

Notes on the unchecked items:

Neither feature is public yet. Both landed after the v0.7.1 tag and sit in 0.7.2-dev, unreleased. Please schedule this for after that release. Draft until then.

One documented behavior is not live yet. The Tiered data subsection states that setting tigerlake.enable_tiered_reads to false keeps tiered data out of Iceberg even when the timescaledb.enable_tiered_reads GUC is enabled for the database. That is the agreed target behavior, but today false is a no-op that inherits the GUC. It depends on timescale/timescaledb-lake#151 plus a matching sink change landing first. Worth re-reading that bullet before merge. Nothing in the Iceberg format version subsection has this caveat.

No images, videos, or component changes, so those items are not applicable. I verified rendering locally and confirmed both new anchors and every internal and external link resolve, but I did not run an end-to-end sync of either kind, hence the untested-code item.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
tiger-data-docs	Ready	Preview	Aug 24, 2026 3:41pm

[erinmikailstaples]

hey @alejandrodnm closing this as it appears to be resolved with the linked PR.

[alejandrodnm]

@erinmikailstaples the linked PR is to expose the feature in the UI. That's behind a feature flag, we haven't deployed this features yet, the docs are still needed.