Using Narrative ID - Narrative I/O Knowledge Base

This guide walks through the practical steps for working with Narrative IDs—encoding your identifiers and translating them for partner collaboration.

Prerequisites

Before working with Narrative IDs, ensure you have:

Access to the Narrative platform with appropriate permissions
An encoding key ID for your organization’s encoding space
Partner encoding key IDs if you need to translate for collaboration

Encoding identifiers

Encoding converts a clear text identifier (such as an email or hashed email) into a Narrative ID within your organization’s encoding space.

When to encode

Encode identifiers when you want to:

Share data with partners without exposing raw identifiers
Create privacy-safe join keys for cross-organization matching
Prepare data for collaboration workflows

Using NARRATIVE_ID_ENCODE

The NARRATIVE_ID_ENCODE function creates a Narrative ID from a clear text identifier. Syntax:

NARRATIVE_ID_ENCODE(raw_identifier, key_id)

Parameters:

Parameter	Type	Description
`raw_identifier`	string	The clear text identifier to encode (email, hashed email, phone, etc.)
`key_id`	string	Your organization’s encoding key ID

Example: Encoding email addresses

SELECT
  NARRATIVE_ID_ENCODE(LOWER(TRIM(email)), 'your_org_key_id') AS narrative_id,
  event_timestamp,
  event_type
FROM your_company."customer_events"

Example: Encoding already-hashed identifiers If your data already contains hashed emails (SHA-256), you can still encode them:

SELECT
  NARRATIVE_ID_ENCODE(email_sha256, 'your_org_key_id') AS narrative_id,
  purchase_amount,
  purchase_date
FROM your_company."transactions"

Always normalize identifiers before encoding. For emails, use LOWER(TRIM(email)) to ensure consistent matching.

Creating a dataset with Narrative IDs

To prepare a dataset for sharing, encode the identifiers during a materialized view creation:

CREATE MATERIALIZED VIEW your_company."customer_data_encoded" AS
SELECT
  NARRATIVE_ID_ENCODE(LOWER(TRIM(email)), 'your_org_key_id') AS narrative_id,
  age_bracket,
  region,
  interest_categories,
  event_timestamp
FROM your_company."raw_customer_data"

Translating between partners

Translation converts a Narrative ID from one partner’s encoding space to another, enabling cross-organization matching without exposing the underlying identifiers.

When to translate

Translate Narrative IDs when you need to:

Share data with a specific partner for matching
Query across datasets from different partners
Enable a partner to join your data with their own

Using NARRATIVE_ID_TRANSLATE

The NARRATIVE_ID_TRANSLATE function converts a Narrative ID from its current encoding space to a target partner’s encoding space. Syntax:

NARRATIVE_ID_TRANSLATE(narrative_id, target_key_id)

Parameters:

Parameter	Type	Description
`narrative_id`	string	An existing Narrative ID to translate
`target_key_id`	string	The encoding key ID for the target partner’s encoding space

Example: Translating for a partner

SELECT
  NARRATIVE_ID_TRANSLATE(narrative_id, 'partner_b_key_id') AS partner_b_narrative_id,
  demographic_segment,
  activity_score
FROM your_company."audience_segments"

Partner collaboration workflow

Here’s a typical workflow for sharing data with a partner:

Encode your identifiers

Create Narrative IDs in your encoding space:

SELECT
  NARRATIVE_ID_ENCODE(email_sha256, 'your_org_key_id') AS narrative_id,
  customer_segment,
  lifetime_value
FROM your_company."customers"

Translate for your partner

Convert your Narrative IDs to the partner’s encoding space:

SELECT
  NARRATIVE_ID_TRANSLATE(narrative_id, 'partner_key_id') AS partner_narrative_id,
  customer_segment,
  lifetime_value
FROM your_company."customers_encoded"

Share the translated data

The partner receives data with Narrative IDs in their encoding space. They can now join against their own data using their Narrative IDs.

Joining across partner datasets

When querying data that spans multiple partners, use translation in the join condition:

SELECT
  a.campaign_name,
  a.impressions,
  b.conversion_value
FROM partner_a."ad_impressions" a
JOIN partner_b."conversions" b
  ON NARRATIVE_ID_TRANSLATE(a.narrative_id, 'partner_b_key_id') = b.narrative_id
WHERE a.event_timestamp >= '2024-01-01'

Working with match tables

Match tables are pre-generated lookup tables that pair Narrative IDs with clear text identifiers, enabling offline workflows.

What match tables provide

A static mapping between your clear text identifiers and their Narrative IDs
The ability to work with Narrative IDs outside the Narrative platform
Faster lookups for high-volume processing

Generating a match table

Create a match table by selecting both the raw identifier and its encoded Narrative ID:

CREATE MATERIALIZED VIEW your_company."identity_match_table" AS
SELECT DISTINCT
  email_sha256 AS clear_text_identifier,
  NARRATIVE_ID_ENCODE(email_sha256, 'your_org_key_id') AS narrative_id
FROM your_company."customer_identities"

Using match tables

Once generated, you can export the match table for use in external systems:

SELECT
  clear_text_identifier,
  narrative_id
FROM your_company."identity_match_table"

Match tables contain mappings between clear text identifiers and Narrative IDs. Handle them with the same security precautions as any sensitive data.

Best practices

Normalization before encoding

Always normalize identifiers before encoding to ensure consistent matching:

Identifier Type	Normalization
Email	`LOWER(TRIM(email))`
Phone	E.164 format or `NORMALIZE_PHONE()`
Hashed email	Already normalized (ensure consistent hashing upstream)

Performance considerations

Encode once, translate as needed: Encode your raw identifiers once and store the Narrative IDs. Translate only when preparing data for a specific partner
Use materialized views: For frequently accessed data, encode identifiers in a materialized view rather than at query time
Batch translations: When sharing with multiple partners, consider creating partner-specific views

Encoding vs. hashing

Use Case	Approach
General pseudonymization	Use standard hashing (SHA-256)
Cross-partner collaboration	Use Narrative ID encoding
Internal data processing	Either, depending on downstream use
Regulatory compliance	Narrative ID provides additional isolation

Troubleshooting

Issue	Possible Cause	Solution
No matches after translation	Identifiers not normalized consistently	Ensure both partners normalize the same way before encoding
Invalid key_id error	Incorrect encoding key ID	Verify the key ID with your Narrative administrator
Translation returns NULL	Source Narrative ID is invalid	Check that the source was properly encoded

Narrative ID Concepts

Understand how Narrative ID works

NQL Functions Reference

Complete function syntax and parameters

Data Pseudonymization

Hashing fundamentals for privacy

​Prerequisites

​Encoding identifiers

​When to encode

​Using NARRATIVE_ID_ENCODE

​Creating a dataset with Narrative IDs

​Translating between partners

​When to translate

​Using NARRATIVE_ID_TRANSLATE

​Partner collaboration workflow

​Joining across partner datasets

​Working with match tables

​What match tables provide

​Generating a match table

​Using match tables

​Best practices

​Normalization before encoding

​Performance considerations

​Encoding vs. hashing

​Troubleshooting

​Related content

Narrative ID Concepts

NQL Functions Reference

Data Pseudonymization

Prerequisites

Encoding identifiers

When to encode

Using NARRATIVE_ID_ENCODE

Creating a dataset with Narrative IDs

Translating between partners

When to translate

Using NARRATIVE_ID_TRANSLATE

Partner collaboration workflow

Joining across partner datasets

Working with match tables

What match tables provide

Generating a match table

Using match tables

Best practices

Normalization before encoding

Performance considerations

Encoding vs. hashing

Troubleshooting

Related content