Flink SQL hints let you manually influence execution plan generation at the query level — without modifying table definitions or deployment settings. Use hints when the optimizer's default decisions do not match your workload's performance or resource requirements.
Three hint categories are available, all applying to streaming jobs:
| Hint type | Applies to | Minimum version |
|---|---|---|
| Dynamic table options | Streaming | VVR 4.x |
| Lookup join hints | Streaming | — |
| State TTL hints | Streaming | VVR 8.0.7 (group aggregation); VVR 8.0.1 (regular join) |
For the full hint syntax specification, see SQL hints.
Dynamic table options
Dynamic table options let you specify or override connector and format options within a single query scope, without changing the underlying table definition.
For syntax and usage examples, see Dynamic table options.
Lookup join hints
Lookup join hints control the lookup execution strategy, async mode, caching, and retry behavior for dimension table joins.
For syntax, available options, and examples, see JOIN hints for dimension tables.
State TTL hints
State time-to-live (TTL) hints let you set different TTL values for individual stateful operators within a single query. This reduces per-operator state sizes and improves system stability.
State TTL hints apply to two operator types:
| Operator | VVR 8.0.7 and later | VVR 8.0.6 and earlier |
|---|---|---|
| Regular join | State TTL hints + hints for regular join | Hints for regular join only |
| Group aggregation | State TTL hints | Not supported |
Configure state TTL
Three methods are available for configuring state TTL. They take effect in the following priority order:
Expert mode > State TTL hints > Deployment parameter
| Method | Scope | How to configure |
|---|---|---|
| Expert mode | Per operator, across deployments | See Configure operator parallelism, chaining policy, and state TTL |
| State TTL hints | Per operator, within a query | Inline /*+ STATE_TTL(...) */ hint |
| Deployment parameter | Entire deployment | Set table.exec.state.ttl — see table.exec.state.ttl |
Use state TTL hints when you need query-level TTL control without modifying deployment configuration. Use expert mode when the same per-operator settings apply across multiple deployments.