When should a Flink DataStream job run with execution.runtime-mode set to BATCH instead of STREAMING?

## Two runtime modes over one API Flink's DataStream API is deliberately unified: the same program can execute in `STREAMING` mode — the classic behaviour, continuous incremental processing, expected to stay online indefinitely — or in `BATCH` mode, which executes more like a batch framework. Flink's promise is that a DataStream application over *bounded* input produces the same **final** results in either mode. The word final matters: a STREAMING run may emit incremental updates along the way (think upserts), while a BATCH run emits one result at the end. The mode is set with `execution.runtime-mode`, which accepts three values: `STREAMING` (default), `BATCH`, and `AUTOMATIC`, where Flink decides from the boundedness of the sources. ```bash bin/flink run -Dexecution.runtime-mode=BATCH job.jar ``` You can also call `env.setRuntimeMode(RuntimeExecutionMode.BATCH)` in code, but the documentation explicitly recommends against it: keeping the application configuration-free lets the same JAR run in either mode depending on how it is submitted. ## The boundedness rule Boundedness is a property of a *source*: does it know all its input up front, or may new data keep arriving indefinitely? A job is bounded only if **every** source is bounded. BATCH mode can only be used for bounded jobs. STREAMING works for both, which is why it is the safe default. A bounded file source is bounded. A Kafka source configured with an end offset is bounded; the same source reading to the end of the topic and staying is not. This is why `AUTOMATIC` is attractive for pipelines whose source configuration varies between environments. ## What changes underneath **Scheduling and shuffles.** In STREAMING mode all tasks are online simultaneously, and shuffles are *pipelined*: records go to downstream tasks immediately, with buffering at the network layer. That is required for low latency, and it means the cluster must have enough slots to run every task at once. In BATCH mode the job splits into stages at the shuffle boundaries. Flink fully processes one stage, materializes its output to non-ephemeral storage, and then runs the next — so upstream tasks can go offline and the job can complete on fewer slots than it has tasks. **State.** In STREAMING mode the configured state backend governs how keyed state is stored. In BATCH mode the state backend is **ignored**. Instead the input to a keyed operation is grouped by key using sorting, and all records for one key are processed in turn, so only one key's state needs to be resident; that key's state is discarded when the run moves to the next key. That is why a BATCH run can process a key space far larger than would fit in a streaming job's state. **Time and watermarks.** STREAMING mode uses watermarks as a heuristic about out-of-orderness. BATCH mode can sort by timestamp instead, so it behaves as if watermarks were perfect. Flink only needs a `MAX_WATERMARK` at the end of each key's input; user `WatermarkGenerator` implementations are ignored. A `WatermarkStrategy` is still worth supplying, because its `TimestampAssigner` still assigns record timestamps. Processing-time timers likewise all fire at the end of input. **Recovery.** STREAMING mode recovers by restarting the running tasks from a checkpoint. BATCH mode backtracks to previous stages whose intermediate results still exist, so potentially only the failed task and its predecessors restart. That is cheaper, and it is one of the stated reasons to prefer BATCH when the job allows. ## What breaks in BATCH mode The documentation is blunt about the limits. **Checkpointing does not work in BATCH mode**, and neither does anything that waits for a checkpoint: a `CheckpointListener` never hears `notifyCheckpointComplete()`, and a legacy `SinkFunction` that commits on that callback — one built on the deprecated `TwoPhaseCommitSinkFunction`, say — never gets the signal to commit. A transactional sink that must work in BATCH has to be built on the unified Sink API instead. In Flink 2.3 the file sink (`FileSink`) and the Kafka sink (`KafkaSink`) already are: at end of input the sink writer flushes and the committer commits everything it holds, so their output still lands. What changes is the timing — a `FileSink` with an on-checkpoint rolling policy never rolls mid-run, and each open part file is closed and committed once, when input ends. Rolling operations change shape. In STREAMING mode `reduce()` or `sum()` on a keyed stream emits an updated value for every arriving record; in BATCH mode they are not rolling and emit only the final result per key. A downstream consumer written to expect the update stream will see far fewer records. Custom operators are the sharp edge. Because BATCH processes key by key, the watermark switches from `MAX_VALUE` back to `MIN_VALUE` between keys — so an operator that caches the last seen watermark and assumes it only ascends will misbehave. Timers fire in key order first and timestamp order within a key. Changing a key manually inside an operator is unsupported. For most use cases the guidance is to use a process function rather than a custom operator, precisely to avoid these assumptions. ## Choosing The rule of thumb is simple: if the program is bounded, use BATCH, because it is more efficient; if it is unbounded, you must use STREAMING. The notable exception is deliberately running a bounded job in STREAMING mode to bootstrap state — run it, take a savepoint, restore that savepoint into the unbounded job — and running bounded sources in STREAMING mode when writing tests for code destined for unbounded input.