> For the complete documentation index, see [llms.txt](https://knowledgebase.fabricdata.com/fabric-knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knowledgebase.fabricdata.com/fabric-knowledge-base/learn-the-application/destinations/preferences/bulk-data-ingest-nuvo/hierarchy-bulk-loading-documentation.md).

# Hierarchy bulk loading documentation

## Overview

The Hierarchy Bulk Loading feature introduces a seamless way to ingest a complete content hierarchy in a single operation. This feature allows you to import an entire franchise structure—from Franchise Collection down through Shows, Seasons, and Episodes—using a single CSV file.

This enhancement reduces the overall time taken to import entire hierarchies by over 90%, eliminating the need for multiple sequential imports and manual linking operations.

## Supported Hierarchy Structure

The Hierarchy Bulk Loading feature supports the following content structure:

```
Franchise Collection
└── Show
    └── Season
        └── Episode
```

## How It Works

### Automatic Parent-Child Linking

The bulk importer automatically establishes relationships between parent and child records during the import process. This is achieved through one of two linking methods:

#### Method 1: Reference ID Linking (Recommended)

Use a common reference ID to link child records to their parents. This method provides the most reliable linking mechanism.

Example:

```
Show: "Tech Tomorrow" (reference_id: "show-001")
└── Season 1 (linkage reference_id: "show-001")
    └── Episode 1 (linkage reference_id: "season-001")
```

#### Method 2: Title-Based Linking

Link records using parent titles and season numbers. This method is useful when reference IDs are not available.

Example:

```
Show: "Tech Tomorrow"
└── Season 1 (parent_show_title: "Tech Tomorrow")
    └── Episode 1 (parent_show_title: "Tech Tomorrow", parent_season_number: "1")
```

### Required Fields by Category

#### Franchise Collection

* `Display Title` - The title type to be set as Display Title
* `Title` - The Title of the Franchise
* `category` - Must be set to "Franchise Collection"

#### Show

* `Display Title` - The title type to be set as Display Title
* `Title` - The Title of the Show
* `category` - Must be set to "Show"
* One of the following:
  * `linkage_FranchiseCollection_meta_id` or
  * `manualLink_linkages_reference_id` (Franchise Collection reference) or
  * `manualLink_parent_franchise_title`

#### Season

* `Display Title` - The title type to be set as Display Title
* `Title` - The Title of the Season
* `category` - Must be set to "Season"
* One of the following:
  * `linkage_Show_meta_id` or
  * `manualLink_linkages_reference_id` (Show reference) or
  * `manualLink_parent_show_title`

#### Episode

* `Display Title` - The title type to be set as Display Title
* `Title` - The Title of the Episode
* `category` - Must be set to "Episode"
* `originalRunningOrder_position` - The episode number within the season
* One of the following:
  * `linkage_Season_meta_id` or
  * `manualLink_linkages_reference_id` (Season reference) or
  * `manualLink_parent_season_number` (used with parent\_show\_title)

## CSV Structure

### Column Overview

<table><thead><tr><th width="289.74609375">Column Name</th><th>Description</th><th>Required For</th><th>Example</th></tr></thead><tbody><tr><td><code>category</code></td><td>The type of record</td><td>All</td><td>"Show", "Season", "Episode"</td></tr><tr><td><code>Display Title</code></td><td>The Title type to be set as Display</td><td>All</td><td>"Title - Title (EN)"</td></tr><tr><td><code>Title</code></td><td>The Title of the Record</td><td>All</td><td>The Fabric Show</td></tr><tr><td><code>Primary ID</code></td><td>The ID Type to be used as the Primary ID for the Ingest</td><td>Optional (recommended)</td><td>"imdb_id"</td></tr><tr><td><code>Primary ID Value</code></td><td>The Primary ID Value of the Record</td><td>Optional (recommended)</td><td>"tt01010101"</td></tr><tr><td><code>manualLink_linkages_reference_id</code></td><td>Parent record's reference ID</td><td>Child records</td><td>"show-tech-tomorrow-001"</td></tr><tr><td><code>manualLink_parent_show_title</code></td><td>Parent show title (alternative to reference ID)</td><td>Seasons, Episodes</td><td>"Tech Tomorrow"</td></tr><tr><td><code>manualLink_parent_season_number</code></td><td>Parent season number</td><td>Episodes</td><td>"1"</td></tr><tr><td><code>originalRunningOrder_position</code></td><td>Episode/Storyline number</td><td>Episodes, Storylines</td><td>"1"</td></tr></tbody></table>

### Import Order

The importer will Ingest the records in the following order:

{% stepper %}
{% step %}

### Franchise Collections

Place Franchise Collection records first so they exist before Shows attempt to link to them.
{% endstep %}

{% step %}

### Shows

Add Show records after Franchise Collections.
{% endstep %}

{% step %}

### Seasons

Add Season records after their parent Shows.
{% endstep %}

{% step %}

### Episodes

Add Episode records after their parent Seasons.
{% endstep %}
{% endstepper %}

This ensures parent records are created before their children attempt to link to them.

## Best Practices

{% stepper %}
{% step %}

### Use Reference IDs

Always populate the `referenceIds_reference_id` field for each record and use `manualLink_linkages_reference_id` for linking. This provides the most reliable linking mechanism.
{% endstep %}

{% step %}

### Maintain Consistent Naming

Ensure titles are spelled consistently throughout the CSV, especially when using title-based linking.
{% endstep %}

{% step %}

### Order Your Data

Structure your CSV with parent records appearing before their children. The importer processes rows sequentially.
{% endstep %}

{% step %}

### Validate Before Import

Review your CSV to ensure:

* All required fields are populated
* Reference IDs are unique
* Parent records exist before child records reference them
* Category values are spelled correctly
  {% endstep %}

{% step %}

### Use Episode Numbering

Always include `originalRunningOrder_position` for Episodes to maintain proper episode ordering within seasons.
{% endstep %}
{% endstepper %}

## Example Scenarios

### Scenario 1: New Franchise with Complete Hierarchy

Import a brand new franchise with all shows, seasons, and episodes in one operation.

Use Case: Launching a new content library with complete metadata.

### Scenario 2: Adding Seasons to Existing Show

Import new seasons and episodes for an existing show by referencing the show's existing `meta_id` or `reference_id`.

Use Case: Adding new season releases to your catalog.

### Scenario 3: Backfilling Episode Metadata

Import episodes for existing seasons with detailed metadata, synopses, and credits.

Use Case: Enriching existing catalog with additional information.

## Troubleshooting

<details>

<summary>"Parent record not found" Error</summary>

Cause: The child record references a parent that doesn't has not made it into the catalog yet or isn't in the sheet.

Solution:

* Ensure parent records appear in the CSV
* Verify the reference ID or title matches exactly
* Check for typos in linking fields

</details>

<details>

<summary>"Required field missing" Error</summary>

Cause: A mandatory field for the record category is empty.

Solution:

* Review the Required Fields section above
* Ensure at least one linking method is populated for child records

</details>

<details>

<summary>"Duplicate reference ID" Error</summary>

Cause: Multiple records use the same `referenceIds_reference_id`.

Solution:

* Ensure each record has a unique reference ID
* Use a naming convention to prevent duplicates (e.g., "show-", "season-", "episode-" prefixes)

</details>

## Performance Benefits

| Traditional Method             | Hierarchy Bulk Loading           |
| ------------------------------ | -------------------------------- |
| 5 separate import operations   | 1 combined import operation      |
| Manual linking between imports | Automatic parent-child linking   |
| \~2-3 hours for 100 episodes   | \~10-15 minutes for 100 episodes |

## Limitations

* Maximum file size: 50MB
* Maximum rows per import: 10,000
* Parent records must be processed before children in the same import
* Cannot update existing records (import creates new records only)

## Sample Data

For a complete working example, download the sample CSV file: [the-fabric-franchise-sample.csv](#)

## Support

For additional assistance with Hierarchy Bulk Loading:

* Review the [Bulk Import Guide](#)
* Contact your Technical Account Manager
* Submit a support ticket through the [Service Desk](#)