> For the complete documentation index, see [llms.txt](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/features/search/saved-queries/manage-ootb-queries.md).

# Manage Out-of-the-Box Queries

Compare, update, reset, and review removals for the queries Veza ships

**Available in Veza v2026.9.7 and later.**

Veza includes hundreds of out-of-the-box (OOTB) queries, refined over time through product releases. When Veza changes the definition of a query a tenant already has, or drops one from the catalog, the query's details page reports the change and offers a decision about it.

By default, Veza applies those changes automatically. Turning on **staged review** holds each one for an administrator to accept or dismiss instead.

Two facts determine what Veza reports for a query:

* **Whether the query has been edited.** Editing an out-of-the-box query marks it as customized. The query keeps its identity as a system query; it does not become a custom query.
* **Whether Veza has changed the shipped definition.** A change can be an update to the definition, or removal of the entry from the catalog altogether.

{% hint style="info" %}
Veza does not keep a version history for out-of-the-box queries. A comparison is between the definition a query runs on today and the definition Veza ships today.
{% endhint %}

For more on working with saved queries and managing visibility, labels, risk levels, and rules, see [Saved Queries](/4yItIzMvkpAvMVFAamTf/features/search/saved-queries.md).

## How Veza applies out-of-the-box updates

Veza compares the out-of-the-box catalog against the queries in a tenant at two points:

* When the tenant is upgraded or restarted
* When an administrator refreshes static assessment data

Nothing runs the comparison on a schedule in between. When the query definition has changed, the outcome depends on whether staged review is enabled and whether the query has been edited.

| Situation                                                 | Staged review off (default)                                                | Staged review on                              |
| --------------------------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------- |
| The shipped definition changed, and the query is unedited | Applied automatically                                                      | Staged as an update for review                |
| The shipped definition changed, and the query is edited   | Left untouched; no update is staged                                        | Staged as an update for review                |
| The entry was removed from the catalog                    | The query is deleted, along with its risks, reports, and scheduled exports | Staged as a removal for review                |
| A removed entry returned to the catalog                   | The query is restored to the current shipped definition                    | Any staged removal is dismissed automatically |

Even with staged review off, drift on an edited query stays visible: **View Changes** compares it against the definition Veza ships today.

Each team sees its own copy of every out-of-the-box query, so one team's edits and decisions do not affect another's. To propagate an edited out-of-the-box query to other teams, share it on a dashboard (see [Share edited out-of-the-box queries](/4yItIzMvkpAvMVFAamTf/features/insights/dashboards/dashboard-sharing.md#share-edited-out-of-the-box-queries)).

These rules apply whether or not staged review is on:

* **Deleting an out-of-the-box query does not keep it out of your assessments.** If Veza still ships the query, the next check restores it with the current shipped definition. [Disable it](/4yItIzMvkpAvMVFAamTf/features/search/saved-queries.md#disable-and-enable-queries) instead.
* **Queries a team cannot see are not staged.** A query whose target integrations are not configured for a team is hidden from that team's query lists, so Veza updates or removes it automatically. Configuring the integration later surfaces the query with the definition Veza ships at that point.
* **Existing customizations are not flagged retroactively.** When staged review is first enabled, each edited query is matched to the definition Veza ships at that moment. Earlier changes are not reported.

{% hint style="info" %}
Veza does not announce a staged change by email or in digest notifications. The query's details page is the only place a pending decision appears, and it stays there until the change is accepted or dismissed.
{% endhint %}

## Enable staged review of out-of-the-box updates

Staged review is off by default. Until an administrator turns it on, Veza applies out-of-the-box updates and removals automatically, as described in [How Veza applies out-of-the-box updates](#how-veza-applies-out-of-the-box-updates).

To enable staged review:

1. Go to **Administration** > **System Settings** > **Assessment Queries**.
2. Enable **Stage OOTB Query Updates for Review**.

![The Stage OOTB Query Updates for Review setting](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-ea92ce34174dc397f23dab6dfc3b606cb6678328%2Footb-staging-system-setting.png?alt=media)

Veza reads the setting when it checks the catalog, so a change takes effect at the next restart or static data refresh, not immediately.

Turning the setting off resolves anything already staged, at the next check: an update on an unedited query is applied, an update on an edited query is dismissed, and a staged removal deletes the query.

## Check out-of-the-box status on a query

The **Modifications** field in the query details header bar reports how the query compares with the Veza catalog entry it came from, and the action available in that state.

![Query header bar showing the Modifications field](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-faed721fe3239be7cd26b43cfad10f3f6c4b4d33%2Footb-query-header-bar.png?alt=media)

| Modifications       | Meaning                                                                                                                                                                                                           | Action             |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| **Unchanged**       | The query runs on the definition Veza ships, and nobody has edited it.                                                                                                                                            | None               |
| **Edited**          | Someone has customized the query, so it no longer matches the shipped definition.                                                                                                                                 | **View Changes**   |
| **Removed by Veza** | Veza has dropped the source entry from the out-of-the-box catalog, and the removal is staged for review.                                                                                                          | **Review Removal** |
| **Clone**           | The query is a copy of another query, made with **Clone** or **Save as New**. A clone has no shipped definition of its own, so it offers no action even when an update is staged on the query it was copied from. | None               |

When an update is staged, the action becomes **Update Available** and **Modifications** still reads **Unchanged** or **Edited**.

{% hint style="info" %}
**Limitations.** **Modifications** appears on the query details page only — the **Queries** table has no column or badge for it, so the query list cannot be sorted or filtered by whether an update is available. The field is omitted altogether for a query built from scratch in [Query Builder](/4yItIzMvkpAvMVFAamTf/features/search/query-builder.md), which has no lineage to report.
{% endhint %}

{% hint style="info" %}
**Permissions.** Accepting or dismissing an update, keeping a removed query, and resetting a query each require a role that can update assessment queries: **Admin**, **Operator**, **Access Reviews Admin**, or **NHI Security Admin**. Deleting a removed query requires a role that can delete assessment queries.
{% endhint %}

## Compare a query with the Veza original

Click **View Changes** to open **Compare With Original Veza Query**, a full-page, read-only comparison.

The two cards show:

| Card                        | Contents                                                                                           |
| --------------------------- | -------------------------------------------------------------------------------------------------- |
| Left: **Current Version**   | The definition the query runs on today, attributed to the user who last edited it (**Edited by**). |
| Right: **Original Version** | The definition Veza ships today, credited to Veza.                                                 |

On an unedited query, both cards read **Original Version** and are credited to Veza.

Fields that differ are outlined and highlighted on both cards. Each card shows:

* **Query Name**, **Query Description**, and **Labels**
* **Risk Profile**, **Risk Level**, **Risk Explanation**, and **Risk Remediation**
* **Query Parameters** — the query logic: source entities, relationships, filters, conditions, and intermediate entities
* **Summary Entities**

A field is omitted from a card when that definition leaves it empty. Longer query logic is abbreviated, with a **Show Full Evaluation** link.

![Comparing a query with the Veza original](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-c61db7bc25f2b07fe967f719ca8833bd4fad9100%2Footb-compare-original.png?alt=media)

If the query is eligible for reset, a **Reset to Original** button appears in the page header. See [Reset a query to its original version](#reset-a-query-to-its-original-version).

{% hint style="info" %}
Veza also compares two settings the cards do not show: the query's result type and whether it is optional. If one of those is the only difference, the query reads as changed but no field is highlighted.

Timestamps, authorship, and internal identifiers are ignored, and tenant and time variables are compared in their unresolved form.
{% endhint %}

Two states are reported in place of a comparison:

* **The original Veza query is no longer available**: Veza has removed the entry from the out-of-the-box catalog, so there is nothing left to compare against. The query keeps running on its current definition.
* **This query has no Veza original**: The query was not derived from an out-of-the-box query.

{% hint style="info" %}
**Comparing through the API.** `GET /api/private/assessments/queries/{query_id}:ootb_diff` returns the same field-level differences the comparison page shows, together with both full definitions. To check lineage instead, [Get a saved query](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getassessmentquery.md) reports whether a query came from the catalog and whether it has been edited.
{% endhint %}

## Review a staged update

When [staged review is enabled](#enable-staged-review-of-out-of-the-box-updates) and Veza ships a new definition for a query in the tenant, the update is held for a decision rather than applied. **Update Available** opens the comparison as **Veza Query Update**, where the right card is titled **Updated Version** and attributed **Suggested by** Veza.

![Reviewing a staged out-of-the-box update](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-b189aee8a47959717a1739554e8be9351faf7c95%2Footb-pending-update.png?alt=media)

Two actions are available:

* **Update Query** replaces the query's definition with the one Veza ships, discarding any customizations. It behaves exactly like [reset](#reset-a-query-to-its-original-version): the query ID, owners, creation record, and hidden, enabled, or disabled state are all preserved. Veza reports *Query updated to the latest Veza version*.
* **Dismiss** opens the **Dismiss this update?** dialog, which records an optional **Reason**. The query keeps its current definition, and Veza reports *Update dismissed*. Veza does not raise the same update again, but the next definition it ships stages a new one.

![Dismissing a staged out-of-the-box update](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-1db345fbdac373b46117b9026c42b6e9ead097f6%2Footb-dismiss-update.png?alt=media)

A query holds at most one staged update at a time. If Veza ships another definition while an update is still waiting for a decision, the newer one replaces it, so the definition under review is always the most recent.

{% hint style="info" %}
**Resolving through the API.** `POST /api/private/assessments/queries/{query_id}:resolve_pending_ootb_update` accepts or dismisses a staged update, with an optional reason recorded on a dismissal. The call fails if nothing is staged for the query.
{% endhint %}

## Review a removed out-of-the-box query

When Veza drops a query from the out-of-the-box catalog and staged review is enabled, **Modifications** reads **Removed by Veza** and **Review Removal** opens **Veza Query Removed**. The query has not been changed or disabled; it keeps running until a decision is made. The page shows the definition it runs on today.

![Reviewing a removed out-of-the-box query](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-34b293d376e865c95387b4fce8c61c84db2c0d14%2Footb-query-removed.png?alt=media)

* **Keep Query** retains the query in the tenant and clears the flag. Veza reports *Query kept*, and does not raise the same removal again.
* **Delete Query** asks for confirmation, then permanently deletes the query along with its history. Reports, alerts, and workflows that use it stop returning results, and the deletion cannot be undone. Veza reports *Query deleted*.

{% hint style="info" %}
If Veza returns the query to the catalog before a decision is made, the staged removal is dismissed automatically and the flag clears.
{% endhint %}

## Reset a query to its original version

Reset restores a customized out-of-the-box query to the definition Veza ships. Use it to discard changes to a query and return it to the current shipped baseline.

**Eligibility.** The option to **Reset to Original System Query** appears only for an out-of-the-box (system-created) query that has been edited. It is not offered for custom queries created in [Query Builder](/4yItIzMvkpAvMVFAamTf/features/search/query-builder.md), for uneditable static queries, or for queries shared with another team.

{% hint style="info" %}
**Resetting through the API.** `POST /api/v1/assessments/queries/{id}:reset` resets any out-of-the-box query, edited or not, and is idempotent. The console offers the action only for queries that have been edited.
{% endhint %}

Reset overwrites the query's content with the shipped default:

* Name, description, and query logic
* Result type and visibility
* Risk level, risk explanation, and remediation guidance
* Integration types, labels, and related query settings

Reset preserves the original query identity and access control:

* The query ID
* Query owners (the users with edit permission)
* Who created the query, and when
* Whether the query is hidden
* Whether the query is enabled or disabled

Resetting also clears the query's edited state, which removes **Reset to Original System Query** from the menu until the query is edited again.

To reset an out-of-the-box query:

1. Open the **Access Visibility** > **Queries** page.
2. Click the **Actions** menu (⋮) for the query to reset, and select **View Query Details**.
3. On the query details page, click **More options** (⋮) and select **Reset to Original System Query**.
4. Review the **Reset to original system query?** dialog — it names the query and warns that the changes made to it, including query logic, filters, risk settings, and labels, are lost and cannot be recovered — then click **Reset query**.

**Reset to Original** on the [comparison page](#compare-a-query-with-the-veza-original) does the same thing.

Veza reports *Query reset to original system query*, and refreshes the query in place.

**After reset.** The query runs on the current shipped definition from the next scheduled assessment run.

* If the reset changes the query's integration types or labels, dependent reports update automatically.
* The reset is recorded in the query's change history (**View Change History**) and in the [audit log](/4yItIzMvkpAvMVFAamTf/administration/administration/events.md).

**Errors and edge cases.**

* **Name conflict**: Reset fails if another out-of-the-box query already uses the shipped name.
* **Original no longer available**: If the original query definition is no longer part of the current Veza release, Veza reports *We couldn't reset this query* and explains that the original system query is no longer available. Retrying does not resolve this.
* **Ineligible query**: Uneditable and shared queries return a permission error. A custom query is rejected because it has no out-of-the-box definition to restore.

{% hint style="info" %}
Reset is separate from [dashboard sharing](/4yItIzMvkpAvMVFAamTf/features/insights/dashboards/dashboard-sharing.md): removing a shared dashboard does not reset or restore a query.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/features/search/saved-queries/manage-ootb-queries.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.