Using the Direct Runner
The Direct Runner executes pipelines on your machine and is designed to validate that pipelines adhere to the Apache Beam model as closely as possible. Instead of focusing on efficient pipeline execution, the Direct Runner performs additional checks to ensure that users do not rely on semantics that are not guaranteed by the model. Some of these checks include:
- enforcing immutability of elements
- enforcing encodability of elements
- elements are processed in an arbitrary order at all points
- serialization of user functions (
Using the Direct Runner for testing and development helps ensure that pipelines are robust across different Beam runners. In addition, debugging failed runs can be a non-trivial task when a pipeline executes on a remote cluster. Instead, it is often faster and simpler to perform local unit testing on your pipeline code. Unit testing your pipeline locally also allows you to use your preferred local debugging tools.
Here are some resources with information about how to test your pipelines.
- Testing Unbounded Pipelines in Apache Beam talks about the use of Java classes PAssert and TestStream to test your pipelines.
- The Apache Beam WordCount Walkthrough contains an example of logging and testing a pipeline with PAssert.
- The Apache Beam WordCount Walkthrough contains an example of logging and testing a pipeline with assert_that.
Direct Runner prerequisites and setup
Specify your dependency
When using Java, you must specify your dependency on the Direct Runner in your
<dependency> <groupId>org.apache.beam</groupId> <artifactId>beam-runners-direct-java</artifactId> <version>2.27.0</version> <scope>runtime</scope> </dependency>
This section is not applicable to the Beam SDK for Python.
Pipeline options for the Direct Runner
For general instructions on how to set pipeline options, see the programming guide.
When executing your pipeline from the command-line, set
DirectRunner. The default values for the other pipeline options are generally sufficient.
Additional information and caveats
Local execution is limited by the memory available in your local environment. It is highly recommended that you run your pipeline with data sets small enough to fit in local memory. You can create a small in-memory data set using a
Create transform, or you can use a
Read transform to work with small local or remote files.
If your pipeline uses an unbounded data source or sink, you must set the
streaming option to
Python FnApiRunner supports multi-threading and multi-processing mode.
The number of worker threads is defined by the
targetParallelism pipeline option.
targetParallelism is the greater of the number of available processors and 3.
Number of threads or subprocesses is defined by setting the
direct_num_workers pipeline option.
direct_num_workers = 0 is supported. When
direct_num_workers is set to 0, it will set the number of threads/subprocess to the number of cores of the machine where the pipeline is running.
Setting running mode
In Beam 2.19.0 and newer, you can use the
direct_running_mode pipeline option to set the running mode.
direct_running_mode can be one of [
in_memory: Runner and workers’ communication happens in memory (not through gRPC). This is a default mode.
multi_threading: Runner and workers communicate through gRPC and each worker runs in a thread.
multi_processing: Runner and workers communicate through gRPC and each worker runs in a subprocess.