cds-data-federation

Documentation · npm

The annotation-driven SAP CAP plugin for integrating external services into your application's data model — declarative, no handler code. Composes cds-data-pipeline for scheduled sync.

Beyond CAP

CAP gives you the right concepts — consumption views, projection chains, cds.connect.to, remote.run(req.query) — and you rarely need much code per entity. But you still maintain that wiring in every project: on('READ') handlers, rename maps, replication loops, and schedule setup copied from samples such as xtravels or the S/4 mashup sample. Cross-service $expand and navigation are especially brittle — intercepting incoming OData requests and CQN, stripping expand items, batch-fetching from the right service, and stitching results by foreign key adds up fast.

This plugin needs zero wiring code. Annotate the consumption view; handlers, query translation, and pipeline binding are registered at boot.

| Benefit | What you get | |---|---| | Zero handler code | @federation.delegate / @federation.replicate on the projection — no per-entity srv files to maintain | | Consumption-view contract | Field and association renames, column restriction, static where — inferred from the projection, not hand-written maps | | Cross-service mashups | $expand and navigation across local ↔ remote boundaries handled inside the plugin — not manual request interception per scenario | | Scheduled replication | Full/delta sync into local tables via cds-data-pipeline — retry, concurrency guard, run history, REST sources | | Optional caching | Per-query (cds-caching) or full-entity SQLite snapshots on delegate | | Observability | Federation-bound pipelines in /pipeline and the Pipeline Console |

Full positioning against CAP samples and other approaches: Comparison with CAP.

Install

# Replicate or entity cache:
npm add cds-data-federation cds-data-pipeline

# Delegate-only:
npm add cds-data-federation

| Package | Version | Required when | |---|---|---| | @sap/cds | >= 9 | Always — CDS 9 and CDS 10 | | @sap-cloud-sdk/http-client, @sap-cloud-sdk/resilience | ^4 | OData remote services | | cds-data-pipeline | peer | @federation.replicate, cache.strategy: 'entity', custom pipeline hooks | | cds-caching | >= 1 | cache.strategy: 'response' (default cache strategy) | | @cap-js/sqlite | >= 2 | cache.strategy: 'entity' (2.x on CDS 9, 3.x on CDS 10) |

The plugin auto-activates on load via cds-plugin.js. Setup: Installation.

Choosing a strategy

| I need… | Use | |---|---| | Live data, writes to system of record | @federation.delegate | | Same remote queries repeated; tolerate TTL staleness | @federation.delegate + cache: { strategy: 'response' } | | Arbitrary filters/sorts on one entity; tolerate TTL | @federation.delegate + cache: { strategy: 'entity' } | | SQL joins with local tables, analytics, offline resilience | @federation.replicate (+ cds-data-pipeline) | | Plain REST JSON API (no CDS model on remote) | @federation.replicate + rest: { … } |

Start with delegate; add cache for latency/load; replicate when you need SQL power or offline resilience.

Full decision tree, limitations, and OData caveats: Choosing a strategy.

Features

The consumption view IS the federation contract — the @federation.* annotation declares runtime behavior; entity X as projection on remote.Y declares schema, renames, and column restriction. See Consumption views.

| Area | Highlights | Docs | |---|---|---| | Delegate | Live proxy, query translation, opt-in CUD, server-driven paging | Annotations | | Replicate | Full/delta sync, UPSERT, replicated aspect, pipeline hooks | First replication | | Caching | Per-query (response) or full-entity SQLite (entity) | Caching | | Cross-service | $expand and navigation across local ↔ remote boundaries | Cross-service scenarios |

Full capability list: Features.

Examples

using { ProviderService as remote } from '../srv/external/ProviderService';

@federation.delegate
entity Customers as projection on remote.Customers;

@federation.delegate
entity Products as projection on remote.Products {
    ID    as productId,
    name  as productName,
    price as unitPrice
};

@federation.replicate: { mode: 'delta', schedule: 600000, delta: { field: 'modifiedAt' } }
entity ReplicatedProducts as projection on remote.Products { ... };

All annotation options: Annotations reference.

Role of cds-data-pipeline

At boot, federation scans @federation.replicate (and entity-cache) annotations and calls addPipeline({ ... }) via pipeline-binding.js. You use annotations, not the engine API, unless you need custom PIPELINE.* hooks. Replicate pipelines appear in the shared /pipeline management API and Pipeline Console.

const pipelines = await cds.connect.to('data-pipeline');
pipelines.before('PIPELINE.MAP', 'ReplicatedPartners', async (req) => {
    req.data.sourceRecords = req.data.sourceRecords.filter(r => !r.blocked);
});

See pipeline features and first replication.

Pipeline Console

When management.reuse.console is enabled on cds-data-pipeline, federation-bound pipelines (replicate jobs, entity-cache entries) show up automatically:

Enable: Feature activation.

Documentation

• Federation guide — getting started, concepts, integration
• Annotations reference
• Choosing a strategy

Multi-tenancy: CAP MTX.

AI assistants

Coming soon. Agent guidance (AGENTS.md) and task skills for coding assistants will ship in a future release.

Related

• cds-data-pipeline — the pipeline engine this plugin composes.
• cds-caching — optional peer for cache.strategy: 'response'.