Skip to main content
VeloDB Cloud 26.x is based on Apache Doris 4.x. See Version Mapping.

Runtime Filter Wait Time Tuning

RuntimeFilter is a query optimization technique: at runtime, it generates filter conditions from the right-hand table of a Join and pushes them down to the left-hand table scan stage, thereby reducing I/O and computation.

When the RuntimeFilter wait time is set unreasonably (too short), the left-hand table scan may start before the filter is generated, causing the optimization to fail and the query to slow down.

The historical Apache Doris profile below illustrates the diagnosis. Its 5-second and 2-second durations are upstream observations without a complete benchmark environment and have not been reproduced in VeloDB Cloud.

Check whether a wait adjustment applies​

Before adjusting the wait time, confirm the following:

  • The query executes slowly and contains a Join operation.
  • You have obtained the execution plan with EXPLAIN and opened Query Profile.
  • The Profile contains the WaitForRuntimeFilter field.
  • The RuntimeFilter state is NOT_READY, or the Join build time is greater than the current wait time.

Parameter reference​

ParameterEngine defaultDescription
runtime_filter_wait_time_ms1000 msWait budget for a remote runtime filter. After the budget expires, the scan can continue without waiting for that filter. Local filters and infinite-wait mode use different waiting rules.

Check SHOW VARIABLES LIKE 'runtime_filter_wait_time_ms';, then test a session setting:

SET runtime_filter_wait_time_ms = 3000;

Example: Diagnose a filter that arrives late​

Step 1: Inspect the scan wait state​

Refer to the following Profile information:

OLAP_SCAN_OPERATOR (id=22. nereids_id=1764. table name = test_doris(test_doris)):(ExecTime: 62.870ms)
- RuntimeFilters: : RuntimeFilter: (id = 6, type = minmax, need_local_merge: true, is_broadcast: false, build_bf_cardinality: false, RuntimeFilter: (id = 7, type = in_or_bloomfilter, need_local_merge: true, is_broadcast: false, build_bf_cardinality: false,
- PushDownPredicates: []
- KeyRanges: ScanKeys:ScanKey=[null(-9223372036854775808) : 9223372036854775807]
- TabletIds: [1732763414173, 1732763414187, 1732763414201, 1732763414215]
- UseSpecificThreadToken: False
- AcquireRuntimeFilterTime: 969ns
- BlocksProduced: 1.829K (1829)
- CloseTime: 0ns
- ExecTime: 62.870ms
- InitTime: 75.703us
- KeyRangesNum: 0
- MaxScannerThreadNum: 32
- MemoryUsage:
- PeakMemoryUsage: 0.00
- NumScanners: 32
- OpenTime: 19.276ms
- ProcessConjunctTime: 30.360us
- ProjectionTime: 0ns
- RowsProduced: 7.433056M (7433056)
- RowsRead: 0
- RuntimeFilterInfo:
- ScannerWorkerWaitTime: 0ns
- TabletNum: 4
- TotalReadThroughput: 0
- WaitForDependency[OLAP_SCAN_OPERATOR_DEPENDENCY]Time: 0ns
- WaitForRuntimeFilter: 1000ms
RuntimeFilter: (id = 6, type = minmax):
- Info: [IsPushDown = false, RuntimeFilterState = NOT_READY, HasRemoteTarget = true, HasLocalTarget = false, Ignored = false]
RuntimeFilter: (id = 7, type = in_or_bloomfilter):
- Info: [IsPushDown = false, RuntimeFilterState = NOT_READY, HasRemoteTarget = true, HasLocalTarget = false, Ignored = false]

Key signals:

  • WaitForRuntimeFilter: 1000ms: The scan operator has waited for 1000ms.
  • RuntimeFilterState = NOT_READY: RuntimeFilters 6 and 7 are still not ready.
  • IsPushDown = false: The filters could not be pushed down to the scan stage.

Step 2: Locate the filter producer​

RuntimeFilter: (id = 6, type = minmax):
- Info: [IsPushDown = false, RuntimeFilterState = NOT_READY, HasRemoteTarget = true, HasLocalTarget = false, Ignored = false]
RuntimeFilter: (id = 7, type = in_or_bloomfilter):
- Info: [IsPushDown = false, RuntimeFilterState = NOT_READY, HasRemoteTarget = true, HasLocalTarget = false, Ignored = false]

Find the Join operator that generates RuntimeFilters 6 and 7 in the Profile:

HASH_JOIN_OPERATOR (id=26 , nereids_id=37948):
- PlanInfo
- join op: RIGHT OUTER JOIN(PARTITIONED)[]
- equal join conjunct: (id = ID)
- runtime filters: RF006[min_max] <- ID(6418/8192/1048576), RF007[in_or_bloom] <- ID(6418/8192/1048576)
- cardinality=6,418
- vec output tuple id: 27
- output tuple id: 27
- vIntermediate tuple ids: 25
- hash output slot ids: 396 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 447
- projections: USER_ID
- project output tuple id: 27
- BlocksProduced: sum 1, avg 1, max 1, min 1
- CloseTime: avg 10.111us, max 10.111us, min 10.111us
- ExecTime: avg 364.497us, max 364.497us, min 364.497us
- InitTime: avg 26.653us, max 26.653us, min 26.653us
- MemoryUsage: sum , avg , max , min
- PeakMemoryUsage: sum 0.00 , avg 0.00 , max 0.00 , min 0.00
- ProbeKeyArena: sum 0.00 , avg 0.00 , max 0.00 , min 0.00
- OpenTime: avg 45.985us, max 45.985us, min 45.985us
- ProbeRows: sum 0, avg 0, max 0, min 0
- ProjectionTime: avg 211.930us, max 211.930us, min 211.930us
- RowsProduced: sum 1, avg 1, max 1, min 1
- WaitForDependency[HASH_JOIN_OPERATOR_DEPENDENCY]Time: avg 1sec780ms, max 1sec780ms, min 1sec780ms

WaitForDependency[HASH_JOIN_OPERATOR_DEPENDENCY]Time: 1sec780ms shows about 1.78 seconds of dependency wait. This includes waiting for build-side work and is not an isolated measurement of hash-table construction. Together with the scan's 1-second wait and NOT_READY state, it suggests that the filter arrives after the scan stops waiting.

Step 3: Increase the wait time​

  • Goal: Allow the scan operator to wait until the RuntimeFilter is generated, so that pushdown is triggered.

  • Command:

    SET runtime_filter_wait_time_ms = 3000;
  • Explanation: Test a 3-second wait budget against the observed 1.78-second dependency delay, then verify filter readiness and total query duration. Dependency wait is not a direct measurement of filter generation time.

Step 4: Verify the effect​

The upstream example reports query time dropping from 5 seconds to 2 seconds. In your warehouse, rerun the same query and compare total duration, scanned rows, filter state, and resource usage. Keep the change only if the repeated measurements improve the workload.

Choose a diagnostic action​

SymptomPossible CauseRecommended Action
RuntimeFilterState = NOT_READY and WaitForRuntimeFilter is close to the limitWait time too short, slow Join buildIncrease runtime_filter_wait_time_ms
RuntimeFilterState = READY and IsPushDown = trueFilter has taken effectNo adjustment needed
Ignored = trueFilter has poor selectivity and is automatically ignoredCheck Join selectivity; do not force enable
Scan stage idles for a long timeWait time too long, filter has low valueReduce runtime_filter_wait_time_ms appropriately

FAQ​

Q1: Is a larger runtime_filter_wait_time_ms always better?

No. A long wait can delay scanning without enough filtering benefit. Compare build-side and dependency wait times, then test a modest increase for the affected query.

Q2: How to determine whether the RuntimeFilter actually takes effect?

Check the RuntimeFilterState and IsPushDown fields of the RuntimeFilter in the Profile. READY and IsPushDown = true indicate that it is available and pushed down in this profile. Check filtered and scanned rows to assess whether it reduces work.

Q3: What if it is still NOT_READY after the adjustment?

Check whether the right-hand table of the Join has a deeper bottleneck (such as data skew or slow Shuffle), or consider using a SQL Hint to disable RuntimeFilters that are ineffective for this query.

Q4: Can this parameter be set globally?

Yes, but it is recommended to adjust it at the Session level or for a single SQL through a Hint, to avoid affecting other queries globally.

Summary​

  • Choose the RuntimeFilter wait time using filter arrival, build-side work, and total query duration. There is no one-size-fits-all value.
  • Use EXPLAIN and Query Profile to inspect filter readiness, operator execution time, and dependency waits.
  • Use SET runtime_filter_wait_time_ms or a SQL Hint to adjust the wait time.
  • Recheck the setting when the plan, data distribution, or cluster workload changes.