Applying Query Policies

An access rule decides which of your columns a partner can reach. A query policy decides what they can do with each one: return it, group by it, join on it, or use it only inside functions you list. This guide shows how to write a policy, attach it to an access rule, check it, and remove it.

Query policies are managed through the API. You need an API key for the company that owns the access rule.

Prerequisites

An access rule your company owns, and its ID
An API key for your company
Familiarity with access rules

Select the columns in the access rule

A policy can only name columns the access rule’s NQL selects. A Rosetta Stone attribute counts only when the NQL selects it from _rosetta_stone. Selecting a dataset column that is mapped to the attribute is not enough. The examples in this guide use an access rule named customer_segments_ar, shared by a company with the slug acme:

SELECT
  company_data.customer_segments._rosetta_stone.email AS email,
  company_data.customer_segments.segment_id
FROM company_data.customer_segments

Once an access rule has a policy, partners can read a Rosetta Stone attribute through it only if the NQL selects that attribute from _rosetta_stone. Select every attribute partners need this way before you attach the policy.

Write the policy

Start from what partners should be able to do, and open only that. Any usage the policy doesn’t set for a column falls back to default, and any usage default doesn’t set is denied. Pick the pattern closest to your use case:

Join only
Hashed values only
Counts only

Partners can join on email addresses to enrich their own records, but never return one. The join-required rule means the access rule is usable only when joined to the partner’s own data on email.

{
  "default": {
    "projection": { "mode": "allow" },
    "group_by": { "mode": "allow" },
    "join": { "mode": "deny" }
  },
  "usage_rules": [
    {
      "attribute": "email",
      "projection": { "mode": "deny" },
      "group_by": { "mode": "deny" },
      "join": { "mode": "allow" }
    }
  ],
  "join_required_rule": {
    "match": [
      { "keys": [ { "attribute": "email", "form": "raw" } ] }
    ]
  }
}

A partner query that satisfies this policy:

SELECT
  c.customer_id,
  ar.segment_id
FROM acme."customer_segments_ar" ar
INNER JOIN company_data.crm c
  ON ar.email = c.email_address

Partners can return email addresses only as SHA-256 hashes, and join only on the hash. Other columns are unrestricted.

{
  "default": {
    "projection": { "mode": "allow" },
    "group_by": { "mode": "allow" },
    "join": { "mode": "allow" }
  },
  "usage_rules": [
    {
      "attribute": "email",
      "projection": { "mode": "restrict", "scalar_operators": ["SHA2"] },
      "group_by": { "mode": "deny" },
      "join": { "mode": "restrict", "scalar_operators": ["SHA2"] }
    }
  ]
}

A partner query that satisfies this policy:

SELECT
  SHA2(ar.email, 256) AS email_sha256,
  ar.segment_id
FROM acme."customer_segments_ar" ar

Partners can see each segment and count the email addresses in it, but can’t return an address or join on one.

{
  "default": {
    "projection": { "mode": "deny" }
  },
  "usage_rules": [
    {
      "attribute": "email",
      "projection": { "mode": "restrict", "aggregate_operators": ["COUNT", "COUNT_DISTINCT"] }
    },
    {
      "field": "segment_id",
      "projection": { "mode": "allow" },
      "group_by": { "mode": "allow" }
    }
  ]
}

A partner query that satisfies this policy:

SELECT
  ar.segment_id,
  COUNT(DISTINCT ar.email) AS emails
FROM acme."customer_segments_ar" ar
GROUP BY ar.segment_id

COUNT_DISTINCT is listed separately because COUNT alone does not permit COUNT(DISTINCT …). A policy sets no minimum group size, so a count can be as small as one.

Grouping by a column and returning it are separate usages. To return each segment next to its count, as the counts example does, segment_id needs projection set to allow as well as group_by.

A policy doesn’t restrict WHERE filters. A partner who can’t return email can still run WHERE ar.email = '[email protected]' to check whether an address is present. If partners must not filter on a column, leave it out of the access rule’s NQL.

For every option, including nested columns and external functions such as AI_COMPLETE, see the Query Policies reference.

Attach the policy

Send the policy as the body of PUT /v2/access-rules/{access_rule_id}/query-policy. This replaces any policy the access rule already has.

curl -X PUT "https://api.narrative.io/v2/access-rules/1234/query-policy" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "default": {
      "projection": { "mode": "deny" }
    },
    "usage_rules": [
      {
        "attribute": "email",
        "projection": { "mode": "restrict", "aggregate_operators": ["COUNT", "COUNT_DISTINCT"] }
      },
      {
        "field": "segment_id",
        "projection": { "mode": "allow" },
        "group_by": { "mode": "allow" }
      }
    ]
  }'

A 200 response returns the stored policy. The policy applies to every query compiled after that. To create an access rule with a policy already attached, add the same object as query_policy in the body of POST /v2/access-rules.

Fix validation errors

Narrative checks the policy against the access rule’s NQL before storing it. An invalid policy returns 400, leaves the current policy in place, and lists every problem in error_description:

{
  "error": "invalid_request",
  "error_description": "invalid query policy: usage_rules[attribute=email]: attribute 'email' is not exposed by this access rule"
}

The most common errors:

Message	Fix
`attribute 'email' is not exposed by this access rule`	Select the attribute from `_rosetta_stone` in the access rule’s NQL, or remove its rule
`attribute 'email' has more than one rule`	Merge the entries. A `field` entry for a column that renames an attribute counts as an entry for that attribute
`COUNT is an aggregate or external function, not a scalar one`	Move the function to `aggregate_operators` or `external_operators`
`attribute 'email' is a raw key, but its join rule is restrict`	Set the key’s `form` to the operator its `join` rule lists, or set `join` to `allow`

The Query Policies reference lists every message.

Check the policy

Read the stored policy back:

curl "https://api.narrative.io/v2/access-rules/1234/query-policy" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response is the policy object. A 404 means the access rule has no policy. Partners the access rule is shared with can call the same endpoint, and the policy also appears as query_policy in every v2 access rule response.

Change or remove the policy

To change the policy, send the complete new policy with PUT. There is no partial update: rules you leave out of the new policy are gone. To remove the policy, send DELETE:

curl -X DELETE "https://api.narrative.io/v2/access-rules/1234/query-policy" \
  -H "Authorization: Bearer YOUR_API_KEY"

A 204 response means the access rule has no policy, whether or not it had one before. Partners can then use every column the access rule selects without restriction.

When a partner’s query returns fewer rows

A query that breaks a policy doesn’t fail. Narrative leaves that access rule out of the query, so it contributes no rows, and the query returns rows from any other access rules it reads. A partner who expects rows from your access rule and gets none should compare their query against the policy:

Does the query return a column’s raw value where the policy only allows functions of it?
Does every function on a restricted column appear in the matching list?
If the policy has a join-required rule, does the query inner join the access rule directly to one of the partner’s own datasets on the required keys?

The Query Policies reference describes exactly how each query clause is checked.

Access Rules

Why query policies exist and how Narrative enforces them

Query Policies Reference

Every field, mode, and validation error

Joining Datasets

Write the joins a join-required rule expects

Set a Query Policy API

Request and response schemas

Overview

Platform

Data Ingestion

Data Planes

Querying with NQL

Data Collaboration

Identity Resolution

Data Activation

Audience Studio

Connectors

Connector APIs

Compliance

Rosetta Stone

Account Settings

Workflows

Webhooks

Data Collaboration MCP Server

Tools

SDKs

Prerequisites

Select the columns in the access rule

Write the policy

Attach the policy

Fix validation errors

Check the policy

Change or remove the policy

When a partner’s query returns fewer rows

Access Rules

Query Policies Reference

Joining Datasets

Set a Query Policy API

​Prerequisites

​Select the columns in the access rule

​Write the policy

​Attach the policy

​Fix validation errors

​Check the policy

​Change or remove the policy

​When a partner’s query returns fewer rows

​Related content

Access Rules

Query Policies Reference

Joining Datasets

Set a Query Policy API

Prerequisites

Select the columns in the access rule

Write the policy

Attach the policy

Fix validation errors

Check the policy

Change or remove the policy

When a partner’s query returns fewer rows

Related content