Federation

Most teams run a single workspace. Once you have several — split by team, client, or environment — questions start to span them. Federation is the answer.

Federation lets you ask a question that requires data from multiple workspaces and get one unified answer. No manual export, no cross-tool join.

When to use it

• Consultancy managing multiple client workspaces — “How is retention across all my clients this month?”
• Multi-brand company with separate workspaces per brand — “Which brand has the fastest-growing paid channel?”
• Multi-environment setup — prod vs staging vs sandbox — “Does staging have the same signup pattern as prod?”
• Distributed team where each region owns its own workspace — “Compare EU vs US ops metrics.”

If you only have one workspace, skip this page.

How it works

You declare one of your workspaces as the Federation root. The root gets access (read-only by default) to the other workspaces you authorize. When you ask a question in the root workspace:

• The Agent identifies which tables are federated (from other workspaces) vs local.
• It issues separate queries per workspace, in parallel.
• It joins / unions the results in the root workspace.
• It returns one answer.

From your seat, it feels like one workspace. Under the hood, each query still runs inside its source workspace’s own database — no cross-database row replication.

Setup

All on Max plan or above. In the root workspace:

1. Settings → Federation → + Add workspace.
2. Enter the target workspace’s ID (from the target’s Settings → About).
3. The target workspace’s Owner gets a federation request. They approve + choose what to share:
   • Everything — all tables.
   • Specific schemas — e.g., only public.*, not integrations.*.
   • Specific tables — fine-grained list.
   • Read-only (default) vs read-write (rare; use with care).
4. Approved. Federated tables appear in the root workspace, prefixed by workspace name: acme_prod.users, acme_stage.users.

Querying across workspaces

Three common patterns:

UNION across environments

> Compare signup count this week in prod, staging, and sandbox.

The Agent:

1. Runs SELECT count(*) FROM users WHERE created_at > now() - interval '7 days' in each federated workspace.
2. Returns a three-row table.

JOIN across workspaces

When two workspaces have complementary data (common in consultancies where a shared clients table lives in the root and per-client data lives in sub-workspaces):

> Join clients.name from the root with last-month revenue from each client's workspace.

Cross-workspace joins use a logical protocol — not a physical PG Foreign Data Wrapper — so they work even when the workspaces run on different Tablize regions.

Aggregate with attribution

> Total revenue across all client workspaces last month, broken down by client.

The Agent fans out, aggregates locally, returns a unified table. Sorting and filtering happen in the root.

Permissions

A federated workspace is read-only by default. The root can only query; it cannot insert, update, or drop.

You can grant write access per target — useful for an ops workspace that manages configs across brands — but the target’s Owner has to approve explicitly, and every write is audit-logged in both workspaces.

Performance

Federated queries run in parallel, so the wall-clock time is the slowest child query. Small joins across a handful of workspaces are fast (sub-second). Large joins (millions of rows from three workspaces) are measured in seconds.

For truly heavy cross-workspace analytics, consider a warehouse pattern: set up a Snowflake or BigQuery workspace as a data destination, have each source workspace ship into it, query the warehouse directly. Federation is for live-join use cases, not heavy batch.

Limits

Plan	Federated workspaces (inbound)	Federation root (outbound)
Plus	—	—
Pro	—	—
Max	Up to 50	Up to 10 roots
Enterprise	Unlimited	Unlimited

Hitting these limits is rare outside of multi-region enterprise setups.

Security

• Mutual TLS between workspaces. Every federated query carries a workspace-scoped token.
• Audit log entries in both workspaces for every query.
• Per-table / per-schema share scope — the target decides what’s visible. The root can’t query tables outside the declared scope.
• Revocation is immediate. The target’s Owner can revoke access at any time; in-flight queries return an error, not stale data.

Revoking federation

In the target workspace: Settings → Federation → find the root → Revoke.

The root workspace’s federated tables become unreadable immediately. Any Reports / Dashboards / Watches in the root that depended on revoked tables show a clear “connection revoked” error — they don’t silently break.

Common gotchas

• “Column not found” after federation. The target workspace changed its schema. Federation doesn’t propagate schema changes automatically — ask the Agent to re-introspect the federated workspace.
• Queries timing out. One of the children is slow. The federation dashboard shows per-workspace latency; usually a missing index in one of the targets.
• Stale data. Federation reads live by default, but heavy reads on the target can cause replication lag if the target uses a read replica. Fix: query the primary directly, or accept the lag.
• Federation inside a federation. Currently unsupported. You can’t federate A into B, and B into C, and query A from C. Roots have to be direct.

Next steps

• Workspaces & roles — before federating, make sure each workspace’s roles are set up.
• Billing & tokens — Federation is a Max plan feature.