> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Syntax

> Nextedy RISKSHEET uses Polarion's Lucene query engine to filter and retrieve work items displayed in the grid. Queries appear in data type configurations, autocomplete search, and query factory functions.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## Query Types

Risksheet supports two query syntaxes:

| Syntax | Prefix      | Description                                           |
| ------ | ----------- | ----------------------------------------------------- |
| Lucene | (none)      | Default Polarion query syntax for work item filtering |
| SQL    | `SQL:(...)` | SQL queries for complex work item filtering           |

## Lucene Query Basics

Lucene queries filter work items based on field values using standard Polarion query syntax.

### Operators

| Operator | Syntax             | Example                                      | Description                 |
| -------- | ------------------ | -------------------------------------------- | --------------------------- |
| Equals   | `field:value`      | `type:risk`                                  | Field equals exact value    |
| NOT      | `NOT field:value`  | `NOT status:closed`                          | Field does not equal value  |
| AND      | `expr1 AND expr2`  | `type:risk AND status:open`                  | Both conditions must match  |
| OR       | `expr1 OR expr2`   | `type:risk OR type:hazard`                   | Either condition must match |
| Wildcard | `field:val*`       | `title:brake*`                               | Wildcard matching           |
| Quoted   | `field:"value"`    | `title:"Brake Failure"`                      | Exact phrase matching       |
| Grouping | `(expr1 OR expr2)` | `(type:risk OR type:hazard) AND status:open` | Logical grouping            |

### Common Fields

| Field             | Description            | Example                   |
| ----------------- | ---------------------- | ------------------------- |
| `type`            | Work item type         | `type:risk`               |
| `status`          | Workflow status        | `status:open`             |
| `project.id`      | Project identifier     | `project.id:AutoSafety`   |
| `module`          | Document/module path   | `module:"Risks/FMEA"`     |
| `id`              | Work item ID           | `id:RISK-001`             |
| `title`           | Work item title        | `title:"Brake Failure"`   |
| `linkedWorkItems` | Linked item references | `linkedWorkItems:REQ-001` |

## Query Assembly

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/yWl5nA2D0IzEnZC1/risksheet/diagrams/reference/query-syntax/diagram-1.svg?fit=max&auto=format&n=yWl5nA2D0IzEnZC1&q=85&s=5872c8d044e254bbdbaf4548f9b525db" alt="diagram" style={{ maxWidth: "700px", width: "100%" }} width="700" height="160" data-path="risksheet/diagrams/reference/query-syntax/diagram-1.svg" />
</Frame>

The final query is assembled by combining four components with AND logic:

1. **Type filter** -- Work item type from `dataTypes.<name>.type` (additional types on a link column come from `typeProperties.linkTypes`), combined with OR if multiple
2. **Project scope** -- Current project identifier
3. **Document scope** -- Current document/module path (quoted to handle spaces)
4. **Custom query** -- Additional user-defined conditions from the `query` property

Empty conditions are automatically skipped. At least one work item type must be specified or the system returns an error.

## Query in Configuration

### Data Type Query

The `dataTypes` configuration uses the `query` property to add custom filtering to the generated query:

```yaml theme={null}
dataTypes:
  risk:
    type: fmea_risk
    role: relates_to
    query: NOT status:rejected
  task:
    type: mitigation
    role: mitigates
    query: NOT status:closed
```

| Property                 | Type     | Default         | Description                                                                                                                                                   |
| ------------------------ | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dataTypes`              | `object` | `{}`            | Configures risk and task data types including query factories, work item types, roles, and menu visibility                                                    |
| `dataTypes.<name>.type`  | `string` | Required        | Single Polarion work-item type id for this data type. (Additional types for a link column are scoped via `typeProperties.linkTypes` on the column, not here.) |
| `dataTypes.<name>.query` | `string` | `""`            | Custom Lucene query fragment appended with AND logic                                                                                                          |
| `dataTypes.<name>.role`  | `string` | See application | Link role used for item relationships                                                                                                                         |

### Escaped Quotation Marks in JSON

When embedding queries that contain quotation marks inside sheet configuration, escape the inner quotes with a backslash (`\"`):

```yaml theme={null}
{
  "dataTypes": {
    "risk": {
      "type": "fmea_risk",
      "query": "customField:\"specific value\" AND category:\"safety\""
    }
  }
}
```

<Tip title="JSON String Escaping">
  Use `\"` to include quotation marks within JSON string values. This is standard JSON escaping and applies to all query strings in sheet configuration.
</Tip>

## SQL Query Support

Risksheet supports SQL queries for complex filtering scenarios using the `SQL:(...)` prefix:

```yaml theme={null}
dataTypes:
  risk:
    query: SQL:(SELECT wi FROM WorkItem wi WHERE wi.project.id = 'AutoSafety')
```

<Info title="Verify in application">
  SQL query syntax and available tables/fields depend on your Polarion server version. Verify supported SQL constructs in your environment before deploying.
</Info>

## Query Factory

Query factories provide dynamic query filtering through custom JavaScript functions registered on the `window.risksheet.queryFactories` object. They enable context-aware filtering of linked items in autocomplete dropdowns.

```yaml theme={null}
{
  "columns": [
    {
      "bindings": "linkedRequirement",
      "header": "Linked Requirement",
      "type": "itemLink",
      "typeProperties": {
        "queryFactory": "requirementFilter"
      }
    }
  ]
}
```

Register the factory in a top panel script or external JavaScript:

```javascript theme={null}
window.risksheet = window.risksheet || {};
window.risksheet.queryFactories = window.risksheet.queryFactories || {};
window.risksheet.queryFactories["requirementFilter"] = function(info) {
  return "type:requirement AND status:approved";
};
```

| Feature                 | Description                                                                                                 |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- |
| Autocomplete filtering  | Customizes which items appear in autocomplete suggestion dropdowns                                          |
| Context-aware search    | Factory function receives a single `info` object (current row item and context), enabling dynamic filtering |
| Link editor integration | Applied to item link, multi-item link, and task link column editors                                         |

See [JavaScript API](/risksheet/reference/api/javascript-api) for the full query factory API.

## Document Path Handling

Document IDs with `_default/` prefix (default modules) have the prefix automatically stripped before query construction. Document paths containing spaces or special characters are automatically quoted in the generated query.

## Autocomplete Search Behavior

The autocomplete suggestion system uses queries to search for matching work items:

| Parameter            | Type    | Default         | Description                                                |
| -------------------- | ------- | --------------- | ---------------------------------------------------------- |
| Fuzzy search         | Boolean | See application | Enables approximate matching for spelling variations       |
| Wildcard search      | Boolean | See application | Allows `*` wildcard characters in search terms             |
| Keyword matching     | Boolean | See application | When enabled, all search terms must be present (AND logic) |
| Result limit         | Number  | `50`            | Maximum number of suggestion results returned              |
| Minimum query length | Number  | `3`             | Minimum characters before autocomplete activates           |

<Note title="Autocomplete Scope">
  Suggestions are automatically scoped to the current project. Cross-project suggestions are not available in the default autocomplete. Newly created items that have not been saved appear in suggestions for the current session.
</Note>

See [Suggestion and Autocomplete API](/risksheet/reference/api/suggestion-api) for the full API reference.

## Complete Example

A full configuration demonstrating query usage across data types and columns:

```yaml theme={null}
{
  "dataTypes": {
    "risk": {
      "type": "fmea_risk",
      "role": "relates_to",
      "query": "NOT status:rejected AND customField:\"productFamily_A\""
    },
    "task": {
      "type": "mitigation",
      "role": "mitigates",
      "query": "NOT status:closed"
    }
  },
  "columns": [
    {
      "bindings": "linkedRequirement",
      "header": "Requirement",
      "type": "itemLink",
      "typeProperties": {
        "queryFactory": "requirementFilter"
      },
      "canCreate": true
    },
    {
      "bindings": "linkedHazard",
      "header": "Hazard",
      "type": "itemLink",
      "typeProperties": {
        "queryFactory": "hazardFilter"
      }
    }
  ]
}
```

This configuration:

* Loads FMEA risk items for `productFamily_A`, excluding those with `rejected` status
* Loads `mitigation` task items, excluding `closed` items
* Provides item link columns for requirements (with creation) and hazards, each with custom query factory filtering

## Related Pages

* [Configuration Properties Index](/risksheet/reference/configuration/properties-index) -- all configuration properties
* [Risksheet.json Format](/risksheet/reference/configuration/risksheet-json-format) -- sheet configuration structure
* [Suggestion and Autocomplete API](/risksheet/reference/api/suggestion-api) -- autocomplete endpoint reference
* [JavaScript API](/risksheet/reference/api/javascript-api) -- query factory registration
* [Item Link Columns](/risksheet/reference/columns/item-link-columns) -- item link column configuration
* [Top Panel Template](/risksheet/reference/templates/top-panel-template) -- bridging server data for query factories

<LastReviewed date="2026-06-24" />