Docs for setting environment level tick rate by ohbadiah · Pull Request #35412 · MaterializeInc/materialize

ohbadiah · 2026-03-11T01:49:33Z

In #35027 and #35046 we made it possible to set a default tick rate at the environment level. It's not really documented yet. This is an effort to supply the missing documentation.

github-actions · 2026-03-11T01:49:41Z

Thanks for opening this PR! Here are a few tips to help make the review process smooth for everyone.

PR title guidelines

Use imperative mood: "Fix X" not "Fixed X" or "Fixes X"
Be specific: "Fix panic in catalog sync when controller restarts" not "Fix bug" or "Update catalog code"
Prefix with area if helpful: compute: , storage: , adapter: , sql:

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).

ohbadiah · 2026-03-11T02:24:48Z

 `client_encoding`                           | `UTF8`                    | The client's character set encoding. The only supported value is `UTF-8`.                                                                                              | Yes
 `client_min_messages`                       | `notice`                  | The message levels that are sent to the client. <br/><br/> Accepts values: `debug5`, `debug4`, `debug3`, `debug2`, `debug1`, `log`, `notice`, `warning`, `error`. Each level includes all the levels that follow it. | Yes
 `datestyle`                                 | `ISO, MDY`                | The display format for date and time values. The only supported value is `ISO, MDY`.                                                                                   | Yes
+`default_timestamp_interval`               | `1s`                      | The default timestamping interval for sources and tables. Only applies as a default for newly-created sources — existing sources are not affected when this value changes. Sources created with an explicit `TIMESTAMP INTERVAL` option use that value instead. To change the interval on an existing source, use [`ALTER SOURCE ... SET`](/sql/alter-source/). | [Contact support]


preview link: https://preview.materialize.com/materialize/35412/sql/alter-system-set/#other-configuration-parameters

kay-kim

Thanks for catching this! Left some comments

kay-kim · 2026-03-11T12:19:05Z

 `client_encoding`                           | `UTF8`                    | The client's character set encoding. The only supported value is `UTF-8`.                                                                                              | Yes
 `client_min_messages`                       | `notice`                  | The message levels that are sent to the client. <br/><br/> Accepts values: `debug5`, `debug4`, `debug3`, `debug2`, `debug1`, `log`, `notice`, `warning`, `error`. Each level includes all the levels that follow it. | Yes
 `datestyle`                                 | `ISO, MDY`                | The display format for date and time values. The only supported value is `ISO, MDY`.                                                                                   | Yes
+`default_timestamp_interval`               | `1s`                      | The default timestamping interval for sources and tables. Only applies as a default for newly-created sources — existing sources are not affected when this value changes. Sources created with an explicit `TIMESTAMP INTERVAL` option use that value instead. To change the interval on an existing source, use [`ALTER SOURCE ... SET`](/sql/alter-source/). | [Contact support]


I wonder if we can combine the 3 sentences like (spitballing -- and I might be making stuff up about the subsources/tables😄 ):

The timestamp interval set during source creation and used for the source and its subsources/tables if `TIMESTAMP INTERVAL` is not specified in the `CREATE SOURCE` statement. Changes to this value affect only newly created sources; existing sources continue using the interval set at creation time. To change the interval for an existing source, use [`ALTER SOURCE ... SET`](/sql/alter-source/).

kay-kim · 2026-03-11T12:25:31Z

+
+You can set an environment-wide default timestamp interval, and override it
+on individual sources. See [`ALTER SYSTEM SET`](/sql/alter-system-set/) for
+the environment default, and [`CREATE SOURCE`](/sql/create-source/) and


Heh ... so, we don't mention TIMESTAMP INTERVAL in either CREATE SOURCE and ALTER SOURCE ... Could we add as well?

Petros had already documented ALTER SOURCE. Good catch on CREATE SOURCE! I added to the examples for each source.

kay-kim · 2026-03-11T12:27:06Z

+## Timestamp interval
+
+The timestamp interval controls how frequently Materialize timestamps new data
+from a source. A shorter interval means fresher data but consumes more


Should we mention its effect on the external system?

Added a note:

Changing the timestamp interval does not significantly affect load on the
upstream system.

maheshwarip · 2026-03-11T15:10:31Z

+### Setting the timestamp interval

 ```mzsql
 ALTER SOURCE kafka_src SET (TIMESTAMP INTERVAL = '500ms');


Same comment as above regarding cloud vs. self-managed

This one is alter source, not alter system set, right?

kay-kim

Thanks for this. Left some questions.

kay-kim · 2026-03-13T17:44:22Z

 `client_encoding`                           | `UTF8`                    | The client's character set encoding. The only supported value is `UTF-8`.                                                                                              | Yes
 `client_min_messages`                       | `notice`                  | The message levels that are sent to the client. <br/><br/> Accepts values: `debug5`, `debug4`, `debug3`, `debug2`, `debug1`, `log`, `notice`, `warning`, `error`. Each level includes all the levels that follow it. | Yes
 `datestyle`                                 | `ISO, MDY`                | The display format for date and time values. The only supported value is `ISO, MDY`.                                                                                   | Yes
+`default_timestamp_interval`               | `1s`                      | How frequently newly-created sources [timestamp incoming data](/concepts/sources/#timestamp-interval), unless a per-source override is set. | [Contact support]


If you add an anchor here, you can link from the source page

Suggested change

`default_timestamp_interval` | `1s` | How frequently newly-created sources [timestamp incoming data](/concepts/sources/#timestamp-interval), unless a per-source override is set. | [Contact support]

`default_timestamp_interval` | `1s` | <a name="default_timestamp_interval"></a>How frequently newly-created sources [timestamp incoming data](/concepts/sources/#timestamp-interval), unless a per-source override is set. | [Contact support]

kay-kim · 2026-03-13T17:45:31Z

+Changing the timestamp interval does not significantly affect load on the
+upstream system.
+
+The environment default is controlled by the `default_timestamp_interval`


If you add the anchor (see below in the parameter table), you can go

[`default_timestamp_interval`](/sql/set/#default_timestamp_interval)

Also, we no longer mention that this value is set for a source at the time of its creation (and the system parameter doesn't affect afterwards). Is that on purpose?

kay-kim · 2026-03-13T18:06:30Z

    ]
    [EXPOSE PROGRESS AS <progress_subsource_name>]
-    [WITH (RETAIN HISTORY FOR <retention_period>)]
+    [WITH (


Not ideal ... but could it be more (for now ):

[WITH ( RETAIN HISTORY FOR <retention_period> | TIMESTAMP INTERVAL <interval> [,... ] )]

I don't want people to think if you use WITH that you need to include RETAIN HISTORY FOR if you're only setting timestamp interval.

kay-kim · 2026-03-13T18:09:39Z

+    [WITH (
+      RETAIN HISTORY FOR <retention_period>
+      [, TIMESTAMP INTERVAL <interval>]
+    )]


So ... do we or do we not set this for the new postgres syntax?

https://preview.materialize.com/materialize/35412/sql/create-source/postgres-v2/#syntax ?

The associated create table from source has some with options ... but per description, it seems like one would set it at the source.

kay-kim · 2026-03-13T18:10:08Z

+    [WITH (
+      RETAIN HISTORY FOR <retention_period>
+      [, TIMESTAMP INTERVAL <interval>]
+    )]


ditto w.r.t. the question about the new create source syntax for sql server.

…val)

ohbadiah · 2026-04-30T19:32:16Z

Summary from looking at this together in person:

We'll remove the bit from the "concepts" page
We'll make sure it shows up on the new create source syntax pages
We'll add the anchoring that Kay suggested

Plus a troubleshooting thing and an anchor that @kay-kim is going to describe for me soon

kay-kim · 2026-04-30T19:53:04Z

@ohbadiah -- let me know if you need further clarifications on these

Summary from looking at this together in person:

We'll remove the bit from the "concepts" page
- Instead add to the Ingest data/troubleshooting page a question like "Why is my data in Materialize not as fresh as expected?" or "Is the timestamp interval affecting my data freshness and resource usage?" or some such. The answer can be the reworked bit from the concepts page (but mentioning default is for new sources ... not existing one) + update default_timestamp_interval to be default_timestamp_interval -- see Docs for setting environment level tick rate #35412 (comment)

We'll make sure it shows up on the new create source syntax pages

We'll add the anchoring that Kay suggested
- For this: you should be able to just hit the commit suggestion Docs for setting environment level tick rate #35412 (comment) --

ohbadiah · 2026-06-02T19:19:13Z

Closing in favor of #36870

ohbadiah requested a review from a team as a code owner March 11, 2026 01:49

ohbadiah marked this pull request as draft March 11, 2026 01:49

ohbadiah commented Mar 11, 2026

View reviewed changes

Comment thread doc/user/content/concepts/sources.md

ohbadiah commented Mar 11, 2026

View reviewed changes

Comment thread doc/user/content/sql/alter-source.md

ohbadiah force-pushed the nickmcavoy/clu-32-document-environment-level-tick-rate branch 2 times, most recently from 725ba59 to a6d3445 Compare March 11, 2026 02:28

ohbadiah marked this pull request as ready for review March 11, 2026 02:29

kay-kim reviewed Mar 11, 2026

View reviewed changes

maheshwarip reviewed Mar 11, 2026

View reviewed changes

Comment thread doc/user/content/concepts/sources.md Outdated

maheshwarip reviewed Mar 11, 2026

View reviewed changes

ohbadiah force-pushed the nickmcavoy/clu-32-document-environment-level-tick-rate branch 2 times, most recently from 802403d to a8e9200 Compare March 13, 2026 16:06

ohbadiah requested review from kay-kim and maheshwarip March 13, 2026 16:10

kay-kim reviewed Mar 13, 2026

View reviewed changes

Docs for setting environment level tick rate (default_timestamp_inter…

b27a29a

…val)

ohbadiah force-pushed the nickmcavoy/clu-32-document-environment-level-tick-rate branch from a8e9200 to b27a29a Compare April 30, 2026 19:07

ohbadiah closed this Jun 2, 2026

	`default_timestamp_interval` \| `1s` \| How frequently newly-created sources [timestamp incoming data](/concepts/sources/#timestamp-interval), unless a per-source override is set. \| [Contact support]
	`default_timestamp_interval` \| `1s` \| <a name="default_timestamp_interval"></a>How frequently newly-created sources [timestamp incoming data](/concepts/sources/#timestamp-interval), unless a per-source override is set. \| [Contact support]

Conversation

ohbadiah commented Mar 11, 2026

Uh oh!

github-actions Bot commented Mar 11, 2026

PR title guidelines

Pre-merge checklist

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kay-kim left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kay-kim left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ohbadiah commented Apr 30, 2026

Uh oh!

kay-kim commented Apr 30, 2026

Uh oh!

ohbadiah commented Jun 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants