[doc](lakehouse) Document timestamp compatibility changes#3982
Open
Gabriel39 wants to merge 1 commit into
Open
[doc](lakehouse) Document timestamp compatibility changes#3982Gabriel39 wants to merge 1 commit into
Gabriel39 wants to merge 1 commit into
Conversation
Gabriel39
marked this pull request as ready for review
July 14, 2026 06:22
Gabriel39
added a commit
to Gabriel39/incubator-doris
that referenced
this pull request
Jul 15, 2026
### What problem does this PR solve? Issue Number: None Related PR: apache#65446 Problem Summary: Timestamp decoding had two correctness problems in scanner v2. Parquet INT96 does not carry a timezone annotation, so applying the Doris SQL session timezone shifted raw wall-clock fields written by Trino/UTC-style writers. ORC nanoseconds were truncated inconsistently across row decoding, statistics, and SARG predicates, which could also produce unsafe pruning at millisecond statistic boundaries. Add an explicit `hive.parquet.time-zone` property for scanner-v2 Parquet INT96 reads. By default scanner v2 preserves raw INT96 wall-clock fields; when configured, it interprets them with the requested unambiguous IANA timezone or valid UTC offset. Reject ambiguous short aliases such as `CST`, share timezone parsing across HMS catalogs and file TVFs, and propagate the setting through generic external-table and TVF interfaces for Hive and Hudi while leaving Iceberg semantics unchanged. Change Parquet export to write INT64 logical timestamps by default and require `enable_int96_timestamps` to be exactly `true` or `false`. Update export regressions to exercise the new default directly while retaining explicit INT96 only for legacy Hive interoperability coverage. Apply half-up nanosecond rounding consistently to ORC rows and statistics, use conservative SARG bounds, and fall back to exact row filtering where negating a widened timestamp envelope would be unsafe. The legacy v1 reader remains unchanged by design. ### Release note Parquet export now writes INT64 logical timestamps by default. Set `enable_int96_timestamps=true` to request INT96. The `hive.parquet.time-zone` property accepts unambiguous IANA timezone IDs or valid UTC offsets; ambiguous short aliases such as `CST` are rejected. ### Check List (For Author) - Test: - Build: `./build.sh --fe` passed on the designated remote host. - Checkstyle: `cd fe && mvn checkstyle:check -pl fe-core` passed on the designated remote host with 0 violations. - Unit Test: 39 targeted FE tests covering scan propagation, HMS/TVF timezone validation, Parquet properties, and export commands passed on the designated remote host. - Unit Test: targeted Parquet and ORC BE unit tests passed on the designated remote host. - Regression test: `test_outfile_parquet` passed on an isolated scanner-v2 cluster on the designated remote host and verified default Parquet export/stream-load round-trip results. - Regression test: `test_hive_read_parquet` and `test_hive_read_parquet_complex_type` passed on the designated remote host. - Regression test: `test_hdfs_parquet_group0` passed completely on an isolated scanner-v2 cluster on the designated remote host. - Regression test: `paimon_timestamp_types` passed completely for JNI and native readers on the isolated cluster on the designated remote host. - Regression test: TeamCity builds 994160 and 994162 produced matching millisecond-precision real results for the updated ARRAY, MAP, and STRUCT expectations. - Regression test: the three S3 outfile suites were attempted on the designated remote host but were blocked before the changed assertions because the configured OSS credential returned `InvalidAccessKeyId`. - Behavior changed: Yes. Scanner v2 preserves raw INT96 wall-clock values by default, Parquet export defaults to INT64 timestamps, timezone aliases are rejected, and ORC timestamp rounding and pruning are consistent and conservative. - Does this need documentation: Yes. apache/doris-website#3982
Gabriel39
force-pushed
the
agent/document-int96-timezone-behavior
branch
from
July 15, 2026 09:29
66d9781 to
1cc4728
Compare
Gabriel39
added a commit
to Gabriel39/incubator-doris
that referenced
this pull request
Jul 15, 2026
### What problem does this PR solve? Issue Number: None Related PR: apache#65446 Problem Summary: Timestamp decoding had two correctness problems in scanner v2. Parquet INT96 does not carry a timezone annotation, so applying the Doris SQL session timezone shifted raw wall-clock fields written by Trino/UTC-style writers. ORC nanoseconds were truncated inconsistently across row decoding, statistics, and SARG predicates, which could also produce unsafe pruning at millisecond statistic boundaries. Add an explicit `hive.parquet.time-zone` property for scanner-v2 Parquet INT96 reads. By default scanner v2 preserves raw INT96 wall-clock fields; when configured, it interprets them with the requested unambiguous IANA timezone or valid UTC offset. Reject ambiguous short aliases such as `CST`, share timezone parsing across HMS catalogs and file TVFs, and propagate the setting through generic external-table and TVF interfaces for Hive and Hudi while leaving Iceberg semantics unchanged. Change Parquet export to write INT64 logical timestamps by default and require `enable_int96_timestamps` to be exactly `true` or `false`. Update export regressions to exercise the new default directly while retaining explicit INT96 only for legacy Hive interoperability coverage. Add an end-to-end regression that exports INT96 in one session timezone and reads it through scanner v2 in another session timezone with `hive.parquet.time-zone` configured. Apply half-up nanosecond rounding consistently to ORC rows and statistics, use conservative SARG bounds, and fall back to exact row filtering where negating a widened timestamp envelope would be unsafe. The legacy v1 reader remains unchanged by design. ### Release note Parquet export now writes INT64 logical timestamps by default. Set `enable_int96_timestamps=true` to request INT96. When scanner v2 reads legacy INT96 files that were normalized by a writer timezone, set `hive.parquet.time-zone` to that timezone. The property accepts unambiguous IANA timezone IDs or valid UTC offsets; ambiguous short aliases such as `CST` are rejected. Existing Hive and Hudi catalogs containing normalized INT96 files should be checked during upgrade. ### Check List (For Author) - Test: - Build: `./build.sh --fe` passed on the designated remote host. - Checkstyle: `cd fe && mvn checkstyle:check -pl fe-core` passed on the designated remote host with 0 violations. - Unit Test: 39 targeted FE tests covering scan propagation, HMS/TVF timezone validation, Parquet properties, and export commands passed on the designated remote host. - Unit Test: targeted Parquet and ORC BE unit tests passed on the designated remote host. - Regression test: `test_outfile_parquet` passed on an isolated scanner-v2 cluster on the designated remote host and verified default Parquet export/stream-load round-trip results. - Regression test: `test_hive_read_parquet` and `test_hive_read_parquet_complex_type` passed on the designated remote host. - Regression test: `test_doris_int96_round_trip` passed in generated-output and comparison modes on the designated remote host, verifying that the configured compatibility timezone overrides a different read session timezone. - Regression test: `test_hdfs_parquet_group0` passed completely on an isolated scanner-v2 cluster on the designated remote host. - Regression test: `paimon_timestamp_types` passed completely for JNI and native readers on the isolated cluster on the designated remote host. - Regression test: TeamCity builds 994160 and 994162 produced matching millisecond-precision real results for the updated ARRAY, MAP, and STRUCT expectations. - Regression test: the three S3 outfile suites were attempted on the designated remote host but were blocked before the changed assertions because the configured OSS credential returned `InvalidAccessKeyId`. - Behavior changed: Yes. Scanner v2 preserves raw INT96 wall-clock values by default, Parquet export defaults to INT64 timestamps, timezone aliases are rejected, and ORC timestamp rounding and pruning are consistent and conservative. - Does this need documentation: Yes. apache/doris-website#3982
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What problem does this PR solve?
Related Doris PR: apache/doris#65446
The Doris change updates timestamp handling in FileScannerV2 and Parquet export. The user-visible compatibility rules and migration options must be documented so users can distinguish raw Parquet
INT96wall-clock values from timestamps normalized by legacy writers.What is changed?
INT96wall-clock fields by default, while ParquetINT64logical timestamps retain their standard semantics.hive.parquet.time-zone, including validation, examples,TIMESTAMPTZhandling, and its Hive/Hudi scope; Iceberg is intentionally unaffected.INT96files were normalized by a known writer time zone.enable_int96_timestampstofalse, producingINT64logical timestamps. Users needing Hive 2/3 compatibility can explicitly set it totrue.INT96, configurehive.parquet.time-zonewith the export session time zone when FileScannerV2 reads it back.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.