Skip to main content
diagram

​
Expand Configuration Properties

The expand clause is configured in the sources[].expand array of the sheet configuration YAML:
NameTypeDefaultDescription
namestringRequiredNavigation property name to expand, as defined in the domain model relationships
titlestringNoneDisplay title for the expanded entity group in the sheet header
expandarrayNoneNested expand definitions for multi-level relationships

​
Expansion Path Syntax

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

​
Single-Level Expansion

Load direct children of the root entity: 
sources:
  - id: requirements
    model: rtm
    query:
      from: UserNeed
    expand:
      - name: systemRequirements

​
Multi-Level Expansion

Load grandchildren and deeper by nesting expand arrays: 
sources:
  - id: requirements
    model: rtm
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: designRequirements
            expand:
              - name: verificationTestCases

​
Parallel Branches

A single entity type can expand multiple navigation properties at the same level: 
expand:
  - name: systemRequirements
    expand:
      - name: designRequirements
      - name: verificationTestCases

​
Relationship Types and Expansion

RelationshipExpansion PatternExample
Many-to-oneSingle name propertystory (Task expands to its parent Story)
One-to-manySingle name collectiontasks (Story expands to child Tasks)
Many-to-manyTwo-level dot notation: association.targetrequirements.requirement (Story through association to Requirement)

​
Many-to-One Expansion

Expand a single parent from a child entity: 
expand:
  - name: story

​
One-to-Many Expansion

Expand a collection of children from a parent entity: 
expand:
  - name: tasks

​
Many-to-Many Expansion

Many-to-many relationships use association entities. The expansion navigates first to the association, then through to the target: 
expand:
  - name: requirements
    expand:
      - name: requirement
This corresponds to the dot-notation path requirements.requirement in column binding paths.
Many-to-many expansions are bidirectional. The same relationship can be navigated from either end:
  • Story -> requirements.requirement -> Requirement
  • Requirement -> stories.story -> Story

​
Expand and Column Binding Alignment

Every column with a navigation binding path must have a corresponding expansion path in the sources configuration. The expand hierarchy must match the column binding path structure.
Column Binding PathRequired Expand
titleNone (direct property)
systemRequirements.systemRequirement.titleexpand: [{ name: systemRequirements }]
systemRequirements.systemRequirement.designRequirements.designRequirement.titleNested: systemRequirements > designRequirements
If a column references a navigation property that is not expanded in the sources configuration, the column cells will remain empty because the related entities are not loaded.

​
Performance Considerations

  • Each expand level adds query overhead. Deep expansions (4+ levels) may impact load time.
  • Expand paths are converted to dot-notation strings for query execution, enabling related entities to be loaded in a single server request rather than multiple round-trips.
  • The query engine pre-fetches all expanded entities, so all data is available for display when the sheet renders.
The maximum supported expand depth and performance characteristics depend on the Polarion server configuration and the number of entities at each level.

​
Complete YAML Example

sources:
  - id: rtm-full
    title: Full RTM View
    model: rtm
    query:
      from: UserNeed
      where: <WHERE>
    constraints:
      applyCurrentDocumentTo: UserNeed
    expand:
      - name: systemRequirements
        title: System Requirements
        expand:
          - name: designRequirements
            title: Design Requirements
            expand:
              - name: verificationTestCases
                title: Verification Tests
              - name: externalReferences
                title: External References
          - name: verificationTestCases
            title: SR Verification Tests

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

  systemRequirements.systemRequirement.title:
    title: System Requirement
    width: 250

  systemRequirements.systemRequirement.designRequirements.designRequirement.title:
    title: Design Requirement
    width: 250

  systemRequirements.systemRequirement.designRequirements.designRequirement.verificationTestCases.verificationTestCase:
    title: DR Verification
    width: 180
    multiItem: true

  systemRequirements.systemRequirement.verificationTestCases.verificationTestCase:
    title: SR Verification
    width: 180
    multiItem: true
  • EntityQuery — top-level query containing the expand clause
  • Sources — YAML configuration for data sources and expansion
  • Binding Syntax — column binding paths that correspond to expand paths
  • Relationships — domain model relationships that define available navigation properties
  • Navigation Directions — upstream/downstream expansion direction
Sources: Code: ExpandClause.java, QueryDataTest.java, PolarionQueryProcessor.java, test-viewModel.ts, constraints_currentDocument_downstream.template.yaml
Source Code
  • PolarionQueryProcessor.java
  • QueryDataTest.java
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/configurations/constraints_currentDocument_downstream.template.yaml
  • prod-powersheet-src/com.nextedy.powersheet.client/ltc-repo/__tests__/test-viewModel.ts
  • prod-powersheet-src/com.nextedy.powersheet.client/ltc-repo/packages/common/types/domain/document.ts