Skip to content

[doc](lakehouse) Document timestamp compatibility changes#3982

Open
Gabriel39 wants to merge 1 commit into
apache:masterfrom
Gabriel39:agent/document-int96-timezone-behavior
Open

[doc](lakehouse) Document timestamp compatibility changes#3982
Gabriel39 wants to merge 1 commit into
apache:masterfrom
Gabriel39:agent/document-int96-timezone-behavior

Conversation

@Gabriel39

Copy link
Copy Markdown
Contributor

What problem does this PR solve?

Related Doris PR: apache/doris#65446

The Doris change updates timestamp handling in FileScannerV2 and Parquet export, but the user-visible compatibility rules and migration options were not documented. Without this context, users can accidentally introduce an eight-hour shift while trying to compensate for legacy Parquet INT96 writer behavior.

What is changed?

  • Document that FileScannerV2 preserves raw Parquet INT96 wall-clock fields by default, while Parquet INT64 logical timestamps retain their standard semantics.
  • Document the Hive Catalog and external-file TVF compatibility property hive.parquet.time-zone, including validation, examples, scope, V1/V2 behavior, and TIMESTAMPTZ handling.
  • Explain why the property is Catalog-wide for Hive INT96 columns mapped to DATETIMEV2, and recommend separating files written with different conventions.
  • Document round-half-up conversion from ORC nanoseconds to Doris microseconds, including second carry and conservative predicate pruning.
  • Correct the Parquet export property name to enable_int96_timestamps and describe its default, INT96/INT64 result, and asynchronous Export persistence.
  • Keep the English and Simplified Chinese current documentation synchronized.

Only current documentation is updated because apache/doris#65446 targets unmerged master behavior. Published 4.x, 3.x, 2.1, and Japanese documentation are intentionally unchanged.

Validation

  • git diff --check — passed.
  • yarn docs:features:changed — passed with no findings.
  • yarn docs:i18n-sync:changed — English/Chinese current pages are synchronized; expected warnings remain for intentionally unchanged published versions and Japanese docs.
  • yarn docs:links:changed / yarn docs:lint:changed — no new link issues from this change; the commands report existing missing Hive Catalog anchors and existing repository-wide SEO/Markdown findings.
  • yarn key-features:generate
  • ./local_dev.sh build-all --versions current --skip-install --max-mem 8192 — generated English and Chinese current site output; the build reports existing repository-wide broken-link warnings.

@Gabriel39 Gabriel39 marked this pull request as ready for review July 14, 2026 06:22
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.

1 participant