Expand Clause - Nextedy Documentation

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. 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.
`query.where`	`object`	None	Subquery filter applied to this expand level only, independent of the current document. Supports the same operators as a root `query.where`, and dynamic values such as `() => context.parameters.<name>`. See Expand Subquery Filtering.

The name property is mandatory. An expand entry without name is invalid and will prevent the sheet from loading related data.

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:

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:

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:

expand:
  - name: systemRequirements
    expand:
      - name: systemRequirement
  - name: chapter

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

Expand Subquery Filtering

An expand node may carry a query.where that filters that level by its own attributes, independently of the current document. The where is applied to the level it is attached to; ancestor rows are not affected.

sources:
  - id: chapters
    query:
      from: Chapter
    expand:
      - name: requirements
        expand:
          - name: requirement
            query:
              where:
                targetSystem: iOS

A where can be attached to any expand node, whether the navigation is scalar (N:1) or a collection (1:N, M:N).
Multiple keys in a single where are combined with AND.
A value may be a dynamic expression. When it reads a URL parameter that has no value, the condition is dropped and the level expands unfiltered — see URL Parameters.

A subquery where on an expand level also constrains the reference picker for that level: only candidates satisfying the same filter (projected onto the picked entity along the binding path) are offered, so a picked item will not vanish on the next load.

Creating an item at a filtered expand level pre-fills the fields the subquery pins by equality, so the new row satisfies the filter it was created under and does not disappear on the next load. Only equality (type: Electrical or type: { eq: … }) seeds a default — fuzzy operators (contains, in, ne, or) do not, since they do not pin a single value. An explicit entityFactory default always wins over a filter-derived one, and a subquery scoped to the current document also creates the new item in that document.

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:

relationships:
  - from: UserNeed
    to: Chapter
    cardinality: many-to-one
    storage: linkedWorkItems
    linkRole: parent
    direct:
      name: chapter
    back:
      name: userNeeds

Source expand:

sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: chapter

Column binding:

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:

sources:
  - id: chapters
    query:
      from: Chapter
    expand:
      - name: userNeeds

Column binding:

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.

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.

Data model relationship:

relationships:
  - from: SystemRequirement
    to: UserNeed
    cardinality: many-to-many
    storage: linkedWorkItems
    linkRole: decomposes
    direct:
      name: userNeeds
    back:
      name: systemRequirements

Source expand (two-level):

sources:
  - id: user_needs
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement

Column binding:

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.

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.

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

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.

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

Maximum supported expand depth and performance characteristics depend on the Polarion server configuration and the number of entities at each level.

Complete YAML Example

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

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:

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

Server-Side Filtering — the concept behind expand subquery where: filtering each level on the server so only the matching slice loads
EntityQuery — top-level query structure containing the expand clause
Sources — source configuration including expand, constraints, and query settings
Binding Syntax — column binding paths that must align with expand paths
Relationships — data model relationships defining available navigation properties
Navigation Directions — direct and back navigation direction semantics
Cardinality — relationship cardinality rules governing expand patterns
Document Filtering — how document constraints interact with expanded data

​Expand Configuration Properties

​Expansion Path Syntax

​Single-Level Expansion

​Multi-Level Expansion

​Parallel Branches

​Expand Subquery Filtering

​Cardinality and Expansion Patterns

​Many-to-One (N:1)

​One-to-Many (1:N)

​Many-to-Many (M:N)

​Cardinality Summary

​Expand and Column Binding Alignment

​Query Execution

​Validation

​Document Context

​Performance Considerations

​Complete YAML Example

​Related Pages

Expand Configuration Properties

Expansion Path Syntax

Single-Level Expansion

Multi-Level Expansion

Parallel Branches

Expand Subquery Filtering

Cardinality and Expansion Patterns

Many-to-One (N:1)

One-to-Many (1:N)

Many-to-Many (M:N)

Cardinality Summary

Expand and Column Binding Alignment

Query Execution

Validation

Document Context

Performance Considerations

Complete YAML Example

Related Pages