Skip to content

unify timestamping interval into a single system parameter#35027

Merged
petrosagg merged 8 commits intoMaterializeInc:mainfrom
petrosagg:timestamp-interval-system-var
Feb 25, 2026
Merged

unify timestamping interval into a single system parameter#35027
petrosagg merged 8 commits intoMaterializeInc:mainfrom
petrosagg:timestamp-interval-system-var

Conversation

@petrosagg
Copy link
Contributor

@petrosagg petrosagg commented Feb 16, 2026

This PR replaces five dyncfg parameters (pg_offset_known_interval, mysql_offset_known_interval, kafka_default_metadata_fetch_interval, sql_server_cdc_poll_interval, sql_server_offset_known_interval) and a hardcoded 1s constant with a single default_timestamp_interval system parameter.

This parameter controls the timestamping interval of tables and the default timestamping interval of sources. For sources, users can specify a custom timestamping interval as part of the CREATE SOURCE statement using the TIMESTAMP INTERVAL WITH option. When this parameter is not specified the source is created with the current value of the default_timestamp_interval system parameter. Changing the global default_timestamp_interval parameter won't affect already created sources. To change the timestamp interval of an already created source an ALTER SOURCE statement is needed.

The value of the TIMESTAMP INTERVAL WITH option is validated against the min_timestamp_interval and max_timestamp_interval system parameters.

part of CLU-25

@github-actions
Copy link

Pre-merge checklist

  • The PR title is descriptive and will make sense in the git log.
  • This PR has adequate test coverage / QA involvement has been duly considered. (trigger-ci for additional test/nightly runs)
  • If this PR includes major user-facing behavior changes, I have pinged the relevant PM to schedule a changelog post.
  • This PR has an associated up-to-date design doc, is a design doc (template), or is sufficiently small to not require a design.
  • If this PR evolves an existing $T ⇔ Proto$T mapping (possibly in a backwards-incompatible way), then it is tagged with a T-proto label.
  • If this PR will require changes to cloud orchestration or tests, there is a companion cloud PR to account for those changes that is tagged with the release-blocker label (example).

@petrosagg petrosagg force-pushed the timestamp-interval-system-var branch 2 times, most recently from 2414c0f to 2ca8b31 Compare February 16, 2026 16:55
@petrosagg petrosagg marked this pull request as ready for review February 16, 2026 17:07
@petrosagg petrosagg requested review from a team as code owners February 16, 2026 17:07
@petrosagg petrosagg requested a review from ohbadiah February 16, 2026 17:07
Copy link
Contributor

@def- def- left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nightly triggered: https://buildkite.com/materialize/nightly/builds/15175

I also want to see what happens if you lower it to 10 ms in all of CI, maybe something falls over in an interesting way: https://buildkite.com/materialize/test/builds/115951

Comment on lines +6996 to +6997
let min = scx.catalog.system_vars().min_timestamp_interval();
let max = scx.catalog.system_vars().max_timestamp_interval();
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What happens if the min/max timestamp interval changes to a value such that duration is not within the bounds anymore? This will not cause the effective interval to be fixed such that it'll be within the interval, right? Maybe you can add an SLT test to show behavior if this happens. (I don't think we specified the behavior, so it might be a good idea to note it somewhere.)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, I didn't test it but the behavior we want is the same one we have for feature flags that allow you to create certain type of objects or use certain parameters, which is that those flags are marked with enable_for_item_parsing so that if you enable the flag, create the restricted object, then disable the flag the catalog can still be loaded.

I'll add a test for that

Copy link
Member

@antiguru antiguru left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great in general, just one Q around adjusting the min/max intervals and what happens if custom durations fall outside the interval.

This PR replaces five dyncfg parameters (`pg_offset_known_interval`,
`mysql_offset_known_interval`, `kafka_default_metadata_fetch_interval`,
`sql_server_cdc_poll_interval`, `sql_server_offset_known_interval`) and
a hardcoded 1s constant with a single `timestamp_interval` system
parameter.

This parameter controls the timestamping interval of tables and the
default timestamping interval of sources. For sources, users can specify
a custom timestamping interval as part of the `CREATE SOURCE` statement
using the `TIMESTAMP INTERVAL` WITH option. When this parameter is not
specified the source is created with the current value of the
`timestamp_interval` system parameter. Changing the global
`timestamp_interval` parameter won't affect already created sources. To
change the timestamp interval of an already created source an `ALTER
SOURCE` statement is needed.

The value of `timestamp_interval` is validated against
`min_timestamp_interval` and `max_timestamp_interval`.

Signed-off-by: Petros Angelatos <petrosagg@gmail.com>
@petrosagg petrosagg force-pushed the timestamp-interval-system-var branch from d5d08b1 to 06770b8 Compare February 25, 2026 15:35
@petrosagg petrosagg enabled auto-merge (squash) February 25, 2026 16:57
Copy link
Contributor

@kay-kim kay-kim left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the docs changes lgtm. Left a question w.r.t. checking after someone issues the command.


### Changing the timestamp interval

To set a custom timestamp interval for a source:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Q: Is there a way to show the current timestamp interval for a source after someone sets this to verify?

@petrosagg petrosagg merged commit f2656c0 into MaterializeInc:main Feb 25, 2026
141 checks passed
@petrosagg petrosagg deleted the timestamp-interval-system-var branch February 25, 2026 17:13
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.

4 participants