aljoscha commented on a change in pull request #14114: URL: https://github.com/apache/flink/pull/14114#discussion_r528830056
########## File path: docs/dev/datastream_execution_mode.md ########## @@ -0,0 +1,377 @@ +--- +title: "Execution Mode (Batch/Streaming)" +nav-id: datastream_execution_mode +nav-parent_id: streaming +nav-pos: 1 +--- +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +The DataStream API supports different runtime execution modes from which you +can choose depending on the requirements of your use case and the +characteristics of your job. + +There is the "classic" execution behavior of the DataStream API, which we call +`STREAMING` execution mode. This should be used for unbounded jobs that require +continuous incremental processing and are expected to stay online indefinitely. + +Additionally, there is a batch-style execution mode that we call `BATCH` +execution mode. This executes jobs in a way that is more reminiscent of batch +processing frameworks such as MapReduce. This should be used for bounded jobs +for which you have a known fixed input and which do not run continuously. + +Apache Flink's unified approach to stream and batch processing means that a +DataStream application executed over bounded input will produce the same +results regardless of the configured execution mode. By enabling `BATCH` +execution, we allow Flink to apply additional optimizations that we can only do +work when we know that our input is bounded. For example, different +join/aggregation strategies can be used, in addition to a different shuffle +implementation that allows more efficient failure recovery behavior. We will go +into some of the details of the execution behavior below. + +* This will be replaced by the TOC +{:toc} + +## When can/should I use BATCH execution mode? + +The `BATCH` execution mode can only be used for Jobs/Flink Programs that are +_bounded_. Boundedness is a property of a data source that tells us whether all +the input coming from that source is known before execution or whether new data +will show up, potentially indefinitely. A job, in turn, is bounded if all its +sources are bounded, and unbounded otherwise. + +`STREAMING` execution mode, on the other hand, can be used for both bounded and +unbounded jobs. + +As a rule of thumb, you should be using `BATCH` execution mode when your program +is bounded because this will be more efficient. You have to use `STREAMING` +execution mode when your program is unbounded because only this mode is general +enough to be able to deal with continuous data streams. + +One obvious outlier case is when you want to use a bounded job to bootstrap +some job state that you then want to use in an unbounded job. For example, by +running a bounded job using `STREAMING` mode, taking a savepoint, and then +restoring that savepoint on an unbounded job. This is a very specific use case +and one that might soon become obsolete when we allow producing a savepoint as +additional output of a `BATCH` execution job. + +Another case where you might run a bounded job using `STREAMING` mode is when +writing tests for code that will eventually run with unbounded sources. For +testing it can be more natural to use a bounded source in those cases. + +## Configuring BATCH execution mode + +The execution mode can be configured via the `execution.runtime-mode` setting. +There are three possible values: + + - `STREAMING`: The classic DataStream execution mode (default) + - `BATCH`: Batch-style execution on the DataStream API + - `AUTOMATIC`: Let the system decide based on the boundedness of the sources + +This can be configured via command line parameters of `bin/flink run ...`, or +programmatically when creating/configuring the `StreamExecutionEnvironment`. + +Here's how you can configure the execution mode via the command line: + +```bash +$ bin/flink run -Dexecution.runtime-mode=BATCH examples/streaming/WordCount.jar +``` + +This example shows how you can configure the execution mode in code: + + ```java +Configuration config = new Configuration(); +config.set(ExecutionOptions.RUNTIME_MODE, RuntimeExecutionMode.BATCH); +StreamExecutionEnvironment env = StreamExecutionEnvironment.getExecutionEnvironment(config); + ``` + +## Execution Behavior + +This section provides an overview of the execution behavior of `BATCH` +execution mode and contrasts it with `STREAMING` execution mode. For more +details, please refer to the FLIPs that introduced this feature: +[FLIP-134](https://cwiki.apache.org/confluence/x/4i94CQ) and +[FLIP-140](https://cwiki.apache.org/confluence/x/kDh4CQ). As well as the +documentation about [task scheduling (TODO)](<TODO>). + +### Task Scheduling And Network Shuffle + +Flink jobs consist of different operations that are connected together in a +dataflow graph. The system decides how to schedule the execution of these +operations on different processes/machines (TaskManager) and how data is Review comment: fixing ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org
