Skip to main content
diagram

​
Query Properties

NameTypeDefaultDescription
fromstringRequiredRoot entity type to query. Must match a valid entity type defined in the domain model (e.g., UserNeed, SystemRequirement)
whereobjectNoneFilter predicates applied to query results. Supports property comparisons, null checks, and composite AND/OR logic
expandarrayNoneExpand clause specifying navigation properties to load inline. Supports nested expansion for multi-level relationships
orderByarrayNoneOrder by clause with property paths and sort direction (asc/desc)
selectarrayNoneSelect clause projecting specific properties to return
parametersobjectNoneRuntime query context parameters controlling execution behavior

​
Query Execution Flow

  1. The query from clause is resolved against the metadata system to identify the target entity type
  2. Security checks verify the current user has read permission for the entity type
  3. The where clause predicates are split into Lucene-compatible queries and in-memory post-filters (see Query Splitting)
  4. Lucene queries execute against Polarion to fetch matching work items
  5. In-memory post-filters are applied to refine results
  6. Navigation properties specified in expand are loaded for each result entity
  7. Results are sorted per the orderBy clause
  8. The final result set is returned with entity metadata

​
Query Result Structure

Each entity returned by a query includes standard metadata fields:
FieldTypeDescription
$typestringEntity type name from the metadata system
entityTypeNamestringDomain model entity type name
idstringPolarion work item ID
titlestringWork item title
updateddatetimeLast modification timestamp
projectobjectProject foreign key reference

​
Query Parameters

Parameters control runtime query behavior. They are passed via the parameters property of the EntityQuery:
ParameterTypeDescription
revisionstringExecute query against a specific project baseline or revision
currentDocstringDocument ID for document filtering. Format: folder/name
currentDocConstraintstringEntity type or navigation property path for document scoping
explainbooleanEnable debug output showing query translation details

​
YAML Configuration Mapping

In the sheet configuration YAML, the sources[].query section maps directly to EntityQuery properties: 
sources:
  - id: requirements
    title: Requirements
    model: rtm
    query:
      from: UserNeed
      where: <WHERE>
      orderBy:
        - columnId: outlineNumber
          direction: asc
    constraints:
      applyCurrentDocumentTo: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: designRequirements
YAML PropertyEntityQuery PropertyDescription
sources[].query.fromfromRoot entity type
sources[].query.wherewhereFilter predicate (Lucene syntax or structured)
sources[].query.orderByorderBySort specification
sources[].expandexpandNavigation property expansion paths
sources[].constraintsparametersConverted to query parameters at runtime
sources[].modelMetadata resolutionMaps entity types to domain model definitions
The <WHERE> placeholder in YAML is replaced at runtime with the user’s current filter state from the toolbar.

​
Querying by ID

To query a specific entity by its Polarion work item ID: 
{
  "from": "UserNeed",
  "where": {
    "id": { "eq": "UN-001" }
  }
}

​
Null Checks

To filter entities where a property is or is not null: 
{
  "from": "SystemRequirement",
  "where": {
    "title": { "ne": null }
  }
}
The null equality check ("eq": null) finds entities where the property has no value. The null inequality check ("ne": null) finds entities where the property has a value.

​
Relationship Expansion Patterns

​
Many-to-One

Expand a single parent entity from a child: 
{
  "from": "Task",
  "expand": ["story"]
}

​
One-to-Many (Inverse)

Expand a collection of children from a parent: 
{
  "from": "Story",
  "expand": ["tasks"]
}

​
Many-to-Many

Expand through an association entity using two-level dot notation: 
{
  "from": "Story",
  "expand": ["requirements.requirement"]
}
The first segment (requirements) navigates to the association entities. The second segment (requirement) navigates through to the target entity.
Many-to-many expansions are bidirectional. Story -> requirements.requirement and Requirement -> stories.story both traverse the same association.

​
Complete YAML Example

sources:
  - id: rtm-source
    title: Requirements Traceability
    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
              - name: externalReferences
          - name: verificationTestCases
            title: Verification Tests
Sources: Code: QueryDataTest.java, PolarionQueryProcessor.java, QueryProcessor.java, QueryManager.tsx, constraints_currentDocument_downstream.template.yaml
Source Code
  • QueryDataTest.java
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/configurations/constraints_currentDocument_downstream.template.yaml
  • powersheet.yaml
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/configurations/whole_rtm.template.yaml
  • QueryProcessor.java