apache_beam.runners.interactive.pipeline_instrument module

Module to instrument interactivity to the given pipeline.

For internal use only; no backwards-compatibility guarantees. This module accesses current interactive environment and analyzes given pipeline to transform original pipeline into a one-shot pipeline with interactivity.

class apache_beam.runners.interactive.pipeline_instrument.PipelineInstrument(pipeline, options=None)

Bases: object

A pipeline instrument for pipeline to be executed by interactive runner.

This module should never depend on underlying runner that interactive runner delegates. It instruments the original instance of pipeline directly by appending or replacing transforms with help of cache. It provides interfaces to recover states of original pipeline. It’s the interactive runner’s responsibility to coordinate supported underlying runners to run the pipeline instrumented and recover the original pipeline states if needed.

instrumented_pipeline_proto()

Always returns a new instance of portable instrumented proto.

background_caching_pipeline_proto()

Returns the background caching pipeline.

This method creates a background caching pipeline by: adding writes to cache from each unbounded source (done in the instrument method), and cutting out all components (transform, PCollections, coders, windowing strategies) that are not the unbounded sources or writes to cache (or subtransforms thereof).

has_unbounded_sources

Returns whether the pipeline has any capturable sources.

cacheables

Finds cacheable PCollections from the pipeline.

The function only treats the result as cacheables since there is no guarantee whether PCollections that need to be cached have been cached or not. A PCollection needs to be cached when it’s bound to a user defined variable in the source code. Otherwise, the PCollection is not reusable nor introspectable which nullifies the need of cache.

pcolls_to_pcoll_id

Returns a dict mapping str(PCollection)s to IDs.

original_pipeline_proto

Returns the portable proto representation of the pipeline before instrumentation.

original_pipeline

Returns a snapshot of the pipeline before instrumentation.

user_pipeline

Returns a reference to the pipeline instance defined by the user. If a pipeline has no cacheable PCollection and the user pipeline cannot be found, return None indicating there is nothing to be cached in the user pipeline.

The pipeline given for instrumenting and mutated in this class is not necessarily the pipeline instance defined by the user. From the watched scopes, this class figures out what the user pipeline instance is. This metadata can be used for tracking pipeline results.

runner_pcoll_to_user_pcoll

Returns cacheable PCollections correlated from instances in the runner pipeline to instances in the user pipeline.

instrument()

Instruments original pipeline with cache.

For cacheable output PCollection, if cache for the key doesn’t exist, do _write_cache(); for cacheable input PCollection, if cache for the key exists, do _read_cache(). No instrument in any other situation.

Modifies:

self._pipeline

preprocess()

Pre-processes the pipeline.

Since the pipeline instance in the class might not be the same instance defined in the user code, the pre-process will figure out the relationship of cacheable PCollections between these 2 instances by replacing ‘pcoll’ fields in the cacheable dictionary with ones from the running instance.

cache_key(pcoll)

Gets the identifier of a cacheable PCollection in cache.

If the pcoll is not a cacheable, return ‘’. The key is what the pcoll would use as identifier if it’s materialized in cache. It doesn’t mean that there would definitely be such cache already. Also, the pcoll can come from the original user defined pipeline object or an equivalent pcoll from a transformed copy of the original pipeline.

‘pcoll_id’ of cacheable is not stable for cache_key, thus not included in cache key. A combination of ‘var’, ‘version’ and ‘producer_version’ is sufficient to identify a cached PCollection.

cacheable_var_by_pcoll_id(pcoll_id)

Retrieves the variable name of a PCollection.

In source code, PCollection variables are defined in the user pipeline. When it’s converted to the runner api representation, each PCollection referenced in the user pipeline is assigned a unique-within-pipeline pcoll_id. Given such pcoll_id, retrieves the str variable name defined in user pipeline for that referenced PCollection. If the PCollection is not watched, return None.

apache_beam.runners.interactive.pipeline_instrument.build_pipeline_instrument(pipeline, options=None)

Creates PipelineInstrument for a pipeline and its options with cache.

Throughout the process, the returned PipelineInstrument snapshots the given pipeline and then mutates the pipeline. It’s invoked by interactive components such as the InteractiveRunner and the given pipeline should be implicitly created runner pipelines instead of pipeline instances defined by the user.

This is the shorthand for doing 3 steps: 1) compute once for metadata of the given runner pipeline and everything watched from user pipelines; 2) associate info between the runner pipeline and its corresponding user pipeline, eliminate data from other user pipelines if there are any; 3) mutate the runner pipeline to apply interactivity.

apache_beam.runners.interactive.pipeline_instrument.cacheables(pcolls_to_pcoll_id)

Finds PCollections that need to be cached for analyzed PCollections.

The function only treats the result as cacheables since there is no guarantee whether PCollections that need to be cached have been cached or not. A PCollection needs to be cached when it’s bound to a user defined variable in the source code. Otherwise, the PCollection is not reusable nor introspectable which nullifies the need of cache. There might be multiple pipelines defined and watched, this will only return for PCollections with pcolls_to_pcoll_id analyzed. The check is not strict because pcoll_id is not unique across multiple pipelines. Additional check needs to be done during instrument.

apache_beam.runners.interactive.pipeline_instrument.cacheable_key(pcoll, pcolls_to_pcoll_id, pcoll_version_map=None)

apache_beam.runners.interactive.pipeline_instrument.has_unbounded_sources(pipeline)

Checks if a given pipeline has capturable sources.

apache_beam.runners.interactive.pipeline_instrument.unbounded_sources(pipeline)

Returns a pipeline’s capturable sources.

apache_beam.runners.interactive.pipeline_instrument.pcolls_to_pcoll_id(pipeline, original_context)

Returns a dict mapping PCollections string to PCollection IDs.

Using a PipelineVisitor to iterate over every node in the pipeline, records the mapping from PCollections to PCollections IDs. This mapping will be used to query cached PCollections.

Returns:(dict from str to str) a dict mapping str(pcoll) to pcoll_id.