How does a Haystack pipeline branch on a runtime value and rejoin the branches?

## Branching is wiring, not code In an imperative chain you would write `if`. In Haystack the decision has to live in the graph, because the graph is what gets validated, serialized and drawn. The component for it is `ConditionalRouter`. ``` routes = [ {"condition": "{{ hits|length > 0 }}", "output": "{{ hits }}", "output_name": "found", "output_type": list}, {"condition": "{{ hits|length == 0 }}", "output": "{{ query }}", "output_name": "fallback", "output_type": str}, ] ``` Each route is a dict with four keys that do distinct jobs: - **condition** — a Jinja expression evaluated against the router's inputs. The variables you reference *become* the router's input sockets, which is how the router gets wired into the graph. - **output** — a Jinja expression producing the value to emit; often just a passthrough of one input. - **output_name** — becomes an output socket name you connect from. - **output_type** — the declared type of that socket, so the usual wiring-time compatibility check still applies to a branch edge. At run time the router evaluates conditions in order and emits on exactly one socket. Everything reachable only through the other sockets never receives its mandatory inputs and therefore never runs. That is the important operational property: an untaken branch costs nothing — no LLM call, no embedding, no latency. A route whose condition can never be true is dead wiring the framework will not warn you about, and if *no* condition matches you get a runtime error rather than a silent no-op. Write a catch-all last route when the input domain is open. ## Why joining needs a component Fan-out is free: one output socket may feed many receivers. Fan-in is not. A plain input socket holds exactly one incoming connection, so wiring both the `found` and the `fallback` branch into the same downstream input is rejected at `connect()` time. The rule exists because the pipeline must know unambiguously where a socket's value comes from. `BranchJoiner` is the escape hatch. You construct it with the type it carries — `BranchJoiner(str)` — and it exposes a **variadic** input (many connections allowed) and a single output of that same type. Whichever branch produced a value, the joiner forwards it, and the downstream component sees one ordinary edge. Because it is typed, the branches must agree on a type; that constraint is a feature, since it forces you to normalize divergent branches before they merge instead of downstream. Haystack ships other joiners for specific payloads — merging lists of answers, lists of strings, generic lists — and choosing the right one matters: a joiner that concatenates is not the same as one that forwards the first arrival. `BranchJoiner` is the one you reach for when the semantics are "exactly one of these branches ran". ## Other routers Not every branch needs a Jinja expression. `FileTypeRouter` sends files down per-MIME-type branches in an indexing pipeline; `MetadataRouter` splits documents by a metadata filter; there are model-based routers that classify text before branching. Use a purpose-built router when one exists — its conditions are declarative and self-documenting — and `ConditionalRouter` when the decision is genuinely bespoke. ## Shape of a real branching pipeline A typical grounded-answer flow: retrieve → router. If enough documents cleared the threshold, go down the RAG branch (prompt builder → generator). If not, go down a fallback branch (a canned "I don't know" builder, or a web-search component). Both branches ultimately produce a reply, so both feed a joiner, and the joiner feeds whatever formats the response. Diagrammed, this is four boxes and two edges more than a linear pipeline — and the diagram is exactly what `pipe.draw(path="pipeline.png")` gives you to put in a design review. (`draw()` renders through a Mermaid service, so it needs network access; in a notebook `pipe.show()` displays it inline.) ## Debugging branches When the wrong branch fires, the router's own output is the evidence you want, and by default it is consumed downstream and therefore absent from the result. Add the router's name to `include_outputs_from` and you see which socket carried a value. Second most common cause: a condition referencing a variable that is never supplied, so the router's input socket is unsatisfied and the router itself never runs — which looks identical to "the branch didn't fire" until you notice nothing downstream ran either. ## What to say about the tradeoff Branching in the graph is more verbose than an `if`, and it buys three things you cannot get from an `if`: the branch is visible in the drawn diagram, it survives serialization to YAML, and its edges are type-checked at wiring time. When a pipeline accumulates many routers, that verbosity stops paying and it is a signal to split the pipeline or push the decision up into calling code.