Skip to main content

​
Prerequisites

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

​
Step 1: Understand the Query Processing Pipeline

When Powersheet loads data, each query goes through a processing pipeline that translates your configuration into Polarion Lucene queries. Understanding this pipeline helps you write efficient queries. diagram The query engine splits predicates into two categories:
  • Lucene-compatible predicates execute as database queries (fast)
  • Complex predicates execute as in-memory post-filters after fetching (slow for large datasets)

​
Step 2: Prefer Lucene-Compatible Predicates

Simple equality, comparison, and null checks translate directly to Lucene and execute efficiently: 
{
  "where": {
    "status": { "eq": "approved" },
    "priority": { "ne": null }
  }
}
These operators translate directly to Lucene: eq, ne, gt, lt, ge, le, and null checks. Use these whenever possible instead of complex function expressions.

​
Step 3: Add Project and Document Constraints

Always define project and document constraints in your domain model. These are resolved early in the query pipeline and dramatically reduce the result set before other filters are applied: 
domainModelTypes:
  SystemRequirement:
    polarionType: systemRequirement
    constraints:
      load:
        project:
          id: myProject
        document:
          moduleFolder: Requirements
          moduleName: System-Requirements
Without 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 can cause significant delays.

​
Step 4: Limit Navigation Property Expansion Depth

Deeply nested expand clauses cause cascading queries. Each expansion level triggers additional database lookups: 
# Shallow expansion (fast)
sources:
  - id: requirements
    from: SystemRequirement
    expand:
      - designRequirements

# Deep expansion (slow - use with caution)
sources:
  - id: requirements
    from: SystemRequirement
    expand:
      - designRequirements:
          - hazards:
              - riskControls
Keep expansion paths as shallow as possible. Use views to hide columns that require deep expansions when they are not needed.

​
Step 5: Use Count and Any for Validation

When you only need to check whether results exist (not fetch all data), the query engine supports efficient operations:
  • Count queries return the number of matches without fetching entities
  • Any queries stop at the first match (short-circuit evaluation)
These are more efficient than fetching a full result set and checking its size.

​
Step 6: Enable Query Debug Logging

To identify slow queries, enable debug logging on the Polarion server. The query engine logs each executed query with:
  • The prototype being queried
  • The full Lucene query string
  • The result count
  • A preview of the first 5 returned items
Check your Polarion server’s logging configuration for the exact log level and category needed to enable query debug output.

​
Performance Decision Matrix

ScenarioRecommendation
Loading all items of a typeAdd project + document constraints
Filtering by string valueUse eq instead of contains where possible
Checking if items existUse any query instead of full fetch
Deep hierarchy displayLimit expand depth to 2-3 levels
Large result sets (1000+)Add additional filter predicates
Cross-project queriesSpecify explicit project ID list

​
Verify

After applying optimization changes:
  1. Open the powersheet document and note the load time
  2. You should now see faster initial data loading compared to before
  3. Check Polarion server logs for the query execution output to confirm efficient Lucene queries
  4. Compare the number of in-memory post-filter operations — fewer is better

​
See Also

Source Code
  • PolarionQueryProcessor.java
  • QueryExecutorTest.java
  • GenericQueryResolver.java
  • prod-powersheet-src/com.nextedy.powersheet.client/src/modules/ModelProvider/ModelProvider.tsx
  • prod-powersheet-src/com.nextedy.powersheet.client/src/modules/QueryManager/QueryManager.tsx