Optimize Queries - Nextedy Documentation

Prerequisites

A working powersheet document with configured data sources
Familiarity with entity queries and predicates
Access to Polarion server logs for debug output

Understand the Query Processing Pipeline

When Powersheet loads data, each query goes through a processing pipeline that translates your configuration into a query against Polarion. Understanding this pipeline helps you write efficient queries.

Every predicate in your where clause is applied together with the entity type, the project and the data model constraints. If any predicate is not supported for its field, the whole query stops with an error instead of skipping it (see Query Execution). Performance depends on how far your constraints and predicates narrow the result.

Prefer Exact Comparisons

Equality and comparison operators are the most direct way to narrow the result. Structure your where clause to use these operators:

sources:
  - id: requirements
    model: rtm
    query:
      from: SystemRequirement
      where:
        status:
          eq: approved
        priority:
          gt: "2"

Exact-match operatorsPrefer eq, ne, gt, lt, ge, le and in over contains when you know the value. Alias operators (==, !=, >, <=) also work and are converted internally.

Avoid mixing complex logical groupings when simple predicates will do. Powersheet handles and at the top level automatically, so flat predicate structures perform best:

# Efficient -- flat predicates, exact comparisons
query:
  where:
    status:
      eq: approved
    severity:
      eq: high
    priority:
      gt: "3"

Unsupported predicates stop the queryA predicate that does not fit its field — such as contains on an enum, or a comparison on a built-in date field — stops the query with an error that names the reason. See Query Execution for the common cases.

Add Project and Document Constraints

Always define project and document constraints in your data model. Powersheet adds these to the query, dramatically reducing the result set together with your where clause:

domainModelTypes:
  SystemRequirement:
    polarionType: systemRequirement
    constraints:
      load:
        project:
          id: myProject
        document:
          moduleFolder: Requirements
          moduleName: System-Requirements

Project and document constraints work together as pre-filters. Powersheet adds them to the same query as your where clause, so they narrow the search scope.

Missing constraints hurt performanceWithout project or document constraints, queries scan all work items of a type across the entire Polarion instance. For large installations with thousands of work items, this causes significant delays. Always specify at least a project constraint.

For dynamic document scoping, use applyCurrentDocumentTo in your constraints so the sheet automatically filters to the current LiveDoc without hardcoding document paths:

domainModelTypes:
  UserNeed:
    polarionType: requirement
    constraints:
      load:
        applyCurrentDocumentTo: UserNeed

This injects the current document ID as a query parameter, scoping results to the active document context.

Limit Navigation Property Expansion Depth

Deeply nested expand clauses cause cascading queries. Each expansion level triggers additional database lookups for related entities:

# Shallow expansion (fast) -- one level of related entities
sources:
  - id: requirements
    from: SystemRequirement
    expand:
      - designRequirements

# Deep expansion (slow) -- use with caution
sources:
  - id: requirements
    from: SystemRequirement
    expand:
      - designRequirements:
          - hazards:
              - riskControls

The expand clause is converted internally to dot-notation strings for the query protocol. Each level adds another round of relationship resolution on the server.

Use views to manage expansion costCreate separate views for different analysis needs. A lightweight view showing only direct properties loads faster than a full traceability view with three levels of expansion. Users switch views as needed rather than loading everything at once.

Optimize Sort Clauses

Sorting interacts with query performance. Inside a query: block, use orderBy to determine the order of returned results. (Note that sortBy is a separate sheet-level option that belongs at the YAML root, not inside query:.)

sources:
  - id: requirements
    model: rtm
    query:
      from: SystemRequirement
      orderBy:
        - outlineNumber asc

Keep sort properties simple and aligned with indexed Polarion fields. Sorting by navigation property paths (e.g., designRequirement.title) requires the server to resolve relationships before sorting, which adds overhead.

Default sortingWhen no orderBy is specified, results come back in Polarion’s default order (typically by work item ID). Specify outlineNumber asc for document-ordered display.

Scope Enum Sources Efficiently

Powersheet auto-discovers enum properties from metadata and dynamically creates data sources for dropdown pickers. Each enum source generates a query to fetch EnumOption entities. To avoid unnecessary queries:

Only include enum columns in views where they are needed
Use constraints on enum queries to limit results to the relevant project and work item type
The auto-discovery uses polarionType, projectId, and enumId metadata to build targeted queries

Enable Query Debug Mode

To identify slow queries, use the explain query parameter. With explain enabled, the server returns diagnostic details about the executed query along with the response, and writes the query to the server log.

Verify in applicationCheck your Polarion server’s logging configuration for the exact log level and category needed to enable query debug output. The explain parameter in query configuration enables additional diagnostic information.

Performance Decision Matrix

Scenario	Recommendation	Impact
Loading all items of a type	Add project + document constraints	High
Filtering by string value	Use `eq` instead of `contains` where possible	High
Deep hierarchy display	Limit `expand` depth to 2–3 levels	High
Large result sets (1000+)	Add narrowing predicates to `where` clause	High
Cross-project queries	Specify explicit project ID constraints	Medium
Multiple enum columns	Use views to load only visible enum sources	Medium
Sort by related entity field	Sort by direct properties instead	Low

Verify

After applying optimization changes:

Open the powersheet document and note the initial load time
You should now see faster data loading compared to before your changes
Confirm the sheet loads without a query error
Test with views that hide deep expansion columns to confirm they load faster

​Prerequisites

​Performance Decision Matrix

​Verify

​See Also

Prerequisites

Performance Decision Matrix

Verify

See Also