Skip to main content

​
Query Translation Overview

diagram

​
Predicate-to-Lucene Mapping

The query processor converts predicates from entity queries into Lucene syntax. The following table documents the confirmed mappings.
Predicate TypeEntity Query SyntaxLucene Output
Equality (string){ 'name': 'John' }name:"John"
Equality (numeric){ 'count': 5 }count:5
Object ID (simple){ 'objectId': 'WI-123' }id:"WI-123"
Object ID (with project){ 'objectId': 'elibrary/WI-123' }(project.id:"elibrary" AND id:"WI-123")
Inequality (!=){ 'status': { 'ne': 'closed' } }NOT status:"closed"
Null check{ 'title': null }NOT HAS_VALUE:title
Not-null check{ 'title': { 'ne': null } }HAS_VALUE:title
AND composite{ 'and': [...] }(expr1) AND (expr2)
OR composite{ 'or': [...] }(expr1) OR (expr2)
NOT (unary){ 'not': { ... } }NOT (expr)
Both '!=' and 'ne' syntax are supported for inequality checks. Both { 'objectId': 'value' } shorthand and explicit { 'objectId': { 'eq': 'value' } } syntax produce identical Lucene output.

​
Lucene Query Prefixes

PrefixLucene FragmentPurpose
QUERY_TYPE_PREFIXtype:Filters entities by work item type
QUERY_PROJECT_PREFIX AND project.id:Appends project-scoping constraint

​
Type Filtering

type:systemRequirement AND project.id:"MyProject"
Powersheet automatically prepends type: followed by the Polarion work item type mapped from the entity type’s polarionType property. See Polarion Type Mapping for entity-to-type mapping details.

​
Project Scoping

The query resolver automatically appends project.id:<projectId> to all queries when executing in a project-scoped context. This ensures results are restricted to the current project. See Project Scoping for details.

​
Query Execution

The query resolver executes translated Lucene queries against Polarion’s persistence layer via the IDataService.searchInstances method.
ParameterTypeDescription
prototypestringPolarion object prototype (e.g., work item prototype)
luceneQuerystringTranslated Lucene query string
limitintegerMaximum results. Value -1 retrieves all matching results (unlimited)
Passing a limit of -1 disables result pagination and retrieves all matching results. Use with caution on queries that may return large result sets, as this can impact server performance.

​
Debug Logging

Powersheet logs executed Lucene queries with structured debug output for troubleshooting.
Log FieldDescription
PrototypeThe Polarion object prototype being queried
Query stringThe complete Lucene query sent to Polarion
Result countNumber of matching entities returned
Item previewFirst 5 item IDs from the result set (for larger result sets, shows count summary)
Enable debug logging in the Polarion server configuration to see query execution details. Consult your Polarion administrator for log access.

​
HAS_VALUE Pseudo-Field

Polarion uses the HAS_VALUE pseudo-field to test whether a property has any value assigned. 
HAS_VALUE:title          -- entities where title is not null
NOT HAS_VALUE:severity   -- entities where severity is null
This is used internally by Powersheet when translating null-check predicates. See Predicates for the entity query syntax.

​
Composite Query Precedence

Nested composite predicates maintain correct operator precedence through recursive parenthesization. 
(type:"systemRequirement") AND ((status:"open") OR (priority:"high"))
Each operand in AND and OR composites is wrapped in parentheses to prevent precedence ambiguities.

​
ID-Based Queries

The query engine can convert resolved query results into ID-based Lucene filters for efficient secondary queries.
PatternLucene OutputNotes
Project IDsproject.id:"proj1" OR project.id:"proj2"From resolved project query
Document IDsdocument.id:"Space/DocName"Space prefix prepended unless _default space
Empty resultsReturns unresolvable query constantEnsures empty results rather than fetching all
Document IDs in Lucene queries include the space prefix (e.g., Requirements/MyDoc). The _default space is omitted from the prefix.

​
Complete YAML Example

sources:
  - id: requirements
    title: System Requirements
    model: rtm
    query:
      from: SystemRequirement
      where: "type:systemRequirement AND HAS_VALUE:title"
    expand:
      - name: designRequirements
        title: Design Requirements
        expand:
          - name: designRequirement
In this configuration, the where clause uses Lucene syntax directly. The type: prefix filters by Polarion work item type, and HAS_VALUE:title excludes items without a title.
Source context: GenericQueryResolver, QueryFactory, QueryToLuceneTest, PowersheetConstants
Source Code
  • GenericQueryResolver.java
  • QueryFactory.java
  • PolarionQueryProcessor.java
  • QueryToLuceneTest.java
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/fixtures/configurations/constraints_currentDocument_downstream.template.yaml