Composite data source

Use the Composite data source type when a player source needs content from multiple data sources, merged into a single feed. You declare an ordered list of child sources (for example, Labels, then Recommendations). The SDK fetches the children in parallel, then merges them in declaration order into one flat list.

Composite is an SDK DataSourceType. You configure it in app code. It is not a CMS setting. Content managers don't configure Composite in the CMS. For how widgets attach to content, see Widgets and Player sources.

For the full list of data source types, see Data sources. For Trending and For you as product concepts, see Content recommendations. Wire those feeds with the Recommendations data source.

When to use Composite

Use Composite when a single source cannot express the feed you want, for example:

Show label-selected (promoted or editorial) items first, then fill with Trending or For you
Combine an IDs list from your backend with a Labels fallback
Merge two Labels expressions into one ordered feed without building merge logic in the host app

If one Labels, IDs, Search, or Recommendations source is enough, use that type directly.

How merge works

Fetch: The SDK fetches every child data source in parallel. Each child uses its normal fetch behavior.
Merge: Results are joined in the order you declared the children.
Deduplicate: If the same content ID appears in more than one child, the SDK keeps the first occurrence and drops later duplicates.
Read / unread: Widget read-status ordering applies to the final merged list, not to each child list separately.

See Ordering and item limits for shared order and maxItems options on child sources that support them.

Child entries and `isMandatory`

Each child is a data source plus optional config.

Setting	Default	Description
`isMandatory`	`false`	If `true`, a fetch failure for that child fails the entire composite. An empty success (0 items) is not a failure.

Failure rules:

Scenario	Behavior
A mandatory child fails	The whole composite fails
A non-mandatory child fails	That child is skipped; merge continues with the others
Every child fails	The composite fails

Partial failures are not reported separately to the host app.

Limits

A composite must include at least one child.
A child cannot be another Composite (no nesting).
A child cannot be a remote config data source. Use Composite only with local data source types (Labels, IDs, Search, Recommendations, and so on).
There is no composite-level maxItems. Cap volume with each child's maxItems where that child supports it.
The host app does not receive per-child failure callbacks.

Example pattern

Promoted or editorial content first, then a recommendations feed:

Child 1: Labels data source with the label expression for the items you want at the top (optionally isMandatory: true if that block must load).
Child 2: Recommendations data source set to Trending or For you.

Items that appear in both lists show once, at the earlier (Labels) position.

This is separate from cold start for For you, which the recommendations engine handles on its own. See Recommendations data source and Cold start for For you.

Platform API reference

API reference: iOS | Android | Web

Platform	Composite surface
iOS	`BlazeDataSourceType.composite` with `BlazeCompositeDataSourceEntry` / `BlazeCompositeDataSourceConfig`
Android	`BlazeDataSourceType.Composite` with `BlazeCompositeDataSourceEntry` / `BlazeCompositeDataSourceConfig`
Web	`BlazeSDK.DataSourceBuilder().composite(...)`

Composite is available starting with: Web 0.35.6, iOS 1.20.0, Android 1.20.3, and React Native 1.20.0.