Skip to main content
diagram

​
Expand Configuration Properties

Each entry in the sources[].expand array accepts the following properties:
NameTypeDefaultDescription
namestringRequiredNavigation property name from the domain model relationships. Must match a direct.name or back.name value on the parent entity type.
titlestringNoneDisplay title for the expanded entity group in the sheet header row. If omitted, the navigation property name is used.
expandarrayNoneNested expand definitions for multi-level hierarchies. Each entry follows the same schema recursively.
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 domain 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.

​
Cardinality and Expansion Patterns

The relationship cardinality defined in the domain 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). Domain 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 domain 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.
Domain 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 domain model relationship definition.

​
Cardinality Summary

CardinalityModel DefinitionSource ExpandColumn BindingUI Behavior
N:1cardinality: many-to-one, direct.name: chapter- name: chapterchapter, chapter.titleSingle-value reference picker
1:NReverse of N:1, back.name: userNeeds- name: userNeedsuserNeedsChild rows (new sheet level)
M:Ncardinality: many-to-many, back.name: systemRequirements- name: systemRequirements then nested - name: systemRequirementsystemRequirements.systemRequirementMulti-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 PathRequired Expand
titleNone (direct property on root entity)
chapterexpand: [{ name: chapter }]
chapter.titleexpand: [{ name: chapter }]
systemRequirements.systemRequirementexpand: [{ name: systemRequirements, expand: [{ name: systemRequirement }] }]
systemRequirements.systemRequirement.titleSame 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 ExpandDot-Notation Query
- name: chapterchapter
- name: systemRequirements with nested - name: systemRequirementsystemRequirements.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 domain 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

FactorImpactRecommendation
Expand depthEach level adds query overheadKeep to 3-4 levels for responsive loading
Entity count per levelLarge collections at each level multiply data volumeUse predicates to filter root entities
Parallel branchesMultiple expands at the same level fetch independentlyCombine into views to show only needed branches
M:N associationsAssociation entities add an extra levelAccount 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:
  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.
  • 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 — domain 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
Source Code
  • PolarionQueryProcessor.java — query execution, constraint application, navigation expansion
  • QueryDataTest.java — expand integration tests for N:1, 1:N, and M:N relationships
  • QueryManager.tsx — client-side expand clause processing and dot-notation conversion
  • OrderByClause.java — property path validation used by expand resolution