**Source URL:** https://limited.veevavault.dev/safety/vql/performance/understanding-query-explain-plan

# Understanding Query Explain Plan

Query explain plan is a VQL feature that allows you to evaluate the estimated cost of a VQL query before executing it, without retrieving any data. Use it to identify expensive queries, compare query approaches, and debug performance issues in your Vault integrations.

## Overview

When you submit a query with explain plan enabled, Vault analyzes the query and returns a cost breakdown in the `explain_plan` response object. No records are returned.

The explain plan reports:

*   Which query targets are involved and how they are traversed
*   Complexity scores and factors for each query phase within each target
*   Security processing costs per phase
*   (`ANALYZE` only) Measured execution time per target and phase

## Explain Levels

| Level | Executes? | Returns | Best for |
| --- | --- | --- | --- |
| `VERBOSE` | No | Full per-target cost breakdown with estimated row counts | Identifying expensive targets or phases without running the query |
| `ANALYZE` | Yes | Cost breakdown with actual row counts and measured execution times per phase. The query runs in full, but returns no data rows to the caller. | Profiling real query behavior when estimates are not enough |

## Query Phases

Each target in the explain plan has up to two execution phases:

*   Initial query: calculates the target's result set
*   Paging query: builds pages of results from the result set. This phase is absent when paging is not applicable for a target.

Each phase has its own complexity score, complexity factors, and security costs. At the `ANALYZE` level, each phase also includes a measured execution time.

## Complexity Factors

Complexity factors are specific conditions that increase a phase's complexity score. When a phase has complexity factors, look for opportunities to optimize the query.

| Factor | Description | Considerations |
| --- | --- | --- |
| `SECURITY` | The query applies record-level or field-level security processing. | Expected for secured objects. Select only the fields you need to reduce field-level security cost. |
| `COMPUTED_FIELDS` | The query contains one or more computed fields, such as formula fields, that require additional processing. | Computed fields can be expensive. Make sure to select only the computed fields you need. |
| `ORDER_BY` | The query applies a sort (`ORDER BY`) to this target. | Only sort when necessary. Sorting large result sets may add cost. |
| `SELECTED_FIELDS` | The query selects multiple fields from this target. | Make sure to select only the fields you need, as additional fields add cost. |
| `LARGE_FILTER_SET` | The query applies a complex filter or a filter containing a large set of values, such as a large `CONTAINS` clause. | Narrow filter conditions or split into multiple targeted queries. |
| `FIND` | The query applies a `FIND` clause. | Text search can be expensive. Use only when necessary. |
| `UNINDEXED_FILTER` | The query uses a filter that cannot use any index. Only applicable to `HVO` and `VAULT_QUERYABLE_ENTITY` type targets. | Add an index to the filtered field if your Vault configuration allows it. |

In addition to complexity factors, you can also optimize your query by following [best practices](/safety/vql/performance/query-performance-best-practices).

## Traversal Types

Traversal type indicates how a secondary target is joined to its parent. Primary targets always have a null traversal type.

| Traversal Type | Description |
| --- | --- |
| `RELATIONSHIP_OUTBOUND` | Outbound relationship join from parent to child, such as a subquery |
| `RELATIONSHIP_INBOUND` | Inbound relationship join from child to parent |
| `LOOKUP_SELECT` | Traversal via a lookup field referenced in the `SELECT` clause |
| `LOOKUP_FILTER` | Lookup filter that pushes a field-level filter into a related object |
| `IMPLICIT_LOOKUP_FILTER` | An implicit lookup filter added by the query engine |
| `IN_SUBQUERY` | `IN` subquery filter |

## Target Types

| Target Type | Description |
| --- | --- |
| `SVO` | Refers to the standard Vault object store, which is a Vault object where the `data_store` attribute is set to `standard`. Learn more about [data stores in Vault Help](https://platform.veevavault.help/en/lr/15298#object-data-store-options). |
| `HVO` | Raw Vault object, where the `data_store` attribute is set to `raw`. Learn more about [raw objects in Vault Help](https://platform.veevavault.help/en/lr/62987). |
| `VAULT_QUERYABLE_ENTITY` | A queryable entity used to access Vault data that is not available through Vault objects. |
| `DOCUMENTS` | A Vault document. |

## Using Explain Plan

You can create a query explain plan in the following ways:

### API Usage

Add the `X-VaultAPI-Explain` header to a `/query` request. Learn more in [VQL API Headers](/vql/references/vql-api-headers#Query_Explain_Plan) and the [VQL API Reference](/vault-api/api-reference/26.3/vault-query-language-vql/submitting-a-query#Explain_Header).

### SDK Usage

Use the `QueryService.explain()` method to evaluate the estimated cost of a VQL query from within a Vault Java SDK integration. Learn more in [Query Service](/vault-sdk/services/query-service#Using_Query_Explain_Plan) and the [Javadocs](https://repo.veevavault.com/javadoc/vault-sdk-api/26.2.3/docs/api/com/veeva/vault/sdk/api/query/QueryService.html).

---

**Previous:** [Performance](/safety/vql/performance)  
**Next:** [Query Performance Best Practices](/safety/vql/performance/query-performance-best-practices)