Hydration is the reconstruction of an object’s in-memory state by reading
from Materialize’s storage layer and existing indexes; hydration does not
read from the upstream system.
When hydration occurs
Depending on the object, hydration (or rehydration) occurs after:
An object is created, triggering its hydration.
This includes dropping and recreating objects to force re-planning. For
example, after dropping an index, you can drop and recreate its
dependent objects to force them to re-plan. The recreated objects then
hydrate like any newly created object.
A cluster replica restarts, such as during Materialize Cloud’s
routine maintenance or after an out-of-memory event. Hydration can be
memory-intensive and can itself trigger the out-of-memory event. The
replica then restarts and rehydrates again, potentially creating a
restart-and-rehydrate loop if the replica is undersized.
A cluster resize. A cluster resize provisions new replicas at the
target size and hydrates them before retiring the old ones. The cluster
keeps serving throughout.
Adding a replica to a cluster, which hydrates the new replica only.
Existing replicas are unaffected and keep serving.
Hydration is per cluster replica: when a hydration trigger occurs, the
objects on the affected replicas hydrate. When a replica restarts, every
object on it re-hydrates. A resize or an added replica hydrates only the
new replicas.
The objects on the affected replicas hydrate as described in the following
table.
Object
Hydration behavior
Materialized views
When: Hydrates on creation and on every replica (re)start or cluster resize.
What: Rebuilds the dataflow’s operator state: the arrangements that joins, aggregations, and similar operators keep to update results incrementally. Note: A materialized view’s result lives in durable storage, so it rebuilds only this maintenance state, not the result.
Memory Use: Scales with the view’s definition, which it holds at steady state, plus a transient output buffer up to twice the output size: the current output plus a read-back of the previously persisted output. On first creation, since there is no previous output, the buffer is a single output size.
Indexes
When: Hydrates on creation and on every replica (re)start or cluster resize.
What: Rebuilds the arranged (indexed) data it keeps in memory to serve reads, plus any operator arrangements its dataflow maintains (for joins, aggregations, and similar).
Memory Use: Its memory is proportional to the indexed data plus those arrangements, and is held for as long as the index exists.
Kafka upsert sources and associated read-only tables/subsources
When: On replica (re)start or cluster resize. These sources do not hydrate on creation; instead, on creation, their indexes are built as part of snapshotting.
What: Rebuilds the table’s or subsource’s internal upsert index from storage.
Memory Use: The index holds the latest value per key, so its memory scales with the source’s key space. On standard cluster sizes it can spill to disk when the key space exceeds memory.
Append-only Kafka sources and CDC database sources (PostgreSQL, MySQL, SQL Server), and their read-only tables/subsources
When: On replica (re)start or cluster resize, marked hydrated as soon as the dataflow starts.
What: Effectively nothing. These sources keep no internal index to rebuild and resume from their persisted position, so hydration is a no-op.
Memory Use: Negligible, since there is no index to hold.
Webhook sources
Not applicable. A webhook source is not maintained by a dataflow. It receives data pushed over HTTP and writes the data directly to storage, so it does not hydrate.
Sinks
When: If created WITH (SNAPSHOT = true) (the default), hydrates:
On creation, when the sink first emits its input snapshot.
On a replica (re)start, but only if the sink restarted before recording
any progress: it then re-reads the whole input snapshot, and any data
already written to the external system is discarded, but the memory
cost still occurs. An established sink resumes from its recorded
progress without re-reading the snapshot.
What: Loads a full copy of its input snapshot into the arrangement that feeds the sink before it can emit.
Memory Use: Peaks at roughly a full copy of the input snapshot, then decreases as the snapshot is written out. Negligible on a restart of an established sink. At steady state, a sink retains little in memory.
Subscriptions
When: On creation and, while it remains active, on every replica (re)start: the dataflow is re-installed on the (re)started replica and the subscription resumes. A subscription that targets a specific replica instead ends with an error when that replica restarts. A subscription ends with its session and is not reported in mz_hydration_statuses.
What: Rebuilds the dataflow when it starts.
Memory Use: Scales with the dataflow, held while the subscription runs.
Reducing hydration memory
Hydration primarily impacts memory usage, and its speed scales with cluster
size. For strategies to reduce hydration memory, speed hydration up, or avoid
triggering it, see Optimize hydration
requirements.