whatagraph-blends

Blends

Tools covered: list-blends, manage-blends.

A blend joins 2+ sources into a single virtual source, keeping each source's own columns. Sources can be from different channels (e.g. Google Ads + Meta + GA4) or from the same channel (e.g. two Google Ads accounts, one column each). The blend has its own integration source id, so widgets and custom metrics can treat the blend like any other source.

Use this when

• "Put Google Ads spend and Meta Ads spend in the same table grouped by date."
• "Compute Blended ROAS = GA4 revenue / (Google Ads spend + Meta Ads spend)." (Blend first, custom metric second.)
• "Cross-channel performance widget that groups by campaign theme across 3 platforms."
• "Show these two Google Ads accounts side by side, matched on campaign name." (Same-channel blend — a source group would sum them into one column.)
• "Combined numbers I can read right now, without waiting for a sync."

Blend vs source group — quick decision

	Source group	Blend
Operation	sums sources into one total	joins rows on a shared dimension
Output	the total, plus a per-channel and per-source variant of every metric (Impressions for Google Ads only) and Channel/Source name dimensions	each sub-source keeps its own columns
Channels	same or across	same or across
Scale	many — dozens to hundreds	a handful — 2–5 typical
Freshness	stored — ETL-written, warms up, as fresh as the last sync	live — computed in-request, ready immediately
Read ids	universal_* (+ _integration_<id> / _integration_source_<id>)	aggregation_* combined, blend_* per sub-source

Sum → source group. Join → blend. Live → blend. Many sources → source group.

Goal	Use
5 Google Ads accounts → 1 virtual "Google Ads Total"	Source group (same-channel)
Meta + Google + Reddit + TikTok → 1 aggregated source with unified metrics	Source group (cross-channel)
Sum of spend across Google + Meta into one total, no row-level join	Source group (cross-channel)
40 GBP locations / 25 client ad accounts → 1 rollup	Source group — a blend here would need 39 joins
Google Ads + Meta Ads joined/matched on campaign name (side-by-side rows)	Blend (cross-channel)
2 Google Ads accounts joined on campaign name, one column per account	Blend (same-channel)
Combined numbers that must be live — today's data, no warmup wait	Blend (same- or cross-channel)

Common mistake: source group ≠ same-channel-only, blend ≠ cross-channel-only. Both do both — channel count decides nothing.

Why scale differs: a group needs one ETL config per channel, not per source and serves precomputed data; a blend needs N−1 joins and re-fetches every sub-source per request. No hard cap either way. When live and many collide, scale wins — build the group and accept the warmup, or blend only the few sources watched live and roll the rest up.

Listing

list-blends action=list                # paginated; includes source_count, channel_names per blend
list-blends action=show blend_id=<id>  # full sub-sources, joins, widgets_count, per-sub-source filter

Only show reports each sub-source's filter. list does not, so never conclude a blend is unfiltered from a list response.

Creating a blend

manage-blends action=create
   name="Google Ads + Meta Ads — Campaign Blend"
   description="Cross-channel campaign performance"
   currency="USD"
   items=[
     {
       "integration_source_id": <google_ads_source>,
       "report_type": "campaign",
       "dimensions": ["universal_dimension_1137", "campaign_name"],
       "metrics":    ["universal_metric_1", "universal_metric_3"]
     },
     {
       "integration_source_id": <meta_ads_source>,
       "dimensions": ["universal_dimension_1137", "campaign_name"],
       "metrics":    ["universal_metric_1", "universal_metric_3"]
     }
   ]
   joins=[
     {
       "type": "full",
       "conditions": [
         {
           "left_source_id":  <google_ads_source>,
           "left_dimension":  "universal_dimension_1137",
           "right_source_id": <meta_ads_source>,
           "right_dimension": "universal_dimension_1137"
         },
         {
           "left_source_id":  <google_ads_source>,
           "left_dimension":  "campaign_name",
           "right_source_id": <meta_ads_source>,
           "right_dimension": "campaign_name"
         }
       ]
     }
   ]

items — each sub-source

• integration_source_id — id from list-sources action=list.
• report_type — the source's report type external id. Auto-resolved when source has exactly one report type; required when multiple exist. Omit entirely when the source has zero report types (e.g. Facebook Ads, GA4) — run list-sources action=list_report_types to check.
• dimensions — array of dimension external ids.
• metrics — array of metric external ids.
• filter_id — optional. Narrows THIS sub-source's rows before the join runs. See "Filtering one sub-source" below.

joins — how sub-sources connect

• type: left, inner, full, or cross.
• conditions: list of {left_source_id, left_dimension, right_source_id, right_dimension} pairs.

All conditions in one join are ANDed together. For more complex joins, add multiple join objects.

Join type — the most important blend decision

type	Behavior	When to use
full	Every row from both sides is kept; missing dimension pairs appear as nulls	Default; safest for "show everything"
inner	Only rows present in both sides	When you want ONLY campaigns that ran on both channels
left	All rows from left + matching from right	When the left source is the "primary" view
cross	Cartesian product	Rare; use only when you know why

Most blends should use full — it avoids excluding rows that only exist in one source. inner is a common source of "my data disappeared after blending" questions.

Write-time validation

manage-blends validates join topology when you create or update (not just at fetch time). A blend that breaks these rules is rejected up front with a specific message. Below is each rule, the error you get, and the fix.

Allowed topologies

Topology	OK?	Format to use
2 distinct sources, 1 join	✓	conditions (simplified)
3+ distinct sources, chained	✓	one join object per adjacent pair: joins=[{A–B},{B–C}]
Self-join (same source twice)	✓	groups/keys only (see below)
One join spanning 3+ sources	✗	split into one join per pair
A sub-source with no join	✗	must connect into the chain (unless a cross join is present)

Shape minimums

create requires at least 2 items and at least 1 join. Each groups/keys group needs at least 2 keys (one per side).

Self-join requires groups/keys (not conditions)

A self-join uses the same integration_source_id in two different items (e.g. one source compared this-month vs last-month). The simplified conditions format keys a join by source id alone, so with the source repeated it can't tell which item you mean. The groups/keys format carries col_index (the 0-based position in items), which disambiguates.

• Error (using conditions with a duplicated source): "Multiple items reference the same integration_source_id. The simplified conditions format cannot disambiguate which item to join. Use the legacy groups/keys format with explicit col_index instead."
• Fix — use groups/keys:

joins=[
  {
    "type": "inner",
    "groups": [
      { "keys": [
        { "col_index": 0, "integration_source_id": <S>, "external_id": "<dim>" },
        { "col_index": 1, "integration_source_id": <S>, "external_id": "<dim>" }
      ] }
    ]
  }
]

col_index 0 and 1 point at the first and second item that both carry source <S>.

One join connects exactly one pair of sources

Each join relates two different sub-sources. A single join cannot span three or more.

• Error (a join condition touches the same source on both sides or only one source): "Each join condition must connect exactly two different sub-sources..."
• Error (one join spans 3+ sources): "A single join can only relate one pair of sub-sources, but join N spans more than two — this blend would be saved but every data fetch would fail with 'Incorrect blend setup'."
• Fix: one join object per pair. To chain A–B–C: joins=[{A–B join},{B–C join}].

Every sub-source must be connected

All sub-sources must link (directly or transitively) into one chain.

• Error: "Sub-source X is not connected to the rest of the blend by any join. Every sub-source must be linked into a single chain — add a join condition relating it to an already-connected sub-source."
• Fix: add a join tying the orphaned source to one already in the chain. Exception: a cross join in the blend skips this connectivity check.

Date dimensions join only to date dimensions

A temporal dimension (date, datetime, month, week, …) cannot be matched against a non-temporal one.

• Error: "Join N matches incompatible dimension types: <dim> (date) on source A cannot be joined to <dim> (string) on source B. A date/time dimension must be joined to another date/time dimension."
• Fix: join date→date and the other key (campaign name, etc.) separately. Keys whose type can't be resolved are skipped, not rejected. (Note: this check currently runs on create only.)

Join keys must be declared dimensions

Every dimension named in a join must also appear in that sub-source's dimensions array.

• Error: "Join condition references dimension D which is not declared in the dimensions of source ID S..."
• Fix: add the join-key dimension to that item's dimensions.

Non-cross joins need conditions or groups

Only a cross join may om

---

Content truncated.