feat(timezone): support session-level timezone by Tony2h · Pull Request #35323 · taosdata/TDengine

Tony2h · 2026-05-12T10:14:45Z

Description

Issue(s)

Close/close/Fix/fix/Resolve/resolve: Issue Link

Checklist

Please check the items in the checklist if applicable.

Is the user manual updated?
Are the test cases passed and automated?
Is there no significant decrease in test coverage?

Copilot

Pull request overview

This PR adds session-level timezone (and related firstDayOfWeek) support across the client stack: new local SQL commands (SET TIMEZONE, SET FIRST_DAY_OF_WEEK), propagation into planner/executor for time windows, and CLI/shell display paths that format timestamps using the connection timezone. It also introduces timezone validation utilities, new error codes, and substantial test + documentation updates to cover the new behavior.

Changes:

Implement local SET TIMEZONE / SET FIRST_DAY_OF_WEEK and snapshot per-connection timezone/firstDayOfWeek into parse/plan context.
Propagate timezone + firstDayOfWeek through planner → physical nodes → serialization → executor interval/window logic.
Add/adjust tests and documentation for timezone configuration, scalar functions, and interval windows.

Reviewed changes

Copilot reviewed 72 out of 72 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tools/shell/src/shellEngine.c	Pass connection timezone into timestamp formatting/printing/dumping paths.
tools/shell/inc/shellInt.h	Update shell function declarations to include timezone parameter.
timezone-test-spec.md	Add/update a detailed timezone-related test specification document.
timezone-query-DS.md	Add a detailed design document for timezone/query changes.
test/cases/13-TimeSeriesExt/03-TimeWindow/test_tz_interval.py	Add INTERVAL timezone/firstDayOfWeek integration tests.
test/cases/11-Functions/03-Selection/test_select_all.py	Update expected error message for timetruncate invalid unit cases.
test/cases/11-Functions/02-Aggregate/test_agg_all.py	Update expected error message for timetruncate invalid unit cases.
test/cases/11-Functions/01-Scalar/test_tz_config_display.py	Add extensive timezone/firstDayOfWeek config + display + query behavior tests.
test/cases/11-Functions/01-Scalar/test_scalar_all.py	Update expected error message for timetruncate invalid unit cases.
source/util/src/terror.c	Add new error codes/messages for invalid timezone and invalid firstDayOfWeek.
source/libs/scheduler/src/schRemote.c	Carry firstDayOfWeek into subquery messages.
source/libs/scheduler/src/schJob.c	Store/copy firstDayOfWeek into scheduler job structures.
source/libs/scheduler/inc/schInt.h	Add firstDayOfWeek to scheduler job struct.
source/libs/scalar/src/sclfunc.c	Extend scalar funcs (to_iso8601/to_char/timetruncate/weekofyear) with timezone + fdow logic.
source/libs/scalar/src/scalar.c	Pass firstDayOfWeek from plan node into scalar param env.
source/libs/planner/src/planPhysiCreater.c	Copy timezone + firstDayOfWeek into physical scan/interval nodes.
source/libs/planner/src/planOptimizer.c	Propagate timezone + firstDayOfWeek during scan-path optimization.
source/libs/planner/src/planLogicCreater.c	Set window logic node timezone + firstDayOfWeek from plan context.
source/libs/parser/test/parInitialDTest.cpp	Add parser coverage for SET FIRST_DAY_OF_WEEK (including invalid values).
source/libs/parser/src/parTranslater.c	Rewrite TIMEZONE() as a literal; mark SET TIMEZONE/FDOW as local exec.
source/libs/parser/src/parTokenizer.c	Add FIRST_DAY_OF_WEEK keyword token.
source/libs/parser/src/parAuthenticator.c	Allow SET TIMEZONE/FDOW statements without extra auth.
source/libs/parser/src/parAstParser.c	Skip meta-key collection for local-only SET statements.
source/libs/parser/src/parAstCreater.c	Create AST nodes for SET TIMEZONE and SET FIRST_DAY_OF_WEEK.
source/libs/parser/inc/sql.y	Add grammar rules for SET TIMEZONE and SET FIRST_DAY_OF_WEEK.
source/libs/parser/inc/parAst.h	Add AST creator declarations for new SET statements.
source/libs/nodes/src/nodesUtilFuncs.c	Add timezone-name decoding helper; free tz handles owned by nodes.
source/libs/nodes/src/nodesMsgFuncs.c	Serialize/deserialize firstDayOfWeek + timezoneName for scan/interval physical nodes.
source/libs/nodes/src/nodesCodeFuncs.c	JSON encode/decode firstDayOfWeek + timezoneName for plan nodes; add node name strings.
source/libs/nodes/src/nodesCloneFuncs.c	Ensure clone copies firstDayOfWeek and reconstructs timezone from timezoneName.
source/libs/nodes/inc/nodesUtil.h	Export nodesDecodeTimezoneName().
source/libs/function/src/builtins.c	Extend timetruncate unit validation; inject timezone name + fdow into args; extend to_char signature.
source/libs/function/inc/functionMgtInt.h	Add new param attribute for time unit or calendar unit validation.
source/libs/executor/src/timewindowoperator.c	Pass firstDayOfWeek + timezone into interval operator initialization.
source/libs/executor/src/executil.c	Include firstDayOfWeek + timezone in extracted interval info.
source/common/test/ttimeNaturalUnitsTest.cpp	Add/strengthen unit tests for natural-unit boundary alignment.
source/common/src/ttime.c	Add timezone validation helper; implement fdow-aware week alignment in interval truncation.
source/common/src/tglobal.c	Add client dynamic config firstDayOfWeek and wire it into client cfg setup.
source/common/src/msg/tmsg.c	Serialize/deserialize firstDayOfWeek in SSubQueryMsg.
source/client/wrapper/src/wrapperVariable.c	Add wrapper function pointer for taos_get_conn_tz.
source/client/wrapper/src/wrapperFunc.c	Expose taos_get_conn_tz() in wrapper API surface.
source/client/wrapper/src/wrapperDriver.c	Load taos_get_conn_tz symbol from native driver.
source/client/wrapper/inc/wrapper.h	Declare fp_taos_get_conn_tz.
source/client/test/clientTests.cpp	Add async local SET command tests to verify session option updates.
source/client/src/clientMain.c	Implement session timezone snapshot/init; validate timezone strings; add taos_get_conn_tz().
source/client/src/clientImpl.c	Execute SET TIMEZONE/FDOW locally; pass fdow/timezoneName into planning/scheduling.
source/client/src/clientEnv.c	Snapshot firstDayOfWeek and session timezone at connection creation.
source/client/inc/clientInt.h	Add timezoneName + firstDayOfWeek to connection option info; declare tscInitSessionTimezone().
p4-review.md	Add an internal review report document (P4).
include/util/taoserror.h	Define new error codes for invalid timezone and invalid firstDayOfWeek.
include/libs/scheduler/scheduler.h	Extend scheduler request to include firstDayOfWeek.
include/libs/planner/planner.h	Add timezoneName + firstDayOfWeek to plan context.
include/libs/parser/parser.h	Add firstDayOfWeek to parse context.
include/libs/nodes/querynodes.h	Add firstDayOfWeek to function nodes.
include/libs/nodes/plannodes.h	Add timezone/timezoneName/ownsTimezone/firstDayOfWeek to logic/physical plan nodes.
include/libs/nodes/cmdnodes.h	Add AST structs for SET TIMEZONE and SET FIRST_DAY_OF_WEEK.
include/libs/function/function.h	Add firstDayOfWeek to scalar param env struct.
include/common/ttime.h	Declare taosValidateTimezone().
include/common/tmsg.h	Add new node types + firstDayOfWeek to messages.
include/common/tglobal.h	Export tsFirstDayOfWeek.
include/client/taos.h	Export taos_get_conn_tz() in public client API.
docs/zh/14-reference/09-error-code.md	Document new error codes for timezone/firstDayOfWeek.
docs/zh/14-reference/03-taos-sql/70-node.md	Document SET TIMEZONE / SET FIRST_DAY_OF_WEEK syntax and semantics.
docs/zh/14-reference/03-taos-sql/22-function.md	Update function docs for TO_CHAR/TO_ISO8601/TIMETRUNCATE/TIMEZONE changes.
docs/zh/14-reference/03-taos-sql/20-select.md	Update SELECT system function syntax to mention TIMEZONE([0
docs/en/14-reference/09-error-code.md	Document new error codes for timezone/firstDayOfWeek.
docs/en/14-reference/03-taos-sql/70-node.md	Document SET TIMEZONE / SET FIRST_DAY_OF_WEEK syntax and semantics.
docs/en/14-reference/03-taos-sql/22-function.md	Update function docs for TO_CHAR/TO_ISO8601/TIMETRUNCATE/TIMEZONE changes.
docs/en/14-reference/03-taos-sql/20-select.md	Update SELECT system function syntax to mention TIMEZONE([0

Comments suppressed due to low confidence (1)

tools/shell/src/shellEngine.c:355

shellFormatTimestamp() writes into buf using multiple sprintf() calls (raw-time branch and fractional append) without respecting bufSize/remaining capacity. The current callers use reasonably sized buffers, but the function signature implies it should be safe for any bufSize. Prefer snprintf() (and pass bufSize to strftime instead of the hard-coded 35) to avoid potential overflows and truncation bugs if future call sites pass smaller buffers.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

gemini-code-assist

Code Review

This pull request implements a comprehensive timezone and query alignment framework, introducing connection-level configurations for timezones and the first day of the week. It extends scalar functions such as TO_ISO8601, TO_CHAR, and TIMETRUNCATE to support IANA timezone names and natural calendar units (month, quarter, year), ensuring DST-aware calculations throughout the query pipeline. Feedback highlighted a critical logic error in the TIMETRUNCATE function where the absence of a timezone during calendar unit truncation leads to incorrect results instead of a proper error response.

Copilot

Pull request overview

Copilot reviewed 74 out of 74 changed files in this pull request and generated 6 comments.

Comments suppressed due to low confidence (1)

source/common/src/ttime.c:16

Including <bits/stdint-intn.h> is a glibc-internal header and will not compile on non-glibc environments (musl, macOS, etc.). This file already uses standard integer types, so please replace this with a portable standard header (e.g. <stdint.h>) or remove it if unnecessary.

Copilot

Pull request overview

Copilot reviewed 72 out of 72 changed files in this pull request and generated 1 comment.

Copilot

Pull request overview

Copilot reviewed 77 out of 77 changed files in this pull request and generated 4 comments.

Copilot

Pull request overview

Copilot reviewed 80 out of 80 changed files in this pull request and generated 7 comments.

+    # @pytest.mark.xfail(
+    #     reason=SESSION_TZ_BOUNDARY_XFAIL,
+    #     strict=True,
+    # )


Copilot

Pull request overview

Copilot reviewed 88 out of 88 changed files in this pull request and generated 9 comments.

Copilot

Pull request overview

Copilot reviewed 93 out of 93 changed files in this pull request and generated 7 comments.

… strings

…unction tests

… timezone handling

…and POSIX-style formats Co-authored-by: Copilot <copilot@github.com>

…statement

Copilot

Pull request overview

Copilot reviewed 95 out of 96 changed files in this pull request and generated 3 comments.

…ion and code

Copilot

Pull request overview

Copilot reviewed 97 out of 98 changed files in this pull request and generated no new comments.

Copilot AI review requested due to automatic review settings May 12, 2026 10:14

Tony2h requested review from a team, dapan1121, guanshengliang and zitsen as code owners May 12, 2026 10:14

taosdata-bot Bot added the team engine label May 12, 2026

Copilot started reviewing on behalf of Tony2h May 12, 2026 10:15 View session

Copilot AI reviewed May 12, 2026

View reviewed changes

gemini-code-assist Bot reviewed May 12, 2026

View reviewed changes

Comment thread source/libs/scalar/src/sclfunc.c

Copilot AI review requested due to automatic review settings May 13, 2026 02:00

Copilot started reviewing on behalf of Tony2h May 13, 2026 02:01 View session

Copilot AI reviewed May 13, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings May 13, 2026 07:20

Copilot started reviewing on behalf of Tony2h May 13, 2026 07:22 View session

Copilot AI reviewed May 13, 2026

View reviewed changes

Comment thread source/util/src/terror.c

Copilot AI review requested due to automatic review settings May 13, 2026 10:54

Copilot started reviewing on behalf of Tony2h May 13, 2026 10:55 View session

Copilot AI reviewed May 13, 2026

View reviewed changes

Comment thread source/libs/scalar/src/sclfunc.c

Comment thread source/util/src/terror.c

Comment thread source/client/src/clientMain.c Outdated

Comment thread test/cases/13-TimeSeriesExt/03-TimeWindow/test_tz_interval.py

Tony2h force-pushed the feat/tz branch from 398021b to 48ff976 Compare May 14, 2026 07:30

Copilot AI review requested due to automatic review settings May 14, 2026 09:20

Copilot started reviewing on behalf of Tony2h May 14, 2026 09:21 View session

Copilot AI reviewed May 14, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings May 15, 2026 08:01

Copilot started reviewing on behalf of Tony2h May 15, 2026 08:01 View session

Copilot AI reviewed May 15, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings May 18, 2026 02:09

Copilot started reviewing on behalf of tomchon May 18, 2026 02:10 View session

Copilot AI reviewed May 18, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings May 18, 2026 09:14

Copilot started reviewing on behalf of Tony2h May 18, 2026 09:15 View session

Tony2h and others added 20 commits May 18, 2026 17:41

fix: ai review

4531aa6

fix: quarter start cal bug

3f3c1e8

fix: enhance parameter validation and error handling in join operators

a0a8384

fix: enhance timezone handling in toISO8601Function for user-provided…

e5edd8b

… strings

fix: update error messages for invalid timezone format in toISO8601 f…

1e71acc

…unction tests

fix: correct interval_diff_tz.csv interval window result

1b51ff8

refactor: shell get tz info from query results

04f3a17

fix: timetruncate error in merge join

a6838da

feat: add timezone support for timestamp formatting in explain context

78ae1b1

chore: refine auto completion and error format

44ca5f1

feat: support set fdow by os config

fa4059f

docs: refine

8cdd8cf

feat: add UTC offset extraction and improve time truncation logic for…

ceb676c

… timezone handling

fix: enhance timezone handling with support for fixed-offset strings …

a75c351

…and POSIX-style formats Co-authored-by: Copilot <copilot@github.com>

feat: add error message formatting for invalid firstDayOfWeek in SET …

774305a

…statement

feat: implement first_day_of_week function and related SQL support

7fede84

tests: add windows skip mark on new tests

07b3437

fix ci failed cases

de6ea28

fix ai review comments

a0a2bf1

fix: remove outdated documentation for FULL JOIN timetruncate bug

c3a2c36

Copilot AI review requested due to automatic review settings May 18, 2026 09:41

Tony2h force-pushed the feat/tz branch from 824e7f8 to c3a2c36 Compare May 18, 2026 09:41

Copilot started reviewing on behalf of Tony2h May 18, 2026 09:42 View session

Copilot AI reviewed May 18, 2026

View reviewed changes

Comment thread source/common/src/ttime.c

Comment thread test/cases/09-DataQuerying/01-Select/test_query_quarter.py

Comment thread source/os/test/osLocaleTests.cpp

Tony2h added 2 commits May 19, 2026 09:55

fix: join on timetruncate error

21e947b

Enhance timezone management and related functionalities in documentat…

b4c2b8b

…ion and code

Copilot AI review requested due to automatic review settings May 19, 2026 03:48

Copilot started reviewing on behalf of Tony2h May 19, 2026 03:48 View session

Copilot AI reviewed May 19, 2026

View reviewed changes

fix: improve timezone validation and update EXPLAIN documentation

64d6c2d

Conversation

Tony2h commented May 12, 2026

Description

Issue(s)

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!