Read/Write Splitter

Route selected reads to secondary targets and writes to the primary.

Always confirm availability in the release bundle selected for deployment.

At a glance

Property	Value
Pipeline phase	Router
Category	Routing
Canonical minimum tier	Pro
Canonical entitlement	Yes
Supported deployment contract	Yes
Release status	Catalog component; confirm a bundle that executes router-phase components.

Release accuracy

• Current documentation: Catalog component; confirm a bundle that executes router-phase components.

Where any detail below conflicts with the release status above, the release status is authoritative. Field names and examples describe the current dashboard and CRD surface; always confirm behavior against the selected release bundle before relying on it operationally.

Release-aware feature flow. The diagram is explanatory; the release status on this page is authoritative.

Diagram resources: Open the SVG full screen · Download the editable Excalidraw source

Performance impact

:::warning Unverified performance figures

These figures are illustrative only. They are not current benchmarks or service guarantees and have not been verified by the current test suite.

:::

Percentile	Reported figure
P50	<0.1ms
P95	<0.2ms
P99	<0.3ms

Note: Command classification is a simple map lookup

Overview

The Read/Write Splitter inspects each incoming MongoDB command and routes it to the appropriate target: writes always go to the primary, while reads are distributed across secondaries using your chosen strategy.

This is transparent to the application — no readPreference configuration needed in drivers. The splitter monitors replication lag and automatically routes reads back to primary if a secondary falls too far behind.

When to use

• Offloading read traffic from primary without changing application code
• Scaling read-heavy workloads across replica set members
• Reducing latency for read operations by using geographically closer secondaries
• Gradually rolling out secondary reads with staleness guarantees

How it works

1. Incoming command is classified as read or write based on command name
2. Writes always route to primary_target
3. Reads are distributed to secondary_targets using the chosen strategy
4. Replication lag is monitored — if a secondary exceeds max_staleness, it's removed from rotation
5. Commands matching force_primary_patterns always go to primary regardless

Configuration

“Not specified” means required semantics were not declared for that field.

Field	Type	Default	Required	Description
primary_target	string	—	Yes	Primary MongoDB address
secondary_targets	json	—	Not specified	List of secondary addresses
strategy	select	round_robin	Not specified	Load balancing strategy for reads
max_staleness	duration	10s	Not specified	Max acceptable replication lag
read_commands	json	[find, aggregate, count, distinct]	Not specified	Commands routed to secondaries
force_primary_patterns	json	—	Not specified	Collections that always use primary

Settings reference

No additional settings reference is documented for this component.

Examples

Basic read scaling

steps:
  - id: builtin:read-write-split
    config:
      primary_target: mongo-primary:27017
      secondary_targets:
        - mongo-secondary-1:27017
        - mongo-secondary-2:27017
      strategy: round_robin
      max_staleness: 5s

Latency-based with exclusions

steps:
  - id: builtin:read-write-split
    config:
      primary_target: mongo-primary:27017
      secondary_targets:
        - mongo-secondary-us:27017
        - mongo-secondary-eu:27017
      strategy: latency
      max_staleness: 30s
      force_primary_patterns:
        - "^billing_"
        - "^transactions"

Best practices

• Start with a conservative max_staleness (5-10s) and increase based on your consistency requirements
• Use force_primary_patterns for collections that require read-after-write consistency
• Monitor secondary lag with the metrics step to tune staleness thresholds
• latency strategy works best with geographically distributed secondaries

Limitations

• Aggregation pipelines with $out or $merge always route to primary
• Cannot split reads within a multi-document transaction
• Staleness detection requires periodic isMaster checks (every 5s by default)

Security and operational guidance

• Validate replication lag and causal consistency
• Keep transactions and primary-required operations on the primary
• Do not infer runtime support from schema presence

Related steps

• connection-pipeline
• traffic-split
• intelligent-failover

Release availability

• Current documentation: Catalog component; confirm a bundle that executes router-phase components.

See the component catalog for the complete comparison matrix.