Skip to main content

risingwave_common/util/
stream_graph_visitor.rs

1// Copyright 2023 RisingWave Labs
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use itertools::Itertools;
16use risingwave_pb::catalog::Table;
17use risingwave_pb::stream_plan::stream_fragment_graph::StreamFragment;
18use risingwave_pb::stream_plan::stream_node::NodeBody;
19use risingwave_pb::stream_plan::{SourceBackfillNode, StreamNode, StreamScanNode, agg_call_state};
20
21#[macro_export]
22macro_rules! dispatch_stream_node_body {
23    ($body:expr, $node_body:ident, $node:ident => $call:expr) => {
24        ::risingwave_pb::__dispatch_stream_node_body!($body, $node_body, $node => $call)
25    };
26}
27
28/// A utility for visiting and mutating the [`NodeBody`] of the [`StreamNode`]s recursively.
29pub fn visit_stream_node_mut(stream_node: &mut StreamNode, mut f: impl FnMut(&mut NodeBody)) {
30    visit_stream_node_cont_mut(stream_node, |stream_node| {
31        f(stream_node.node_body.as_mut().unwrap());
32        true
33    })
34}
35
36/// A utility for to accessing the [`StreamNode`] mutably. The returned bool is used to determine whether the access needs to continue.
37pub fn visit_stream_node_cont_mut<F>(stream_node: &mut StreamNode, mut f: F)
38where
39    F: FnMut(&mut StreamNode) -> bool,
40{
41    fn visit_inner<F>(stream_node: &mut StreamNode, f: &mut F)
42    where
43        F: FnMut(&mut StreamNode) -> bool,
44    {
45        if !f(stream_node) {
46            return;
47        }
48        for input in &mut stream_node.input {
49            visit_inner(input, f);
50        }
51    }
52
53    visit_inner(stream_node, &mut f)
54}
55
56/// A utility for visiting the [`NodeBody`] of the [`StreamNode`]s recursively.
57pub fn visit_stream_node_body(stream_node: &StreamNode, mut f: impl FnMut(&NodeBody)) {
58    visit_stream_node_cont(stream_node, |stream_node| {
59        f(stream_node.node_body.as_ref().unwrap());
60        true
61    })
62}
63
64pub fn visit_stream_node(stream_node: &StreamNode, mut f: impl FnMut(&StreamNode)) {
65    visit_stream_node_cont(stream_node, |stream_node| {
66        f(stream_node);
67        true
68    })
69}
70
71/// A utility for to accessing the [`StreamNode`] immutably. The returned bool is used to determine whether the access needs to continue.
72pub fn visit_stream_node_cont<'a, F>(stream_node: &'a StreamNode, mut f: F)
73where
74    F: FnMut(&'a StreamNode) -> bool,
75{
76    fn visit_inner<'a, F>(stream_node: &'a StreamNode, f: &mut F)
77    where
78        F: FnMut(&'a StreamNode) -> bool,
79    {
80        if !f(stream_node) {
81            return;
82        }
83        for input in &stream_node.input {
84            visit_inner(input, f);
85        }
86    }
87
88    visit_inner(stream_node, &mut f)
89}
90
91/// A utility for visiting and mutating the [`NodeBody`] of the [`StreamNode`]s in a
92/// [`StreamFragment`] recursively.
93pub fn visit_fragment_mut(fragment: &mut StreamFragment, f: impl FnMut(&mut NodeBody)) {
94    visit_stream_node_mut(fragment.node.as_mut().unwrap(), f)
95}
96
97/// A utility for visiting the [`NodeBody`] of the [`StreamNode`]s in a
98/// [`StreamFragment`] recursively.
99pub fn visit_fragment(fragment: &StreamFragment, f: impl FnMut(&NodeBody)) {
100    visit_stream_node_body(fragment.node.as_ref().unwrap(), f)
101}
102
103/// Visit references to the Fetch task table used for job identity, not extra owned tables.
104pub fn visit_iceberg_completion_tables(
105    fragment: &mut StreamFragment,
106    mut f: impl FnMut(&mut risingwave_pb::plan_common::StorageTableDesc),
107) {
108    visit_fragment_mut(fragment, |body| {
109        if let NodeBody::Source(node) = body
110            && let Some(table) = node
111                .source_inner
112                .as_mut()
113                .and_then(|source| source.iceberg_fetch_state_table.as_mut())
114        {
115            f(table);
116        }
117    });
118}
119
120/// Visit the tables of a [`StreamNode`].
121pub fn visit_stream_node_tables_inner<F>(
122    stream_node: &mut StreamNode,
123    internal_tables_only: bool,
124    visit_child_recursively: bool,
125    mut f: F,
126) where
127    F: FnMut(&mut Table, &str),
128{
129    macro_rules! always {
130        ($table:expr, $name:expr) => {{
131            let table = $table
132                .as_mut()
133                .unwrap_or_else(|| panic!("internal table {} should always exist", $name));
134            f(table, $name);
135        }};
136    }
137
138    macro_rules! optional {
139        ($table:expr, $name:expr) => {
140            if let Some(table) = &mut $table {
141                f(table, $name);
142            }
143        };
144    }
145
146    macro_rules! repeated {
147        ($tables:expr, $name:expr) => {
148            for table in &mut $tables {
149                f(table, $name);
150            }
151        };
152    }
153
154    let mut visit_body = |body: &mut NodeBody| {
155        match body {
156            // Join
157            NodeBody::HashJoin(node) => {
158                // TODO: make the degree table optional
159                always!(node.left_table, "HashJoinLeft");
160                always!(node.left_degree_table, "HashJoinDegreeLeft");
161                always!(node.right_table, "HashJoinRight");
162                always!(node.right_degree_table, "HashJoinDegreeRight");
163            }
164            NodeBody::TemporalJoin(node) => {
165                optional!(node.memo_table, "TemporalJoinMemo");
166            }
167            NodeBody::DynamicFilter(node) => {
168                always!(node.left_table, "DynamicFilterLeft");
169                always!(node.right_table, "DynamicFilterRight");
170            }
171
172            // Aggregation
173            NodeBody::HashAgg(node) => {
174                assert_eq!(node.agg_call_states.len(), node.agg_calls.len());
175                always!(node.intermediate_state_table, "HashAggState");
176                for (call_idx, state) in node.agg_call_states.iter_mut().enumerate() {
177                    match state.inner.as_mut().unwrap() {
178                        agg_call_state::Inner::ValueState(_) => {}
179                        agg_call_state::Inner::MaterializedInputState(s) => {
180                            always!(s.table, &format!("HashAggCall{}", call_idx));
181                        }
182                    }
183                }
184                for (distinct_col, dedup_table) in node
185                    .distinct_dedup_tables
186                    .iter_mut()
187                    .sorted_by_key(|(i, _)| *i)
188                {
189                    f(dedup_table, &format!("HashAggDedupForCol{}", distinct_col));
190                }
191            }
192            NodeBody::SimpleAgg(node) => {
193                assert_eq!(node.agg_call_states.len(), node.agg_calls.len());
194                always!(node.intermediate_state_table, "SimpleAggState");
195                for (call_idx, state) in node.agg_call_states.iter_mut().enumerate() {
196                    match state.inner.as_mut().unwrap() {
197                        agg_call_state::Inner::ValueState(_) => {}
198                        agg_call_state::Inner::MaterializedInputState(s) => {
199                            always!(s.table, &format!("SimpleAggCall{}", call_idx));
200                        }
201                    }
202                }
203                for (distinct_col, dedup_table) in node
204                    .distinct_dedup_tables
205                    .iter_mut()
206                    .sorted_by_key(|(i, _)| *i)
207                {
208                    f(
209                        dedup_table,
210                        &format!("SimpleAggDedupForCol{}", distinct_col),
211                    );
212                }
213            }
214
215            // Top-N
216            NodeBody::AppendOnlyTopN(node) => {
217                always!(node.table, "AppendOnlyTopN");
218            }
219            NodeBody::TopN(node) => {
220                always!(node.table, "TopN");
221            }
222            NodeBody::AppendOnlyGroupTopN(node) => {
223                always!(node.table, "AppendOnlyGroupTopN");
224            }
225            NodeBody::GroupTopN(node) => {
226                always!(node.table, "GroupTopN");
227            }
228
229            // Source
230            NodeBody::Source(node) => {
231                if let Some(source) = &mut node.source_inner {
232                    always!(source.state_table, "Source");
233                }
234            }
235            NodeBody::StreamFsFetch(node) => {
236                if let Some(source) = &mut node.node_inner {
237                    always!(source.state_table, "FsFetch");
238                }
239            }
240            NodeBody::SourceBackfill(node) => {
241                always!(node.state_table, "SourceBackfill")
242            }
243
244            // Sink
245            NodeBody::Sink(node) => {
246                // A sink with a kv log store should have a state table.
247                optional!(node.table, "Sink")
248            }
249
250            // Now
251            NodeBody::Now(node) => {
252                always!(node.state_table, "Now");
253            }
254
255            // Watermark filter
256            NodeBody::WatermarkFilter(node) => {
257                assert!(!node.tables.is_empty());
258                repeated!(node.tables, "WatermarkFilter");
259            }
260
261            // Shared arrangement
262            NodeBody::Arrange(node) => {
263                always!(node.table, "Arrange");
264            }
265
266            // Dedup
267            NodeBody::AppendOnlyDedup(node) => {
268                always!(node.state_table, "AppendOnlyDedup");
269            }
270
271            // EOWC over window
272            NodeBody::EowcOverWindow(node) => {
273                always!(node.state_table, "EowcOverWindow");
274                optional!(
275                    node.intermediate_state_table,
276                    "EowcOverWindowIntermediateState"
277                );
278                optional!(
279                    node.watermark_trigger_table,
280                    "EowcOverWindowWatermarkTrigger"
281                );
282            }
283
284            NodeBody::OverWindow(node) => {
285                always!(node.state_table, "OverWindow");
286            }
287
288            // Sort
289            NodeBody::Sort(node) => {
290                always!(node.state_table, "Sort");
291            }
292
293            // Stream Scan
294            NodeBody::StreamScan(node) => {
295                optional!(node.state_table, "StreamScan")
296            }
297
298            // Stream Cdc Scan
299            NodeBody::StreamCdcScan(node) => {
300                always!(node.state_table, "StreamCdcScan")
301            }
302
303            NodeBody::EowcGapFill(node) => {
304                always!(node.prev_row_table, "EowcGapFillPrevRowTable");
305            }
306
307            NodeBody::GapFill(node) => {
308                always!(node.state_table, "GapFillStateTable");
309            }
310
311            NodeBody::MatchRecognize(node) => {
312                always!(node.state_table, "MatchRecognizeStateTable");
313            }
314
315            // Note: add internal tables for new nodes here.
316            NodeBody::Materialize(node) => {
317                if !internal_tables_only {
318                    // Note: Plan directly generated by frontend may not have the table filled,
319                    // as it is filled by the meta service during building fragments.
320                    // However, if caller requests to visit this table via `!internal_tables_only`,
321                    // we still assert on its existence to avoid undefined behavior.
322                    always!(node.table, "Materialize");
323                }
324                // Also visit the staging table if it exists (for refreshable tables)
325                optional!(node.staging_table, "MaterializeStaging");
326                optional!(node.refresh_progress_table, "MaterializeRefreshProgress");
327            }
328
329            // Global Approx Percentile
330            NodeBody::GlobalApproxPercentile(node) => {
331                always!(node.bucket_state_table, "GlobalApproxPercentileBucketState");
332                always!(node.count_state_table, "GlobalApproxPercentileCountState");
333            }
334
335            // AsOf join
336            NodeBody::AsOfJoin(node) => {
337                always!(node.left_table, "AsOfJoinLeft");
338                always!(node.right_table, "AsOfJoinRight");
339            }
340
341            // Synced Log Store
342            NodeBody::SyncLogStore(node) => {
343                always!(node.log_store_table, "StreamSyncLogStore");
344            }
345
346            // MaterializedExprs
347            NodeBody::MaterializedExprs(node) => {
348                always!(node.state_table, "MaterializedExprs");
349            }
350
351            // Vector Index Write
352            NodeBody::VectorIndexWrite(node) if !internal_tables_only => {
353                always!(node.table, "StreamVectorIndexWrite");
354            }
355
356            NodeBody::LocalityProvider(node) => {
357                always!(node.state_table, "LocalityProviderState");
358                always!(node.progress_table, "LocalityProviderProgress");
359                optional!(node.sort_buffer_table, "LocalityProviderSortBuffer");
360            }
361
362            NodeBody::IcebergWithPkIndexWriter(node) => {
363                always!(node.pk_index_table, "IcebergWithPkIndexWriter");
364            }
365
366            _ => {}
367        }
368    };
369    if visit_child_recursively {
370        visit_stream_node_mut(stream_node, visit_body)
371    } else {
372        visit_body(stream_node.node_body.as_mut().unwrap())
373    }
374}
375
376pub fn visit_stream_node_stream_scan(stream_node: &StreamNode, mut f: impl FnMut(&StreamScanNode)) {
377    visit_stream_node_body(stream_node, |body| {
378        if let NodeBody::StreamScan(node) = body {
379            f(node)
380        }
381    })
382}
383
384pub fn visit_stream_node_source_backfill(
385    stream_node: &StreamNode,
386    mut f: impl FnMut(&SourceBackfillNode),
387) {
388    visit_stream_node_body(stream_node, |body| {
389        if let NodeBody::SourceBackfill(node) = body {
390            f(node)
391        }
392    })
393}
394
395pub fn visit_stream_node_internal_tables<F>(stream_node: &mut StreamNode, f: F)
396where
397    F: FnMut(&mut Table, &str),
398{
399    visit_stream_node_tables_inner(stream_node, true, true, f)
400}
401
402pub fn visit_stream_node_tables<F>(stream_node: &mut StreamNode, f: F)
403where
404    F: FnMut(&mut Table, &str),
405{
406    visit_stream_node_tables_inner(stream_node, false, true, f)
407}
408
409/// Visit the internal tables of a [`StreamFragment`].
410pub fn visit_internal_tables<F>(fragment: &mut StreamFragment, f: F)
411where
412    F: FnMut(&mut Table, &str),
413{
414    visit_stream_node_internal_tables(fragment.node.as_mut().unwrap(), f)
415}
416
417/// Visit the tables of a [`StreamFragment`].
418///
419/// Compared to [`visit_internal_tables`], this function also visits the table of `Materialize` node.
420pub fn visit_tables<F>(fragment: &mut StreamFragment, f: F)
421where
422    F: FnMut(&mut Table, &str),
423{
424    visit_stream_node_tables(fragment.node.as_mut().unwrap(), f)
425}