> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Expand Clause

> The expand clause in Nextedy POWERSHEET defines which related entities are loaded inline when querying data from Siemens Polarion ALM.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/-WiVljKlDztH36bB/powersheet/diagrams/reference/query-api/expand-clause/diagram-1.svg?fit=max&auto=format&n=-WiVljKlDztH36bB&q=85&s=c2405496cf1b1de946a486a97298ade5" alt="diagram" style={{ width: "560px", maxWidth: "100%" }} width="560" height="280" data-path="powersheet/diagrams/reference/query-api/expand-clause/diagram-1.svg" />
</Frame>

## Expand Configuration Properties

Each entry in the `sources[].expand` array accepts the following properties:

| Name     | Type     | Default  | Description                                                                                                                                                                              |
| -------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`   | `string` | Required | Navigation property name from the [data model relationships](/powersheet/reference/data-model/relationships). Must match a `direct.name` or `back.name` value on the parent entity type. |
| `title`  | `string` | None     | Display title for the expanded entity group in the sheet header row. If omitted, the navigation property name is used.                                                                   |
| `expand` | `array`  | None     | Nested expand definitions for multi-level hierarchies. Each entry follows the same schema recursively.                                                                                   |

<Warning title="Required Property">
  The `name` property is mandatory. An expand entry without `name` is invalid and will prevent the sheet from loading related data.
</Warning>

## Expansion Path Syntax

Expansion paths follow navigation properties defined in the data model. Each `name` value must correspond to a relationship property on the parent entity type.

### Single-Level Expansion

Load direct related entities of the root entity type:

```yaml theme={null}
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: chapter
```

This loads the `Chapter` entity associated with each `UserNeed` via the many-to-one `chapter` navigation property.

### Multi-Level Expansion

Load deeper levels by nesting `expand` arrays inside each other:

```yaml theme={null}
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement
            expand:
              - name: designRequirements
                expand:
                  - name: designRequirement
```

Each nested `expand` resolves relative to its parent entity type.

### Parallel Branches

A single entity type can expand multiple navigation properties at the same level. List multiple entries in the same `expand` array:

```yaml theme={null}
expand:
  - name: systemRequirements
    expand:
      - name: systemRequirement
  - name: chapter
```

This loads both `SystemRequirement` entities (via the association) and the parent `Chapter` alongside each `UserNeed`.

## Cardinality and Expansion Patterns

The relationship cardinality defined in the data model determines the expand syntax and the resulting UI behavior in the sheet.

### Many-to-One (N:1)

Each child entity references exactly one parent. The navigation property is scalar (singular name).

**Data model relationship:**

```yaml theme={null}
relationships:
  - from: UserNeed
    to: Chapter
    cardinality: many-to-one
    storage: linkedWorkItems
    linkRole: parent
    direct:
      name: chapter
    back:
      name: userNeeds
```

**Source expand:**

```yaml theme={null}
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: chapter
```

**Column binding:**

```yaml theme={null}
columns:
  title:
    title: Title
    hasFocus: true
  chapter:
    title: Chapter
    display: title
    list:
      search:
        - title
  chapter.title:
    title: Chapter Title
    isReadOnly: true
```

* `chapter` renders as a single-value reference picker (scalar navigation property).
* `chapter.title` renders the referenced `Chapter` entity's title as a read-only column.

### One-to-Many (1:N)

A parent entity has a collection of children. This is the reverse side of a many-to-one relationship. The navigation property is plural (collection name).

**Source expand:**

```yaml theme={null}
sources:
  - id: chapters
    query:
      from: Chapter
    expand:
      - name: userNeeds
```

**Column binding:**

```yaml theme={null}
columns:
  title:
    title: Chapter
    hasFocus: true
  userNeeds:
    title: User Need
    hasFocus: true
```

* `userNeeds` expands into child rows in the sheet, creating a new hierarchical level.
* No dot-notation is needed for the expand itself; the expand directly opens the child level.

### Many-to-Many (M:N)

Many-to-many relationships use an **association entity** between the two types. The expansion requires two nested levels: first to the association collection, then through to the target entity.

<Info title="Verify in application">
  Many-to-many expansion patterns use an implicit association entity generated by the data model. The exact association entity structure depends on how the relationship is defined. Consult a domain expert when configuring complex M:N expansions for the first time.
</Info>

**Data model relationship:**

```yaml theme={null}
relationships:
  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements
```

**Source expand (two-level):**

```yaml theme={null}
sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement
```

**Column binding:**

```yaml theme={null}
columns:
  title:
    title: Title
    hasFocus: true
  systemRequirements.systemRequirement:
    title: System Requirement
    list:
      search:
        - objectId
        - title
      createNew: true
  systemRequirements.systemRequirement.title:
    title: SysReq Title
    hasFocus: true
```

* The source expand uses two levels: `systemRequirements` (association collection) followed by `systemRequirement` (target entity).
* Column binding uses dot-notation matching the expand path: `systemRequirements.systemRequirement`.
* The column renders as a multi-item reference picker.

<Tip title="Bidirectional Navigation">
  Many-to-many expansions are bidirectional. The same relationship can be navigated from either end:

  * `UserNeed` expands `systemRequirements.systemRequirement` to reach `SystemRequirement`
  * `SystemRequirement` expands `userNeeds.userNeed` to reach `UserNeed`

  The navigation property names come from the `direct.name` and `back.name` values in the data model relationship definition.
</Tip>

## Cardinality Summary

| Cardinality | Model Definition                                             | Source Expand                                                        | Column Binding                         | UI Behavior                   |
| ----------- | ------------------------------------------------------------ | -------------------------------------------------------------------- | -------------------------------------- | ----------------------------- |
| **N:1**     | `cardinality: many-to-one`, `direct.name: chapter`           | `- name: chapter`                                                    | `chapter`, `chapter.title`             | Single-value reference picker |
| **1:N**     | Reverse of N:1, `back.name: userNeeds`                       | `- name: userNeeds`                                                  | `userNeeds`                            | Child rows (new sheet level)  |
| **M:N**     | `cardinality: many-to-many`, `back.name: systemRequirements` | `- name: systemRequirements` then nested `- name: systemRequirement` | `systemRequirements.systemRequirement` | Multi-item reference picker   |

## Expand and Column Binding Alignment

Every column with a navigation [binding path](/powersheet/reference/sheet-config/binding-syntax) must have a corresponding expansion in the source configuration. The expand hierarchy must match the column binding path structure.

| Column Binding Path                          | Required Expand                                                                 |
| -------------------------------------------- | ------------------------------------------------------------------------------- |
| `title`                                      | None (direct property on root entity)                                           |
| `chapter`                                    | `expand: [{ name: chapter }]`                                                   |
| `chapter.title`                              | `expand: [{ name: chapter }]`                                                   |
| `systemRequirements.systemRequirement`       | `expand: [{ name: systemRequirements, expand: [{ name: systemRequirement }] }]` |
| `systemRequirements.systemRequirement.title` | Same as above                                                                   |

<Warning title="Missing Expand Causes Empty Columns">
  If a column references a navigation property that is not expanded in the source configuration, the column cells will remain empty. The related entities are simply not loaded and no error is shown.
</Warning>

## Query Execution

The expand clause is converted to dot-notation strings for query execution. Nested expand arrays are recursively flattened:

| YAML Expand                                                          | Dot-Notation Query                     |
| -------------------------------------------------------------------- | -------------------------------------- |
| `- name: chapter`                                                    | `chapter`                              |
| `- name: systemRequirements` with nested `- name: systemRequirement` | `systemRequirements.systemRequirement` |

This enables loading all related entities in a single server request rather than multiple round-trips. The query engine pre-fetches all expanded entities so the data is available when the sheet renders.

### Validation

Expand property paths are validated against the data model metadata at query time. If a `name` references a navigation property that does not exist on the entity type, the query fails with a validation error.

### Document Context

When a source defines `constraints.applyCurrentDocumentTo`, the expand clause operates within the document scope. Expanded entities are filtered to those associated with the current document context. See [Document Filtering](/powersheet/reference/query-api/document-filtering) for details.

## Performance Considerations

| Factor                 | Impact                                                 | Recommendation                                        |
| ---------------------- | ------------------------------------------------------ | ----------------------------------------------------- |
| Expand depth           | Each level adds query overhead                         | Keep to 3-4 levels for responsive loading             |
| Entity count per level | Large collections at each level multiply data volume   | Use predicates to filter root entities                |
| Parallel branches      | Multiple expands at the same level fetch independently | Combine into views to show only needed branches       |
| M:N associations       | Association entities add an extra level                | Account for the association level when planning depth |

<Info title="Verify in application">
  Maximum supported expand depth and performance characteristics depend on the Polarion server configuration and the number of entities at each level.
</Info>

## Complete YAML Example

A full requirements traceability matrix (RTM) configuration showing multi-level and parallel expand paths:

```yaml theme={null}
sources:
  - id: rtm-traceability
    title: Full RTM View
    query:
      from: UserNeed
    constraints:
      applyCurrentDocumentTo: UserNeed
    expand:
      - name: chapter
        title: Chapter
      - name: systemRequirements
        title: System Requirements
        expand:
          - name: systemRequirement
            expand:
              - name: designRequirements
                title: Design Requirements
                expand:
                  - name: designRequirement

columns:
  title:
    title: User Need
    width: 300
    hasFocus: true

  chapter:
    title: Chapter
    display: title
    list:
      search:
        - title

  chapter.title:
    title: Chapter Title
    isReadOnly: true

  systemRequirements.systemRequirement:
    title: System Requirement
    list:
      search:
        - objectId
        - title
      createNew: true

  systemRequirements.systemRequirement.title:
    title: SysReq Title
    width: 250

  systemRequirements.systemRequirement.designRequirements.designRequirement:
    title: Design Requirement
    list:
      search:
        - objectId
        - title

  systemRequirements.systemRequirement.designRequirements.designRequirement.title:
    title: DesReq Title
    width: 250
```

This configuration:

1. Queries `UserNeed` entities scoped to the current document.
2. Expands the parent `Chapter` (N:1) for each user need.
3. Expands `SystemRequirement` entities through the M:N association (`systemRequirements.systemRequirement`).
4. Further expands `DesignRequirement` entities through another M:N association at the next level.
5. Binds columns to display titles at each level with appropriate pickers.

## Related Pages

* [EntityQuery](/powersheet/reference/query-api/entity-query) -- top-level query structure containing the expand clause
* [Sources](/powersheet/reference/sheet-config/sources) -- source configuration including expand, constraints, and query settings
* [Binding Syntax](/powersheet/reference/sheet-config/binding-syntax) -- column binding paths that must align with expand paths
* [Relationships](/powersheet/reference/data-model/relationships) -- data model relationships defining available navigation properties
* [Navigation Directions](/powersheet/reference/data-model/navigation-directions) -- direct and back navigation direction semantics
* [Cardinality](/powersheet/reference/data-model/cardinality) -- relationship cardinality rules governing expand patterns
* [Document Filtering](/powersheet/reference/query-api/document-filtering) -- how document constraints interact with expanded data

***

<LastReviewed date="2026-07-02" />