What is the Relay?¶
The Relay is the data ingestion component of 3forge Enterprise: it streams realtime data from external sources into the Center, and executes on-demand queries and uploads against external systems on the Center's behalf.
Getting data into 3forge Enterprise¶
Every ingestion route in this section delivers data through a Relay to one or more Centers.
| To ingest | Use | Page |
|---|---|---|
| A continuous feed from an external system, such as a message bus or market data source | A feed handler | Feed handlers |
| Data your own application publishes | A client library, which sends realtime messages to the Relay | Realtime Messages, Client Libraries |
| A file, as a one-off bulk import | The LoadFile command | LoadFile |
| Messages the Relay has already received, again | The Replay command | Replay |
To reshape messages on the way in, use Relay Transforms. To query an external database on demand rather than ingest from it, use a datasource; see Connect.
Overview¶
The Relay runs as an independent process alongside the Center and the Web, and connects to one or more Centers over two message channels: outbound (Relay-to-Center), carrying row-level insert/update/delete events and command responses, and inbound (Center-to-Relay), carrying commands, acknowledgments, snapshot and replay requests, and datasource queries. Feed handlers push change events into the Relay through the AmiRelayIn interface as they occur at the source; the Relay assigns each outgoing batch a sequence number, and each connected Center acknowledges processed sequence numbers independently, so a slow or disconnected Center does not hold up delivery to the others.
Datasource adapters normally run on the Center itself; a datasource can instead be configured to run on a Relay, in which case the Center forwards the query on the inbound channel and the Relay returns the result on the outbound channel. It is kept for existing configurations; new datasources should run on their host Center. The datasource registration itself is always stored in the Center regardless of where the query executes.
Feed handlers and datasource adapters that are not part of the base install must be installed into the plugins directory before they can be configured.
Two durability mechanisms cover resilience and audit: guaranteed messaging (ami.relay.guaranteed.messaging.enabled, disabled by default) journals outbound batches to disk until every connected Center acknowledges them, so a reconnecting Center replays from its last acknowledged sequence number instead of resyncing fully; see Configuration for the property details.
The journal files, messages.recovery and keys.recovery, are written to the directory set by ami.relay.persist.dir, which defaults to persist/ relative to the working directory of the running instance.
In this section¶
- Feed handlers: define feed handlers in the watched
relay.feedhandlersfile, and manage them at runtime through the f1 console or MCP tools. - Realtime Messages: the pipe-delimited protocol feed handlers and client applications use to exchange data with a Relay.
- Relay Transforms: rules that modify, translate, or enrich inbound feed handler payloads before they reach the Center.
- Replay: replay a Relay's
AmiMessages.logthrough a synthetic feed handler session, for auditing and rebuilding state. - LoadFile: load tabular data from a file directly into a Center table, for one-off bulk import rather than a continuous feed.
To connect an application, BI tool, or agent to 3forge Enterprise instead, see Connect.