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

doc/user/content/concepts/sources.md

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

doc/user/content/headless/configuration-parameters.md

 `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

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

kay-kim

Thanks for catching this! Left some comments

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

doc/user/content/headless/configuration-parameters.md

 `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

doc/user/content/concepts/sources.md

+
+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

doc/user/content/concepts/sources.md

+## 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:09:39Z

doc/user/content/concepts/sources.md

+resources; a longer interval reduces load at the cost of data freshness.
+
+You can set an environment-wide default timestamp interval, and override it
+on individual sources. See [`ALTER SYSTEM SET`](/sql/alter-system-set/) for


You can only use ALTER SYSTEM SET on self-managed right? For Materialize Cloud, we should direct customers to contact us

Fixed - the current version just gives the name of the param, without reference to how it is set.

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

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

+### 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?

…val)

kay-kim

Thanks for this. Left some questions.

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

doc/user/content/headless/configuration-parameters.md

 `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

doc/user/content/concepts/sources.md

+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

doc/user/data/examples/create_source_kafka.yml

    ]
    [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

doc/user/data/examples/create_source_postgres_legacy.yml

+    [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

doc/user/data/examples/create_source_sql_server_legacy.yml

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


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

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

doc/user/content/concepts/sources.md Show resolved Hide resolved

ohbadiah commented Mar 11, 2026

View reviewed changes

doc/user/content/sql/alter-source.md Show resolved Hide resolved

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

ohbadiah force-pushed the nickmcavoy/clu-32-document-environment-level-tick-rate branch from a6d3445 to 802403d Compare March 13, 2026 15:53

Docs for setting environment level tick rate (default_timestamp_inter…

a8e9200

…val)

ohbadiah force-pushed the nickmcavoy/clu-32-document-environment-level-tick-rate branch 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

	`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!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants