---
metadata:
  - name: generator
    content: Diplodoc Platform v5.64.2
alternate:
  - https://ytsaurus.tech/docs/en/flow/python/examples/external_state_join.md
  - https://ytsaurus.tech/docs/ru/flow/python/examples/external_state_join.md
  - href: https://ytsaurus.tech/docs/en/flow/python/examples/external_state_join.md
    type: text/markdown
    title: Markdown version
  - href: https://ytsaurus.tech/docs/en/llms.txt?revision=c426f39927f2807c73168512150ef54f4b741847
    rel: describedby
---
> **Documentation Index:** Fetch the complete configuration index at https://ytsaurus.tech/docs/en/llms.txt?revision=c426f39927f2807c73168512150ef54f4b741847

<!-- source: en/_includes/flow/python/examples/external_state_join.md -->
# External State Join in YTsaurus Flow (Python)

This pipeline enriches queue events from a prebuilt dynamic reference table through a read-only external state joiner.

[Source code](https://github.com/ytsaurus/ytsaurus/tree/main/yt/yt/flow/examples/python/external_state_join)

## Pipeline structure {#structure}

`event_reader` publishes the `event` stream. The `lookup_join` companion computation is grouped by `key`, reads `/reference` through `external_state_joiners`, and sends successful matches to `enriched`. The queue sink stores the output. The joiner's `path` may point to a Cypress link, allowing the reference table to be switched without restarting the pipeline.

See the [pipeline spec](https://github.com/ytsaurus/ytsaurus/tree/main/yt/yt/flow/examples/python/external_state_join/pipeline.yson).

## Read the joined state {#lookup}

`ctx.joined_external_state("/reference", message)` selects the joined row by the message key. The returned accessor is read-only. A missing row is represented by an empty payload, so `get("name")` returns `None` and the example emits nothing.

```python
class LookupJoin(RowFunction):
    """Looks up each event's name in the reference state and emits the joined row."""

    def on_message(self, message, output, ctx):
        name = ctx.joined_external_state("/reference", message).get("name")
        if name is None:
            return

        builder = ctx.message_builder("enriched")
        builder.set("key", message.payload["key"])
        builder.set("name", name)
        output.add_message(builder.finish())

```

## See also

- [External State (Python)](https://ytsaurus.tech/docs/en/flow/python/external-state.md)
- [Static Table Join example](https://ytsaurus.tech/docs/en/flow/python/examples/static_table_join.md)
<!-- endsource: en/_includes/flow/python/examples/external_state_join.md -->