Skip to main content
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:
ParameterTypeDescription
raw_identifierstringThe clear text identifier to encode (email, hashed email, phone, etc.)
key_idstringYour 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:
ParameterTypeDescription
narrative_idstringAn existing Narrative ID to translate
target_key_idstringThe 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:
1

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"
2

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"
3

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 TypeNormalization
EmailLOWER(TRIM(email))
PhoneE.164 format or NORMALIZE_PHONE()
Hashed emailAlready 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 CaseApproach
General pseudonymizationUse standard hashing (SHA-256)
Cross-partner collaborationUse Narrative ID encoding
Internal data processingEither, depending on downstream use
Regulatory complianceNarrative ID provides additional isolation

​
Troubleshooting

IssuePossible CauseSolution
No matches after translationIdentifiers not normalized consistentlyEnsure both partners normalize the same way before encoding
Invalid key_id errorIncorrect encoding key IDVerify the key ID with your Narrative administrator
Translation returns NULLSource Narrative ID is invalidCheck that the source was properly encoded

​
Related content

Narrative ID Concepts

Understand how Narrative ID works

NQL Functions Reference

Complete function syntax and parameters

Data Pseudonymization

Hashing fundamentals for privacy