> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrative.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Using Narrative ID
> Encode and translate identifiers for privacy-safe data collaboration
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:**
```sql theme={null}
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**
```sql theme={null}
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:
```sql theme={null}
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:
```sql theme={null}
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:**
```sql theme={null}
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**
```sql theme={null}
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:
Create Narrative IDs in your encoding space:
```sql theme={null}
SELECT
NARRATIVE_ID_ENCODE(email_sha256, 'your_org_key_id') AS narrative_id,
customer_segment,
lifetime_value
FROM your_company."customers"
```
Convert your Narrative IDs to the partner's encoding space:
```sql theme={null}
SELECT
NARRATIVE_ID_TRANSLATE(narrative_id, 'partner_key_id') AS partner_narrative_id,
customer_segment,
lifetime_value
FROM your_company."customers_encoded"
```
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:
```sql theme={null}
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:
```sql theme={null}
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:
```sql theme={null}
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 |
***
## Related content
Understand how Narrative ID works
Complete function syntax and parameters
Hashing fundamentals for privacy