EntityQuery - Nextedy Documentation

Query Properties

Name	Type	Default	Description
`from`	`string`	Required	Root entity type to query. Must match a valid entity type defined in the data model (e.g., `UserNeed`, `SystemRequirement`, `Hazard`).
`where`	`object`	`None`	Filter predicates applied to query results. Supports property comparisons and composite AND/OR logic.
`expand`	`array`	`None`	Expand clause specifying navigation properties to load inline. Supports nested expansion for multi-level relationships.
`orderBy`	`array`	`None`	Sorting clause with property paths and sort direction. Ascending is the default; append `desc` for descending order.

EntityQuery does not support a select clause for projecting specific properties. All properties defined for the entity type in the data model are returned automatically.

The `from` Clause

The from clause specifies the root entity type for the query. The value must exactly match an entity type name defined in the domainModelTypes section of the data model YAML. Entity type names use PascalCase.

sources:
  - id: user_needs
    query:
      from: UserNeed

The server resolves the from value against the metadata system to locate the entity type definition, including its mapped Polarion work item type, properties, and available navigation properties. If the entity type is not found in the metadata registry, the query fails with a validation error. Common entity types (using the standard RTM example model):

Entity Type	Polarion Type	Typical Use
`UserNeed`	`user_need`	Top-level requirements
`SystemRequirement`	`sys_req`	System-level requirements
`DesignRequirement`	`des_req`	Design-level requirements
`Hazard`	`hazard`	Risk analysis entities
`RiskControl`	`risk_control`	Risk mitigation measures
`Chapter`	`heading`	Document structure headings

For the complete list of entity type properties and Polarion type mappings, see Data Model Types and Polarion Type Mapping.

The `where` Clause

The where clause defines filter predicates that restrict the result set. Predicates are split during execution into two categories:

Lucene-compatible predicates — translated to Polarion Lucene queries and executed server-side for performance
In-memory post-filters — complex predicates that cannot be expressed in Lucene, applied after the initial fetch

This splitting is transparent to the query author. See Predicates for the full predicate syntax and Query Splitting for details on how predicates are categorized.

sources:
  - id: active_requirements
    query:
      from: SystemRequirement
      where:
        status:
          ne: "rejected"

Filtering entities by null presence (using eq: null or ne: null to find entities where a property is or is not null) is not currently supported. The null check predicate is not functional in the current release and should not be used in production sheet configurations. To filter on field presence, use an explicit value comparison (for example, ne: "" for non-empty strings) or apply the filter via a downstream post-processing step. This limitation will be addressed in a future release.

For composite filtering with AND/OR logic, see the Predicates reference.

The `expand` Clause

The expand clause specifies which navigation properties to load inline with the query results. Navigation properties represent relationships between entity types defined in the data model. The expand syntax differs based on the relationship cardinality.

Many-to-One (N:1) Expansion

For many-to-one relationships, the expand loads a single related entity. Uses the direct navigation property name from the relationship definition.

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

This loads the parent Chapter for each UserNeed. In the data model, the relationship defines direct.name: chapter on the many side.

One-to-Many (1:N) Expansion

For one-to-many relationships (the reverse of N:1), the expand loads a collection of child entities. Uses the back navigation property name.

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

This loads all child UserNeed entities for each Chapter. In the sheet, these appear as expandable child rows creating a new hierarchy level.

Many-to-Many (M:N) Expansion

Many-to-many relationships require a two-level expand that traverses through an association entity to reach the target entity.

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

The first level (systemRequirements) navigates to the association entities. The second level (systemRequirement) navigates from each association to the actual target SystemRequirement entity. This two-level pattern is required because the data model represents M:N links through an intermediate association. For complete expand syntax including nested multi-level expansion, see Expand Clause.

The `orderBy` Clause

The orderBy clause defines the sort order for query results. Each item specifies a property path and an optional sort direction.

Property	Type	Default	Description
Property path	`string`	Required	Dot-notation path to the property to sort by (e.g., `title`, `severity`, `chapter.title`).
Sort direction	`string`	`asc`	Append `desc` after the property path for descending order. Ascending is the default when no direction is specified.

sources:
  - id: sorted_requirements
    query:
      from: SystemRequirement
      orderBy:
        - severity desc
        - title

Property path syntax supports both direct properties and navigation paths using dot notation. The path is validated against the entity type metadata to ensure it references a valid property. The orderBy clause in the source configuration maps to the sortBy property in the sheet configuration, which uses a slightly different format:

sortBy:
  - id: severity
    direction: desc
  - id: title
    direction: asc

All property paths in the orderBy clause are validated against the entity type metadata during query construction. If a property path references a non-existent property, the query returns a validation error. Use property names exactly as defined in the data model.

Query Execution Flow

The server API processes an EntityQuery through the following stages:

Metadata resolution — The from clause is resolved against the metadata registry to identify the target entity type, its Polarion work item type mapping, and available properties.
Security enforcement — The server verifies the current user has read permission for the entity type. If the entity type is not readable, the query fails immediately.
Predicate splitting — The where clause predicates are analyzed and split into Lucene-compatible server queries and in-memory post-filters.
Document pre-filtering — If document-level predicates exist in the where clause, documents are pre-resolved to narrow the work item query scope.
Lucene query execution — Lucene-compatible predicates are translated and executed against Polarion to fetch matching work items.
Post-filtering — In-memory filters are applied to the fetched results to handle predicates that cannot be expressed in Lucene.
Constraint application — Data model constraints and project scoping rules are enforced on the result set.
Navigation property expansion — Properties specified in the expand clause are loaded for each result entity, following the relationship paths defined in the data model.
Sorting — Results are ordered per the orderBy clause.
Result assembly — The final result set is returned with entity metadata.

Query Result Structure

Each entity returned by an EntityQuery includes standard metadata fields alongside the data model properties:

Field	Type	Description
`$type`	`string`	Fully qualified entity type name from the metadata system.
`entityTypeName`	`string`	Data model entity type name (e.g., `UserNeed`, `SystemRequirement`).
`id`	`string`	Polarion work item ID.
`title`	`string`	Work item title.
`updated`	`datetime`	Last modification timestamp.
`project`	`object`	Project foreign key reference.

Additional fields depend on the properties defined for the entity type in the data model. Custom fields, enum properties, and computed (server-rendered) properties are included when defined.

Properties backed by Velocity templates are evaluated server-side during query execution. The Velocity context includes variables item, tx, context, and pObject for template evaluation. See Velocity Templates and Context Variables.

Primitive Field Type Mapping

When entity properties are returned in query results, Polarion custom field types are mapped to their runtime equivalents:

Polarion Field Type	Runtime Type	Notes
`string`	`string`	Plain text values
`text`	`string`	Multi-line text
`richtext`	`string`	HTML-formatted rich text
`boolean`	`boolean`	`true` / `false`
`integer`	`number`	Whole numbers
`float`	`number`	Decimal numbers
`currency`	`number`	Currency values
`date`	`datetime`	Date values
`time`	`datetime`	Time values
`duration`	`string`	Duration representation

Enum Property Resolution

When the metadata system discovers enum properties on an entity type, Powersheet automatically creates data sources for loading the available enum options. This powers dropdown pickers in the sheet without manual source configuration. The auto-generated enum source uses the following resolution pattern:

Source ID: system.enums.<enumId> (e.g., system.enums.severity)
Query construction: Filters by polarionProto, polarionType, projectId, and enumId from the entity metadata
Display mapping: Each enum option provides a display label and internal value for the picker

This process is triggered during metadata initialization and completes before any user queries execute.

Complete YAML Example

A complete source configuration demonstrating all EntityQuery properties within a sheet configuration:

sources:
  - id: rtm_matrix
    query:
      from: UserNeed
      where:
        status:
          ne: "rejected"
      orderBy:
        - severity desc
        - title
    expand:
      - name: chapter
      - name: systemRequirements
        expand:
          - name: systemRequirement
            expand:
              - name: designRequirements
                expand:
                  - name: designRequirement

columns:
  title:
    title: User Need
    hasFocus: true
    width: 250
  severity:
    title: Severity
    width: 80
  chapter:
    title: Chapter
    display: title
    isReadOnly: true
    list:
      search:
        - title
  chapter.title:
    title: Chapter Title
    isReadOnly: true
  systemRequirements.systemRequirement:
    title: System Req
    list:
      search:
        - objectId
        - title
      createNew: true
  systemRequirements.systemRequirement.title:
    title: SysReq Title
    hasFocus: true
  systemRequirements.systemRequirement.designRequirements.designRequirement:
    title: Design Req
    list:
      search:
        - objectId
        - title
  systemRequirements.systemRequirement.designRequirements.designRequirement.title:
    title: DesReq Title
    hasFocus: true

This configuration demonstrates:

Root query with from, where, and orderBy on UserNeed
N:1 expansion via chapter (direct navigation property)
M:N expansion via systemRequirements.systemRequirement (two-level association traversal)
Deep nesting continuing through designRequirements.designRequirement for a full traceability chain
Column bindings using dot-notation matching the expansion path structure
Picker configuration with list.search and list.createNew on reference columns

Cardinality and Query Pattern Summary

Cardinality	Data Model	Source Expand	Column Binding	Sheet 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 hierarchy level)
M:N	`cardinality: many-to-many`, `back.name: systemRequirements`	`- name: systemRequirements` then `- name: systemRequirement`	`systemRequirements.systemRequirement`	Multi-item reference picker

Predicates — filter syntax for where clauses
Expand Clause — detailed expand syntax and nesting rules
Query Context — runtime parameter reference
Document Filtering — document-scoped query patterns
Baseline and Revision Queries — historical data queries
Data Model Types — entity type definitions
Relationships — relationship and navigation property configuration
Sources — sheet source configuration referencing EntityQuery

​Query Properties

​The from Clause

​The where Clause

​The expand Clause

​Many-to-One (N:1) Expansion

​One-to-Many (1:N) Expansion

​Many-to-Many (M:N) Expansion

​The orderBy Clause

​Query Execution Flow

​Query Result Structure

​Primitive Field Type Mapping

​Enum Property Resolution

​Complete YAML Example

​Cardinality and Query Pattern Summary

​Related Pages

Query Properties

The `from` Clause

The `where` Clause

The `expand` Clause

Many-to-One (N:1) Expansion

One-to-Many (1:N) Expansion

Many-to-Many (M:N) Expansion

The `orderBy` Clause

Query Execution Flow

Query Result Structure

Primitive Field Type Mapping

Enum Property Resolution

Complete YAML Example

Cardinality and Query Pattern Summary

Related Pages