> ## 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.

# Configure Queries

> Customize the Lucene queries that control which work items are loaded and displayed in your Nextedy RISKSHEET, including custom filters, SQL queries, and multi-type configurations.

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>;
};

<Steps>
  <Step title="Understand the Query System">
    Risksheet builds Lucene queries to retrieve work items from Polarion. The query combines three components using AND logic:

    1. **Type filter** -- which work item types to include
    2. **Project/document scope** -- restricts to the current document
    3. **Custom query** -- your optional additional filter

    ```text theme={null}
    Query Assembly:

      Work Item Type Filter (from dataTypes.risk.type)
             +
      Project & Document Scope (automatic)
             +
      Custom Query (from dataTypes.risk.query)
             =
      Final Lucene Query
    ```
  </Step>

  <Step title="Configure Work Item Type Filtering">
    Specify which work item types appear in the Risksheet using the `dataTypes` configuration. Multiple types are combined with OR logic.

    ```yaml theme={null}
    dataTypes:
      risk:
        type: fmeaRisk
        role: relates_to
      task:
        type: mitigationTask
        role: has_parent
    ```

    <Warning title="At Least One Type Required">
      The `type` property must specify at least one work item type. If no type is configured, the system raises an error and no items are loaded.
    </Warning>
  </Step>

  <Step title="Add Custom Query Filters">
    Add a `query` property to your data type configuration to apply additional Lucene filters:

    ```yaml theme={null}
    dataTypes:
      risk:
        type: fmeaRisk
        query: status:open OR status:draft
    ```

    The custom query is ANDed with the type and scope filters. Empty or whitespace-only queries are automatically ignored.
  </Step>

  <Step title="Use Escaped Quotation Marks">
    When embedding queries with quotation marks in sheet configuration, use backslash escaping:

    ```yaml theme={null}
    dataTypes:
      risk:
        type: fmeaRisk
        query: customField:"Product Family A"
    ```

    <Tip title="SQL Query Support">
      Risksheet supports SQL queries for complex work item filtering using the `SQL:(...)` prefix syntax. This is useful when Lucene queries cannot express the required filtering logic.
    </Tip>
  </Step>

  <Step title="Configure Autocomplete Search Behavior">
    Control how the item search and autocomplete behaves when linking items. These properties are set in **Administration** > **Nextedy Risksheet** at the project level:

    | Property                | Default | Description                          |
    | ----------------------- | ------- | ------------------------------------ |
    | Fuzzy Search            | `true`  | Allows approximate matches for typos |
    | Wildcard Search         | `true`  | Enables `*` and `?` wildcards        |
    | Keyword Search Required | `false` | When true, keywords are mandatory    |
    | Suggestion Result Limit | `20`    | Maximum autocomplete results         |
    | All-Field Search        | `false` | Search all fields, not just primary  |

    <Tip title="Enable All-Field Search for Linked Items">
      Set `nextedy.risksheet.isSearchAllFieldsWhenSearchingLinkedItems=true` in Polarion Configuration Properties to search through all fields when searching linked items, not just the default fields.
    </Tip>
  </Step>

  <Step title="Configure Multi-Project Queries">
    When working with cross-project Risksheets, you can define multiple projects for upstream columns using configuration properties with Velocity snippets.

    <Warning title="Empty Configuration Property Values">
      When using configuration properties to define multi-project upstream columns, empty property values after the `=` sign cause errors. Always ensure configuration properties have valid values, and use direct project IDs rather than nested configuration property variables.
    </Warning>
  </Step>
</Steps>

## Verification

Open your Risksheet document and verify that:

1. Only work items matching your configured types appear in the grid.
2. Custom query filters correctly limit the displayed items.
3. Autocomplete search returns relevant results when linking items.

You should now see only the work items that match your query configuration, with autocomplete suggestions filtered according to your search settings.

## See Also

* [Use Query Factory](/risksheet/guides/advanced/query-factory) -- dynamic query generation for autocomplete filtering
* [Configure Upstream Traceability Columns](/risksheet/guides/columns/upstream-traceability) -- set up linked item columns
* [Configure Cross-Project Linking](/risksheet/guides/advanced/cross-project-linking) -- queries across multiple projects

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