Access Rules

An access rule is a set of business rules that define how other organizations can access data within the Narrative platform. Access rules are a core primitive that give data owners fine-grained governance over their datasets.

What access rules control

Access rules let you define four key aspects of data access: Who can access your data. Specify which organizations can run queries against your datasets. You can grant access to specific companies, make data available to all platform participants, or restrict access to a closed group of partners. What data they can access. Control which records and fields are available through filtering conditions. You might expose only certain date ranges, geographic regions, or record types to different partners. How they can use it. Attach a query policy to control what a query can do with each column, such as allowing a join on email addresses without ever returning one. How much access costs. Set pricing for data access on a per-record basis. Prices can vary by record type, buyer, or any other criteria you define. For non-commercial collaborations, set the price to zero.

Why access rules exist

Without access rules, datasets in Narrative cannot be queried by other organizations. This is by design—data remains private by default, and you must explicitly create access rules to enable collaboration. This approach ensures:

Data owners stay in control. No one can access your data without your explicit permission
Flexible monetization. Charge different rates for different data or different buyers
Governance compliance. Audit exactly who has access to what data and under what terms

How access rules work

Access rules are defined using NQL (Narrative Query Language) and are enforced at query execution time. When another organization queries data you own:

Rule matching — The control plane identifies which access rules apply to the requested data
Permission verification — The query is checked against the access rule’s constraints
Price calculation — If the rule includes pricing, costs are calculated based on matching records
Query execution — Only records that pass the access rule’s filters are included in results

┌─────────────────────────────────────────────────────────────────┐
│                       Query Submitted                           │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                  Access Rules Evaluated                          │
│   • Which rules match the requested datasets?                   │
│   • Does the requester have permission?                          │
│   • What are the pricing terms?                                  │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                   ┌────────────┴────────────┐
                   │                         │
                   ▼                         ▼
        ┌──────────────────┐      ┌──────────────────┐
        │  Rules Match     │      │  No Match        │
        │  Query Executes  │      │  Query Fails     │
        └──────────────────┘      └──────────────────┘

Common use cases

Make data available to a specific partner

Grant a single organization access to your dataset:

-- Access rule granting Partner Corp access to customer segments
SELECT
    segment_id,
    segment_name,
    audience_size
FROM company."customer_segments"

Configure the rule to be visible only to the partner’s organization, and set pricing (or $0 for a data share).

Set different prices for different data

Create multiple access rules with different pricing tiers:

-- Premium access rule: recent data at higher price
SELECT
    user_id,
    event_type,
    event_timestamp
FROM company."user_events"
WHERE event_timestamp > CURRENT_DATE - INTERVAL '30' DAY

-- Standard access rule: older data at lower price
SELECT
    user_id,
    event_type,
    event_timestamp
FROM company."user_events"
WHERE event_timestamp <= CURRENT_DATE - INTERVAL '30' DAY

Restrict fields for certain buyers

Expose different columns to different partners by creating separate access rules:

-- Full access for premium partners
SELECT
    user_id,
    email,
    purchase_history,
    lifetime_value
FROM company."customers"

-- Limited access for standard partners (no PII)
SELECT
    user_id,
    purchase_history
FROM company."customers"

Share data at no cost for research, partnerships, or data exchanges:

SELECT
    anonymized_id,
    survey_responses,
    demographic_category
FROM company."research_data"

Set the price to $0 CPM when creating the rule.

Attribute mappings

When a dataset has Rosetta Stone mappings, the API returns which normalized attributes each access rule exposes. The mappings array on each access rule response tells you:

Which attributes are mapped — The Rosetta Stone attribute ID and name
Which properties are exposed — The dot-separated paths of attribute properties that the rule’s NQL query selects

For example, if a dataset column idValue is mapped to the identity.value property of an identity attribute, and the access rule’s NQL selects idValue, the response includes:

{
  "mappings": [
    {
      "attribute_id": 42,
      "attribute_name": "identity",
      "properties": ["id.value"]
    }
  ]
}

Only properties that are both mapped and selected by the access rule’s NQL query appear in the response. If a column is mapped to an attribute but the access rule does not select that column, the attribute is excluded. Scalar attributes (attributes without sub-properties) return an empty properties list.

Attribute mappings are filtered by the caller’s permissions. You only see mappings for attributes your organization has viewing access to.

Query policies

An access rule’s NQL decides which records and columns a partner can reach. A query policy decides what the partner can do with those columns once they reach them. Many collaborations need a column to be usable without being visible. A partner matching your audience against their CRM needs to join on email addresses, but you may not want any email address to appear in their results. A partner sizing segments needs to count your records, but not to export the list. Without a policy, the only control is the access rule’s NQL: leave a column out and the partner can’t return it, but they can’t join on it or count it either. A query policy separates those uses. A policy rules on three ways a query can use a column:

Projection — Returning the column’s value in the result, directly or through functions
Group by — Grouping rows by the column
Join — Using the column in a join condition

For each column and each usage, the policy can allow it, deny it, or restrict it to a list of functions. A restricted email might be returnable only as SHA2(email, 256), or only inside COUNT(DISTINCT …). A default rule covers every column the policy doesn’t name, and anything it leaves out is denied, so a policy starts closed and opens only what you list. A policy can also carry a join-required rule, which makes the access rule usable only in queries that join it to the querying company’s own data on keys you choose. This fits overlap and enrichment use cases, where your data should only ever answer questions about records the partner already has.

How enforcement works

Narrative checks the policy when it compiles a query, separately for each access rule the query reads. When a query breaks an access rule’s policy, Narrative leaves that access rule out of the query instead of failing it. The access rule contributes no rows, and the rest of the query runs as usual. This matters most for queries through Rosetta Stone, which can read many companies’ access rules at once. One access rule’s policy doesn’t block the others: a query that satisfies some policies and breaks others still returns rows from the access rules it satisfies. The query doesn’t report that an access rule was left out, so a partner who gets fewer rows than expected should check the access rule’s policy. Every access rule response in the API includes its query_policy, so partners can read the terms before they query. A policy governs what reaches the result, how results are grouped, and how data is joined. It does not restrict WHERE filters, so a partner can still filter on a column whose value they can’t return. If a partner must not be able to filter on a column at all, leave it out of the access rule’s NQL. For the full policy format, see the Query Policies reference. To attach one to an access rule, see Applying query policies.

Access rules and datasets

Every dataset can have multiple access rules, and a single access rule can reference multiple datasets. This flexibility supports complex governance scenarios:

One dataset, many rules — Different pricing tiers, different partner access levels
Many datasets, one rule — Bundle related datasets for partners who need comprehensive access

If a dataset has no access rules, it cannot be queried by other organizations. You always retain access to your own datasets regardless of access rules.

Access rules cannot be created for view datasets. Because a view dataset stores only a query definition rather than physical data, access must be controlled on the underlying datasets that the view references.

Pricing with access rules

Access rule pricing uses CPM (cost per thousand)—the cost per 1,000 records. When a query matches an access rule with pricing:

The number of matching records is counted
The total cost is calculated: (matching_records / 1000) × CPM
The buyer is charged and the data owner receives payment

Pricing is enforced at the data plane level, meaning costs are calculated based on actual query results, not estimates.

Data Planes

Where your data lives and access rules are enforced

Control Plane

How Narrative orchestrates permissions and query coordination

Security Model

The broader security architecture including access controls

How Rosetta Stone Works

Understand the attribute mappings returned by access rules

Query Policies Reference

The policy format, enforcement rules, and validation errors

Applying Query Policies

Attach, check, and remove a query policy

Access Rules API

Manage access rules programmatically

Name Conflict Errors

Resolve HTTP 409 errors when a name is already in use

Overview

Core Primitives

Rosetta Stone

NQL

Data Formats

Identifiers

Architecture

Workflows

Webhooks

Data Collaboration MCP Server

Model Inference

Security

Compliance

Data Activation

Apps

What access rules control

Why access rules exist

How access rules work

Common use cases

Make data available to a specific partner

Set different prices for different data

Restrict fields for certain buyers

Attribute mappings

Query policies

How enforcement works

Access rules and datasets

Pricing with access rules

Data Planes

Control Plane

Security Model

How Rosetta Stone Works

Query Policies Reference

Applying Query Policies

Access Rules API

Name Conflict Errors

​What access rules control

​Why access rules exist

​How access rules work

​Common use cases

​Make data available to a specific partner

​Set different prices for different data

​Restrict fields for certain buyers

​Enable non-commercial data sharing

​Attribute mappings

​Query policies

​How enforcement works

​Access rules and datasets

​Pricing with access rules

​Related content

Data Planes

Control Plane

Security Model

How Rosetta Stone Works

Query Policies Reference

Applying Query Policies

Access Rules API

Name Conflict Errors

What access rules control

Why access rules exist

How access rules work

Common use cases

Make data available to a specific partner

Set different prices for different data

Restrict fields for certain buyers

Enable non-commercial data sharing

Attribute mappings

Query policies

How enforcement works

Access rules and datasets

Pricing with access rules

Related content