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.

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.
`HVO`	Raw Vault object, where the `data_store` attribute is set to `raw`. Learn more about raw objects in Vault Help.
`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 and the VQL API Reference.

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 and the Javadocs.