> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/getting-started/how-to-structure-data-in-coupler.io.md).

# How to structure data in Coupler.io

As your Coupler.io setup grows, the way you structure it matters more. How you split work across workspaces, what you group into one data flow, and how you shape datasets before they reach a destination all affect the reliability, maintainability, and accuracy of your reporting.

This guide helps you make those decisions. It follows a top-down path:

1. How to separate access and ownership
2. How to decide what belongs in one data flow
3. How to shape datasets inside a flow
4. How to prepare data for different destination types.

It ends with several complete configuration examples.

### Choose organizations and workspaces based on access and ownership

An organization is the top-level account in Coupler.io. It controls billing and contains one or more workspaces. A workspace is a fully isolated environment with its own data flows, connections, dashboards, and users. Each workspace has separate resources and membership. Access to one workspace does not automatically provide access to another.

This is the first structural decision you make, and it comes down to two questions: who should see what, and who should pay for what.

{% content-ref url="/pages/GU49c4M5r8yi2sXuRY3g" %}
[Workspaces & Organization](/account-management/workspaces-and-organization.md)
{% endcontent-ref %}

#### When to create a separate workspace

Create a separate workspace when a group of data flows, connections, and users should be invisible to everyone outside that group. The most common cases:

An agency managing multiple clients keeps each client in their own workspace. The client's ad accounts, dashboards, and reporting flows are isolated from every other client. When a client engagement ends, you can remove their workspace without affecting anything else.

A company with multiple departments (marketing, finance, sales) gives each department its own workspace when they should not see each other's data. A marketing analyst has no reason to browse finance data flows, and a dedicated workspace makes that impossible rather than relying on people not clicking on the wrong thing.

A team that handles sensitive data (payroll, financial records, customer PII) keeps it in a workspace with limited membership, even if other workspaces in the same organization are more open.

Do not place unrelated clients or projects in the same workspace just because their data flows look technically similar. Workspaces exist for access boundaries, not for grouping similar configurations.

{% content-ref url="/pages/sHMpsCcMgAypckMyYp8N" %}
[Add workspace to your organization](/account-management/workspaces-and-organization/how-to-add-workspace-to-your-organization.md)
{% endcontent-ref %}

#### When to create a separate organization

Create a separate organization when billing, ownership, or administration must be fully independent. The typical case: a client who wants to own their Coupler.io subscription, control who has access, and manage billing themselves. Set up the organization in their name, build out the flows, invite yourself as an Admin. When the engagement ends, you leave the organization. Their data, their account, no disruption.

If a client or team does not need independent billing, a workspace under your existing organization is the right choice.

{% content-ref url="/pages/TNpiOvQi0MwY1WXd1vdx" %}
[Create organization](/account-management/workspaces-and-organization/how-to-create-organization.md)
{% endcontent-ref %}

#### Connections and billing across workspaces

Usage is billed at the organization level, summed across all workspaces. One detail catches people: connecting the same source account in two different workspaces counts as two billable accounts, because workspace isolation extends to connections too.

This also happens within a single workspace when two team members each connect the same account (for example, the same Facebook Ads account) separately instead of sharing one connection.

How account usage is calculated depends on the source. For example, advertising integrations such as Google Ads and Facebook Ads count the individual advertising accounts used. URL-based sources like Airtable or CSV count each source separately. Check the account-limit documentation for the specific source before estimating usage.

Connect once, reuse within the workspace. Create new workspaces for access isolation, not to duplicate the same source.

#### Roles and flow ownership

Four roles control access. Owners and Admins have full control over data flows in their scope, while Users and Guests are more limited. For example, Users and Guests cannot see another member's private connections or copy their data flows.

Two behaviors matter for how you assign flow ownership:

The integration URL for destinations like Power BI, Tableau, and Excel Desktop is visible only to the flow's creator. If someone else needs that URL, the creator has to share it manually.

Only the flow's creator receives failure notification emails. If one person builds all the flows in a workspace, only they will know when something breaks. Distribute ownership so the person who gets the alert is the person who can diagnose and fix the source.

When you remove a user from the organization, Coupler.io requires you to reassign their flows, connections, and dashboards to another member before the removal goes through.

{% content-ref url="/pages/qHupmvbE9xANDNNMXNdD" %}
[User roles in Coupler.io](/account-management/workspaces-and-organization/user-roles-in-coupler.io.md)
{% endcontent-ref %}

### Decide what belongs in one data flow

A data flow can hold multiple sources and send data to multiple destinations. The decision of what to group together and what to separate is one of the most important structural choices you make.

The guiding principle: **one data flow should represent one coherent data project**. That might be one client, one dashboard, one analysis, one reporting model, or one group of related accounts. What defines "coherent" is whether the sources need to refresh together, transform together, and be maintained together.

#### Group sources that serve the same reporting objective

If you are building a cross-channel marketing report, the data from Google Ads, Facebook Ads, and LinkedIn Ads belongs in one flow. You need these sources together because the deliverable (an appended cross-platform campaign table) requires all of them. You can then send the combined table to Google Data Studio, the raw per-platform data to BigQuery, and the summary to an AI tool, all from the same flow, all refreshing on the same schedule.

The same logic applies to the same data type across accounts. Five Shopify stores for one client can go in one flow if you append them with an identifier column (store name or account ID) so every row traces back to its origin. Several Google Ads accounts for the same client can be handled the same way.

#### Separate sources that need different schedules

The refresh schedule is set per flow, not per source. If Google Ads data needs to refresh every hour and Google Search Console data only needs a daily update, putting them in the same flow forces a compromise. Either GSC refreshes more often than necessary (consuming quota for no benefit), or Google Ads refreshes too slowly for your reporting. Give them separate flows.

#### Separate sources that must succeed independently

Sources in the same flow share a single run. A problem with one source can hold up or affect the combined result. For example, if Facebook Ads and TikTok Ads are in the same flow and one of them encounters an API error, the other source's data may not refresh as expected either.

Use separate flows when each source must run and deliver data independently.

#### Separate by owner when different people maintain the data

Only the flow's creator gets failure alerts. If your PPC specialist maintains ad platform sources and your SEO analyst maintains search sources, they should each own their own flows. The person who gets the failure email should be the person who understands the source and can fix the problem.

#### Keep test and demo flows separate from production

If you are experimenting with a new source configuration, trying a different transformation approach, or building a demo for a client pitch, do it in a dedicated flow. Editing a production flow for testing purposes risks breaking a live dashboard.

#### Keep combined flows to a manageable size

Grouping a handful of related accounts in one flow works well. But packing thirty clients into a single flow creates a maintenance problem: disconnecting one client means editing a flow that twenty-nine others depend on. For large client sets, one flow per client is typically cleaner. Keep multi-account flows to a size where any single change does not put unrelated data at risk.

To scale a per-client setup efficiently, build one complete flow with the full source, transformation, and destination configuration, then duplicate it for the next client. Swap out the source accounts and rename the flow instead of rebuilding from scratch. This turns a finished flow into a reusable template.

### Shape datasets: raw data vs. prepared data

Inside a data flow, you work with two layers. Raw data is what Coupler.io pulls from the source API. Prepared data is what you build from it in the Data Sets step. A single flow can output both: raw tables to one destination and a prepared summary to another.

{% content-ref url="/pages/afTpIXFikv1QPaZKgmua" %}
[Preview Data](/functionality/data-set.md)
{% endcontent-ref %}

Three tools turn raw data into prepared datasets. Choosing the right one depends on the relationship between your sources.

#### Append: stack rows from compatible sources

Append combines datasets vertically by stacking their rows. Use it when multiple sources contain the same type of records with a compatible column structure.

Google Ads campaign stats and Facebook Ads campaign stats both contain columns like date, campaign name, impressions, clicks, and spend. Appending them produces a single cross-platform campaign table. Coupler.io matches columns by name, so this works cleanly when the schemas are aligned.

Some columns may only apply to one platform. That is fine. A few empty cells per row are normal and expected when the platforms genuinely share a common entity but have some platform-specific fields.

What does not work well: appending datasets that represent fundamentally different entities. Campaign-level stats and keyword-level data have different granularities and different columns. Appending them produces a table that mixes granularities, contains many irrelevant empty fields, and is difficult to filter, aggregate, or analyze consistently. Keep different entities as separate datasets.

{% content-ref url="/pages/DRZ4XrnyiexEgvqceZLi" %}
[Append data](/functionality/data-set/combining-data/append-data.md)
{% endcontent-ref %}

#### Join: merge datasets horizontally on a shared key

Join combines datasets side by side on a matching field. Use it when two sources describe the same thing from different angles.

Google Search Console gives you how pages perform in search results: queries, clicks, impressions, average position. GA4 tells you what happens after someone lands on those pages: engagement metrics, conversions, user behavior. Joining them on the page URL puts both perspectives in one row. Neither source gives you this view on its own.

The key field must exist in both datasets and contain matching values. Before joining, verify that both sources use the same format for the shared field (full URL vs. path only, trailing slashes, capitalization).

{% content-ref url="/pages/HC2Kdc1x6P1Cb4ev6NMx" %}
[Join data](/functionality/data-set/combining-data/join-data.md)
{% endcontent-ref %}

#### Aggregate: summarize a single dataset

Aggregate rolls detailed rows into summaries by grouping on one or more dimensions. Daily campaign data can be grouped into monthly totals for clicks, impressions, spend, and conversions. Derived metrics like CTR or CPA should then be recalculated from the aggregated values rather than averaged across rows.

It works on one dataset and does not require a second source. Use it when your destination needs a higher-level view than what the source provides.

{% content-ref url="/pages/FpymVmiSpgrOtHT3Xr2l" %}
[Aggregate data](/functionality/data-set/combining-data/aggregate-data.md)
{% endcontent-ref %}

#### Preserve identifiers

Whenever you combine data from multiple sources, accounts, platforms, or clients, add or preserve a column that identifies where each row came from: source platform, account name, store ID, client name. Without it, a row in your appended table is anonymous, and you lose the ability to filter, segment, or troubleshoot.

### Maintain reliability and efficient usage

These practices do not describe data modeling directly, but they affect how reliably your data flows run and how efficiently you use your plan.

#### Pull only what you need at the source step

Configure each source with the specific accounts, date ranges, fields, and metrics you will use. Do not pull everything and filter afterward. Narrower imports run faster, stay within row limits, and avoid permission-related failures. Some sources (Facebook Ads is a common example) grant access to certain fields only at specific permission levels. Selecting a field your account cannot access causes the entire import to fail, not just that field.

#### Choose the right granularity

If you need a per-country report, request data broken down by country. If you need a per-gender report, request it broken down by gender. These are two separate datasets, each with one breakdown dimension.

Do not import at the highest granularity (country + gender + age + device + day) and aggregate it yourself unless you are certain the metrics you need can be safely re-aggregated. Additive metrics like impressions, clicks, and spend can usually be summed. But non-additive metrics (unique users, conversion rates, ratios, precalculated averages) cannot be reproduced accurately by summing or averaging granular rows. The source platform's API calculates these correctly at the granularity you request, and that calculation is lost once the data is broken into finer rows.

A per-country view and a per-gender view are two separate datasets. A combined per-country-and-gender view is a single dataset broken down by both dimensions simultaneously. Decide which view you need before configuring the source.

#### Use filters at the right level

Filter at the source step when possible to reduce the volume before it enters Coupler.io. When the source does not support filtering, use the Data Sets step to narrow or split the data before it reaches the destination.

{% content-ref url="/pages/rZniNCB22r4cK4xpKQbB" %}
[Data filtering](/functionality/data-set/data-filtering.md)
{% endcontent-ref %}

#### Reuse connections, do not duplicate them

When the same account is used in multiple flows within a workspace, reuse an existing connection where possible instead of creating duplicate connections. Duplicate connections waste billable accounts and create maintenance overhead.

### Prepare data for each destination type

There is no single "correct" data structure. The right structure depends on where the data is going.

#### Google Data Studio and dashboards

Data Studio does not provide the same relational data-modeling capabilities as tools like Power BI. You can work with multiple data sources and use data blending, but managing several sources and blends adds complexity quickly. Unless you specifically need separate sources and are comfortable configuring them, prepare one report-ready dataset per dashboard in Coupler.io and send Data Studio the finished result.

If your dashboard shows cross-channel ad performance, building the appended campaign table in Coupler.io and sending that single table to Data Studio is typically simpler and more reliable than sending three separate platform tables and blending them inside the dashboard.

Power BI is different. It supports multiple tables with defined relationships, so separate tables per entity (campaigns, ad groups, keywords) work well there.

For any dashboard, include columns that identify the source platform, account, and report type so you can filter and segment the data in the visualization.

#### Google Sheets and Microsoft Excel

Spreadsheets are a good fit for small-to-moderate, report-ready data that people need to read, review, or share. Google Sheets caps at 10 million cells across the entire file (all tabs share that limit) and performance drops well before that. Large datasets and archival data belong in a warehouse.

Build the final dataset inside Coupler.io, including calculations and aggregations. Complex spreadsheet formulas can slow imports and contribute to execution timeouts. Where possible, perform calculations in Coupler.io and send ready-to-use values to the spreadsheet.

#### Data warehouses (BigQuery, Snowflake, PostgreSQL, Redshift, Supabase)

Load each entity into its own table. Shopify orders, customers, and products should be three separate tables. Relational databases are designed to store entities separately and combine them through queries and views. Send clean, normalized data and let the database handle joins.

If managing joins in the database is not something you want to deal with, prepare the combined dataset in Coupler.io and load a denormalized reporting table. Use consistent table names and include identifiers for the source and account.

#### AI destinations (Claude, ChatGPT, and others)

Send each dataset as its own destination rather than merging unrelated sources into one sparse table. When datasets with fundamentally different structures are appended together, many columns are empty for most rows, which makes it harder for the LLM to interpret the data correctly.

You can and should send multiple types of data to the same AI tool when the analysis calls for it. Send each ad platform's raw data as a separate destination for detailed questions, and send the appended cross-platform summary as another destination for high-level analysis. The LLM gets both the detail and the overview, each in a clean, self-contained form.

When an analysis requires a stable, reusable joined or appended dataset, prepare it in the Data Sets step before sending it to the AI destination. Some AI integrations can also query across multiple Coupler.io datasets or sources, but the available cross-source capabilities depend on the specific integration.

If you need a transformation that the Data Sets step does not cover, you may need to handle it through the AI tool's own capabilities. This is another reason to keep related sources in the same flow, where they can be combined in the Data Sets step before reaching the destination.

Currently, only one workspace per organization can be connected to AI integrations at a time. If you need to analyze data from a different workspace, disconnect the current one first.

### Example configurations

These examples show how the principles above come together in common setups.

#### Agency managing one client per workspace

An agency with ten clients creates ten workspaces, one per client. Inside each workspace, one data flow pulls all of that client's ad platform data (Google Ads, Facebook Ads, LinkedIn Ads), appends it into a cross-platform campaign table, and sends it to Data Studio. The same flow sends the raw per-platform tables to BigQuery for storage. A second flow in the same workspace pulls GA4 and Google Search Console on a different schedule and sends both to BigQuery. Flows are owned by the analyst responsible for that client.

To onboard new clients quickly, the agency builds one complete flow as a template, then duplicates it for each new client. The duplicate gets its source accounts swapped and its flow renamed. This avoids rebuilding the same transformation and destination configuration from scratch each time.

#### Multi-store e-commerce reporting

A brand with five Shopify stores pulls all five into one data flow. Each store's orders are appended with a store identifier column. The appended table goes to Data Studio for a consolidated sales dashboard. Each store's raw data also goes to BigQuery as separate tables (one per store) for ad hoc queries. Because all five stores need the same refresh frequency and serve one reporting objective, a single flow is appropriate. If the number grows significantly, splitting into one flow per store avoids the risk of one store's disconnection affecting the others.

#### Cross-platform marketing dashboard

A marketing team pulls Google Ads, Facebook Ads, and LinkedIn Ads campaign data into one flow. The data is appended into a single campaign performance table with a platform identifier column. This table goes to Data Studio. An aggregate dataset (monthly spend and conversions by platform) goes to Google Sheets for the CMO's monthly review. The raw per-platform tables go to BigQuery. One flow, three destination types, each receiving the data in the structure it needs.

#### AI analysis with raw and prepared data

An analyst wants to use Claude to investigate why conversions dropped last month. One data flow contains Google Ads, Facebook Ads, and GA4 data. Each source is sent to Claude as a separate destination so the LLM can examine each platform individually. The appended cross-platform summary is sent as an additional destination for high-level questions. The analyst can ask Claude to compare platforms using the summary table and drill into a specific platform using the raw data, all from the same flow.

#### Data warehouse with normalized tables

A SaaS company pulls HubSpot deals, contacts, and companies into one data flow. Each entity goes to PostgreSQL as a separate table: hubspot\_deals, hubspot\_contacts, hubspot\_companies. A database view joins them on contact ID when a combined report is needed. The data flow does not attempt to flatten everything into one table, because the database handles relational queries natively. A separate flow pulls Stripe invoices and payments on a different schedule and loads them into stripe\_invoices and stripe\_payments.

<br>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coupler.io/getting-started/how-to-structure-data-in-coupler.io.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.