Cascading 3.0 User Guide - Configuring

Configuring

Introduction

Cascading provides a number of ways to pass properties down for use by built-in or custom operations and integrations, to Cascading internals, or to the underlying platform.

Additionally the scope of the configuration properties can be application-wide, limited to a specific process level (a Flow, a FlowStep, or a FlowNode), or specific to a given Pipe or Tap instance.

Creating Properties

Cascading is very configurable. You can configure aspects of Cascading by creating a property set. Each property consists of a key-value pair. The key is a String value, such as cascading.app.appjar.path. The value is the String path to the "app JAR."

Property sets can be managed directly in a java.util.Properties instance. This class has methods that allow *.property files to be loaded from disk or other locations.

Properties is a subclass of Map<Object,Object>. Any Map type can be used, so long as key-value pairs are stored as type java.util.String.

Properties can be nested via the constructor creating a hierarchy of default key values. But calling getKeySet() and other Map-specific API calls does not return the nested key values. See Properties.getPropertyNames().

Props

All frequently used Cascading properties are encapsulated in subsystem-specific Props subclasses. All Props classes are fluent-style interfaces for creating property sets. For example, the AppProps class can be used for setting application-level configuration settings.

Example 1. Configuring the application JAR

Properties properties = AppProps.appProps()
  .setName( "sample-app" )
  .setVersion( "1.2.3" )
  .addTags( "deploy:prod", "team:engineering" )

  .setJarClass( Main.class ) (1)

    // ALTERNATIVELY ...

  .setJarPath( pathToJar ) (2)

  .buildProperties();

The Props interface allows for both setting available values as well as populating either a Properties or ConfigDef instance for use by Cascading.

There are various "Props-based" classes that expose fluent API calls. The following table lists the most commonly used classes for creating property sets with fluent-style interfaces.

cascading.property.AppProps

Allows for setting application-specific properties. Some properties are required by the underlying platform, like application JAR. Others are simple metadata used by compatible management tools, like tags.

cascading.flow.FlowConnectorProps

Allows for setting a DebugLevel or AssertionLevel for a given FlowConnector to target. Also allows for setting intermediate DecoratorTap subclasses to be used, if any.

cascading.flow.FlowProps

Allows for setting any Flow-specific properties like the maximum concurrent steps to be scheduled, or changing the default Tuple Comparator class.

cascading.flow.FlowRuntimeProps

Allows for setting specific runtime properties, like the level of parallelization to use.

cascading.cascade.CascadeProps

Allows for setting any Cascade-specific properties like the maximum concurrent Flows to be scheduled.

cascading.tap.TrapProps

Allows for fine-grained configuration of what diagnostic data traps should capture on failures.

cascading.tuple.collect.SpillableProps

Allows for fine-grained control over how to manage spilling of data during certain operators that accumulate data. Specifically thresholds and what compression codecs to use.

cascading.pipe.assembly.AggregateByProps

Allows for fine-grained control over the underlying caches used.

Passing Properties

Properties can be applied to the following scopes:

Application: through a default, shared Properties instance
Flow: through a Flow-specific Properties instance passed to the proper FlowConnector
FlowStep: through either Pipe.getStepConfigDef() or Tap.getStepConfigDef()
FlowNode: through either Pipe.getNodeConfigDef() or Tap.getNodeConfigDef()
Pipe: through Pipe.getConfigDef()
Tap: through Tap.getConfigDef()

In the cases of FlowStep and FlowNode, the Pipe and Tap instances that are coded to run on those levels are inspected for property settings. The property settings are merged and, if possible, applied to the underlying configuration for that level.

FlowNode-level properties cannot be applied to the MapReduce platform.

Planner Properties

Properties passed to a FlowConnector are checked by the Cascading query planner. In addition, these properties are pushed directly to the underlying platform as defaults. Any such properties can be overridden by a given scoped ConfigDef instance.

ConfigDef

The ConfigDef class supports the creation of a configuration properties template. The template can then be applied to an existing properties configuration set.

There are three property mode: Mode.DEFAULT, Mode.REPLACE, and Mode.UPDATE.

A DEFAULT property is only applied if there is no existing value in the property set.
A REPLACE property is always applied overriding any previous values.
An UPDATE property is always applied to an existing property, usually when the property key represents a list of values.

The following examples show using the ConfigDef at different scopes.

Example 2. Configuring properties at the FlowStep scope

Pipe join =
  new HashJoin( lhs, common, rhs, common, declared, new InnerJoin() );

SpillableProps props = SpillableProps.spillableProps()
  .setCompressSpill( true )
  .setMapSpillThreshold( 50 * 1000 );

props.setProperties( join.getStepConfigDef(), ConfigDef.Mode.DEFAULT );

Example 3. Configuring properties at the Pipe scope

Pipe join =
  new HashJoin( lhs, common, rhs, common, declared, new InnerJoin() );

SpillableProps props = SpillableProps.spillableProps()
  .setCompressSpill( true )
  .setMapSpillThreshold( 50 * 1000 );

props.setProperties( join.getConfigDef(), ConfigDef.Mode.REPLACE );