Mapping Multiple Fields to the Same Attribute in Narrative

This article explains how to configure multi-mapping in Narrative, a feature that allows you to assign multiple dataset columns—or multiple transformations of a single column—to the same Narrative attribute. It covers the motivation, core concepts, technical steps, and sample API requests.

1. Introduction

1.1 Overview

Traditionally, a single dataset column in Narrative mapped to exactly one attribute. This limitation created challenges for data structures that inherently have multiple representations for the same conceptual attribute (e.g., multiple dates, plaintext vs. hashed emails).

Multi-mapping removes that constraint by letting you:

• Map several columns to the same Narrative attribute.
• Treat different transformations of one column (e.g., hashed vs. plaintext) as separate entries under the same attribute.

1.2 Benefits

• Consolidated Analysis: Multiple columns describing the same concept (e.g., various phone numbers) can be viewed in a single attribute.
• Simplified Queries: No extra syntax is required in Narrative's query language (NQL) to access multiple columns mapped to the same attribute.
• Compatible with Current Billing: Row-based billing remains unchanged; if you generate more rows, your costs scale accordingly.

2. Use Cases

1. Multiple Timestamp Columns
   • Example: A dataset has both start_time and end_time but wants to treat them collectively as event_timestamp.
2. Hashed & Plaintext Fields
   • Example: email stored in plaintext, MD5, and SHA256 can all map to a single "email" attribute.
3. Multiple Related Identifiers
   • Example: Different types of user IDs (internal, external, hashed) mapped to a single "identifier" attribute to unify analysis.
4. Multiple Addresses or Phone Numbers
   • Example: home_address, billing_address, and shipping_address mapped as "address," enabling a combined view of address data.

3. Key Technical Details

3.1 Row Expansion and Billing

• Expansion: When multiple dataset columns map to one attribute, queries can "explode" these values into additional rows.
• Costs: Narrative's billing is per-output-row. If multiple values result in more total rows, the row count (and consequently the cost) will increase proportionally.

3.2 Private vs. Public Mappings

• Private Mappings: Visible only within your organization's account.
• Global (Public) Mappings: Created by Narrative administrators for cross-company use. Multiple global mappings can coexist with private mappings for the same attribute if each uses a distinct transformation.

3.3 Duplicate Values

• Platform Behavior: Narrative checks to avoid exact duplicate mappings (e.g., the same expression and attribute).
• Handling Redundancy: If different transformations ultimately produce the same output (e.g., identical hashed values), deduplication or filtering can be handled downstream (outside Narrative or in your query logic).

3.4 Backward Compatibility

• No Breaking Changes: Existing single mappings remain valid.
• Optional Adoption: You can add multi-mappings at any point without affecting existing dataset ingestion.

4. Configuration Steps

1. Identify Your Attribute
   • Determine which Narrative attribute (e.g., "email," "event_timestamp") should receive multiple mapped values.
2. Prepare the Expression
   • Use an ARRAY(...) construct for multi-value mappings, and optionally apply transformations (regex, hashing, trimming).
3. Specify the Path
   • Within the mapping object, define the path (e.g., "emails", "timestamp_list") to hold the array output.
4. Send Request via UI or API
   • UI: In Narrative, navigate to Dataset Details → Mappings → Create/Update.
   • API: Send a JSON payload to the relevant Narrative Mappings endpoint.

5. Example Mappings

The following JSON objects illustrate how to configure multi-mappings through the Narrative Mappings API. Modify them based on your dataset's column names and your desired transformations.

Two Timestamp Columns → event_timestamp

Scenario: A dataset has start_timestamp and end_timestamp; both should be recognized as "event_timestamp."

{
  "attribute_id": 2, // "event_timestamp"
  "dataset_id": 67890,
  "mapping": {
    "type": "object_mapping",
    "property_mappings": [
      {
        "path": "timestamp_list",
        "expression": "CASE WHEN start_timestamp IS NOT NULL THEN start_timestamp ELSE NULL END"
          
      }
    ]
  }
}

Then we map the end_timestamp to the same attribute:

{
  "attribute_id": 2, // "event_timestamp"
  "dataset_id": 67890,
  "mapping": {
    "type": "object_mapping",
    "property_mappings": [
      {
        "path": "timestamp_list",
        "expression": "CASE WHEN end_timestamp IS NOT NULL THEN end_timestamp ELSE NULL END"          
      }
    ]
  }
}

6. Operational Tips

1. UI vs. API
   • The UI offers a graphical approach: Dataset Details → Mappings.
   • The API is suitable for automated workflows or large-scale updates.
2. Duplicates
   • Different columns or transformations may occasionally produce the same value. Deduplication is optional and can be handled downstream.
3. Implications for Queries
   • Queries referencing the multi-mapped attribute will return multiple rows if there are multiple mapped values.
   • No special query syntax is required; Narrative automatically expands the mappings.
4. Costs and Performance
   • Each additional row generated by multi-mapping follows Narrative's standard row-based billing.
   • Performance impact is minimal aside from handling more output rows.

7. Summary

Multi-mapping provides a flexible mechanism to accommodate real-world data structures where a single conceptual attribute is represented in multiple ways. By configuring multiple columns or transformations within the same mapping, organizations gain more comprehensive query results without rewriting schemas or workflows. Billing remains row-based, and existing single-mapped datasets continue to function normally.

For further questions or advanced troubleshooting, consult the Narrative documentation or contact our support team.

Last Updated: April 10, 2025