Summary

A relationship is a named output path from a processor. Every FlowFile leaving a processor must go through one of its relationships. To keep a flow valid, each relationship must be connected to another component or explicitly terminated.

What a relationship actually is

A relationship is a logical output path defined by the processor.

Examples include:

• success

• failure

• retry

• original

• response

These names come from the processor itself. 

Relationships create queues when connected

A relationship by itself does nothing.

When you draw a connection from a relationship to another component:

Processor A (success) → Processor B

Clockspring creates a queue between them.

• Relationship = logical output

• Connection = link to another component

• Queue = buffer that stores FlowFiles on that connection

You can have multiple connections from the same relationship, and each connection has its own queue.

A FlowFile can be duplicated when a relationship has multiple connections

If a processor routes a FlowFile to a relationship that has more than one connection, Clockspring automatically duplicates the FlowFile.

Example:

Processor A (success)   
↳ Processor B   
↳ Processor C

If a FlowFile routes to success:

• One copy goes to A→B

• One copy goes to A→C

Both FlowFiles start identical until downstream processors modify them.

You are not creating multiple “success” relationships - you are creating multiple connections from the same relationship.

Every relationship must be handled

Clockspring requires that all possible output paths from a processor be addressed.

For each relationship, you must either:

1. Connect it to another component, or

2. Terminate it (mark it intentional)

If you do neither, the processor becomes invalid, and you cannot start it.  This prevents accidental data loss.

Relationships drive routing behavior

Processors decide which relationship a FlowFile follows based on:

• Processing outcome

• Expression Language evaluations

• Attribute values

• Lookup or cache results

• Record counts

• Matching rules

This is why attributes are so critical - routing almost always depends on them.

Relationship changes can affect processor validity

A processor may become invalid if:

• A relationship is unconnected

• A required relationship is not terminated

• A downstream component is deleted

• A dynamic relationship is added but not connected or terminated

• You remove a connected relationship (leads to a dotted “dead” connection)

Relationship changes must be resolved before the processor will run.

Why relationships matter

Relationships define:

• How FlowFiles branch

• What happens on success vs failure

• Whether multiple downstream paths receive a copy

• Error handling behavior

• Retry logic

• Data lineage and auditability

Understanding relationships is essential before learning retries, backpressure, or advanced routing.

Quick rules to remember

• Relationships are logical output paths — queues appear only when you connect them.

• A single relationship can feed multiple downstream components.

• A FlowFile is duplicated for every connection on that relationship.

• All relationships must be connected or terminated.

• Changing relationships may invalidate processors.

• Routing decisions usually come from attributes.

Related Articles

• Managing Relationship Connections

• Queues and Backpressure

• Retries, Yielding, and Penalization

• Terminating Relationships