Skip to main content
Narrative’s architecture is designed around a core principle: data stays in place. Rather than moving data to queries, queries move to data. This approach enables collaboration across organizations while maintaining data residency and security requirements.

​
The principle: Queries go to data

Traditional data sharing requires copying data between systems. Narrative inverts this model:
Traditional approachNarrative approach
Copy data to a shared locationLeave data in place
Queries run against copiesQueries run against source data
Data freshness depends on sync frequencyData is always current
Multiple copies increase security surfaceSingle source reduces exposure
When you query data through Narrative, the control plane sends query instructions to your data plane. The data plane executes the query locally and returns only the results.

​
What flows where

Understanding what crosses boundaries helps clarify the architecture:

​
From user to control plane

  • NQL query text
  • Authentication credentials
  • Request metadata

​
From control plane to data plane

  • Compiled SQL (transpiled for the target database)
  • Job metadata and parameters
  • Execution instructions

​
From data plane to control plane

  • Query results (for interactive queries)
  • Status updates and completion signals
  • Error messages and diagnostics

​
What never leaves the data plane

  • Raw source data
  • Intermediate query results
  • Materialized view contents (stored locally)

​
Query data flow

A typical query follows this path: 
User                Control Plane              Data Plane
  │                      │                         │
  │──── NQL Query ──────>│                         │
  │                      │                         │
  │                      │──── Compiled SQL ──────>│
  │                      │                         │
  │                      │                    ┌────┴────┐
  │                      │                    │ Execute │
  │                      │                    │  Query  │
  │                      │                    └────┬────┘
  │                      │                         │
  │                      │<──── Results ───────────│
  │                      │                         │
  │<──── Results ────────│                         │
  │                      │                         │
For interactive queries, results flow back through the control plane to the user. The control plane acts as a relay but doesn’t store or analyze the raw results.

​
Materialized view data flow

Materialized views follow a different pattern. Results stay in the data plane: 
Control Plane              Data Plane
     │                         │
     │──── Refresh Job ───────>│
     │                         │
     │                    ┌────┴────┐
     │                    │ Execute │
     │                    │  Query  │
     │                    └────┬────┘
     │                         │
     │                    ┌────┴────┐
     │                    │  Store  │
     │                    │ Results │
     │                    └────┬────┘
     │                         │
     │<──── Status ────────────│
     │                         │
The control plane receives only a completion status—never the actual data. Results are stored as a dataset within your data plane.

​
Cross-data-plane queries

When a query references data in multiple data planes, the control plane coordinates execution:
  1. Query decomposition — The control plane breaks the query into subqueries, one per data plane
  2. Parallel execution — Subqueries execute independently in each data plane
  3. Result coordination — Results are combined as needed, with the control plane coordinating data movement between planes
The specific data movement depends on the query. For joins across data planes, some data may need to move between planes for the join to complete. The control plane optimizes this movement to minimize data transfer.

​
Data collaboration flow

When you share data with a partner organization, they query your data through the same architecture:
  1. Partner submits NQL query referencing your dataset
  2. Control plane verifies their access grants
  3. Compiled query is sent to your data plane
  4. Your data plane executes and returns results
  5. Partner receives results through the control plane
Your raw data never leaves your data plane—only the query results authorized by your access grants.

​
Related content

Query Processing

The complete query lifecycle from submission to results

Data Planes

Where your data lives and queries execute

Control Plane

How queries are compiled and coordinated

Security Model

How this architecture protects your data