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
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
