Submitting a Query

Retrieve and filter Vault data using a VQL query.

POST/api/{version}/query

Headers

Name	Description
`Accept`	`application/json` (default) or `application/xml`
`Content-Type`	`application/x-www-form-urlencoded` or `multipart/form-data`
`X-VaultAPI-Explain`	Optional: If present, retrieve a query execution cost estimate instead of query results. Valid values are `verbose` and `analyze`. Cannot be combined with `X-VaultAPI-DescribeQuery`, `X-VaultAPI-RecordProperties`, `X-VaultAPI-DocumentProperties`, or `X-VaultAPI-Facets`. Learn More.
`X-VaultAPI-DescribeQuery`	Set to `true` to include static field metadata in the response for the data record. If not specified, the response does not include any static field metadata. This option eliminates the need to make additional API calls to understand the shape of query response data. Learn More.
`X-VaultAPI-RecordProperties`	Optional: If present, the response includes the record properties object. Possible values are `all`, `hidden`, `redacted`, and `weblink`. If omitted, the record properties object is not included in the response. Learn more.
`X-VaultAPI-DocumentProperties`	Optional: If present, the response includes the document properties object. The only possible value is `all`. If omitted, the document properties object is not included in the response. Learn more.
`X-VaultAPI-Facets`	Optional: If present, the response includes the `facets` object containing the count of unique values for each facetable field. Learn more.

Body Parameters

Name	Description
`q` required	A VQL query of up to 50,000 characters, formatted as `q={query}`. For example, `q=SELECT id FROM documents`. Note that submitting the query as a query parameter instead may cause you to exceed the maximum URL length.

Request

curl -X POST -H "Authorization: {AUTH_VALUE}" \
-H "X-VaultAPI-DescribeQuery: true" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
--data-urlencode "q=SELECT id, name__v FROM documents WHERE product__v = ‘cholecap’"
https://myvault.veevavault.com/api/v26.3/query

Response

{
   "responseStatus": "SUCCESS",
   "queryDescribe": {
       "object": {
           "name": "documents",
           "label": "documents",
           "label_plural": "documents"
       },
       "fields": [
           {
               "type": "id",
               "required": true,
               "name": "id"
           },
           {
               "label": "Name",
               "type": "String",
               "required": true,
               "name": "name__v",
               "max_length": 100
           }
       ]
   },
   "responseDetails": {
       "pagesize": 1000,
       "pageoffset": 0,
       "size": 5,
       "total": 5
   },
   "data": [
       {
           "id": 72,
           "name__v": "Cholecap-2021-brochure"
       },
       {
           "id": 63,
           "name__v": "Cholecap - Multisequence"
       },
       {
           "id": 36,
           "name__v": "Cholecap Study"
       },
       {
           "id": 25,
           "name__v": "Clinical Trial Reference"
       },
       {
           "id": 24,
           "name__v": "Formulary Guidelines"
       }
   ]
}

Response Details

On SUCCESS, the response includes the following information:

Name	Description
`pagesize`	The number of records displayed per page. This can be modified. Learn more.
`pageoffset`	The records displayed on the current page are offset by this number of records. Learn more.
`size`	The total number of records displayed on the current page.
`total`	The total number of records found.
`previous_page`	The Pagination URL to navigate to the previous page of results. This is not always available. Learn more.
`next_page`	The Pagination URL to navigate to the next page of results. This is not always available. Learn more.
`data`	The set of field values specified in the VQL query.

About the X-VaultAPI-Explain Header

When you include the X-VaultAPI-Explain header, the response includes the explain_plan object instead of query results.

Name	Description
`cardinality_basis`	Whether row counts in the plan are `ESTIMATE` (`verbose`) or `ACTUAL` (`analyze`).
`targets[]`	Array of per-target cost breakdowns. See the `targets` table for more information.
`summary`	Aggregate execution statistics. Only present at the `analyze` level. See the `summary` table for more information.
`vql_engine`	Engine-level operations not attributed to a specific query target. Only present at the `analyze` level. Contains an `operations` array; each operation includes `name` and `target_id`.

The `targets[]` Array

Name	Description
`id`	Unique identifier for this target within the plan.
`object`	The Vault object or document type queried.
`target_type`	The storage type of this target.
`traversal_type`	Engine-level operations not attributed to a specific query target. Only present at the `analyze` level. Contains an `operations` array; each operation includes `name`, `target_id`, and `execution_ms`.
`position`	`PRIMARY` or `SECONDARY`.
`relationship_name`	The relationship field used to join this target. `null` for primary targets.
`initial_row_count`	Estimated or actual row count for the initial query phase. May be a sentinel value such as `SKIPPED` if estimation was not performed.
`initial_row_count_execution_ms`	Total execution time for this target, in milliseconds.
`applied_filters`	Filters applied to this target.
`applied_order`	Sort order applied to this target.
`memory_estimate_bytes_per_row`	Estimated memory usage per row, in bytes.
`actual_row_count`	Actual number of rows returned for this target. Only present at the `analyze` level.
`actual_page_size`	Page size used when fetching results for this target. Only present at the `analyze` level.
`initial_query`	Cost data for the initial query phase. Contains `cost_factors` and (`analyze` only) `execution_ms`. May be `null`. See the `cost_factors` table for more information.
`paging_query`	Cost data for the paging query phase. Contains `cost_factors` and (`analyze` only) `execution_ms`. May be `null` if paging is not applicable for this target. See the `cost_factors` table for more information.

The `cost_factors` Fields

Inside initial_query and paging_query, the cost_factors fields include:

Name	Description
`target_complexity`	Numeric complexity score for this phase, as a decimal with precision 2. For example, `8.77`. Higher values indicate greater cost.
`complexity_factors[]`	Array of specific factors that contributed to the complexity score. Learn more in Complexity Factors.
`security.record_level`	Whether record-level security is applied to this phase.
`security.field_level`	Whether field-level security is applied to this phase.
`security.field_level_ms`	Measured execution time for field-level security processing, in milliseconds. Only present at the `analyze` level.

The `summary` Fields

For analyze queries only, the response includes the following summary fields:

Name	Description
`records_returned`	Total number of records returned by the query.
`actual_page_count`	Total number of pages used during execution.
`actual_page_size`	Page size used during execution.
`total_execution_ms`	Total end-to-end query execution time, in milliseconds.

About the X-VaultAPI-DescribeQuery Header

When you include the X-VaultAPI-DescribeQuery header and set it to true, the query response includes query metadata, including the query type:

Name	Description
`type`	The type of query: `select__sys`, `show_targets__sys`, `show_fields__sys`, or `show_relationships__sys`

The response also includes the following static metadata description. These values are null for SHOW TARGETS (show_targets__sys) queries.

Name	Description
`name`	The name of the queryable object.
`label`	The label of the queryable object.
`label_plural`	The plural label of the queryable object.

The field metadata may include some or all of the following:

Metadata Field	Description
`name`	The name of the field.
`label`	The UI label of the field.
`type`	The data type, for example, `String` or `Number`
`max_length`	The max length of a string field.
`max_value`	The max value of a number field.
`min_value`	The minimum value of a number field.
`scale`	The number of digits after a decimal point in a number field.
`required`	Indicates whether the field is required (`true`/`false`).
`unique`	Indicates whether the value must be unique (`true`/`false`).
`status`	Indicates whether the field is active (`active`/`inactive`).
`picklist`	The picklist name field value.
`encrypted`	Indicates whether the Contains Protected Health Information (PHI) or Personally Identifiable Information (PHI) setting is selected for this field (`true`/`false`). Learn more in Vault Help.
`format_mask`	The format mask expression if it exists. Learn more about format masks in Vault Help.
`function`	The function name if the VQL query applies a function to this field.
`alias`	If `true`, the VQL query applies an alias to this field. Omitted if `false`.

Note: For formula fields, queryDescribe should describe the field as specified in the metadata, excluding the formula attribute.

About the X-VaultAPI-RecordProperties Header

When you include the X-VaultAPI-RecordProperties header, the query response includes the record_properties object. The record_properties object describes the properties of a data record. If set to all, the response includes for each record:

Name	Description
`id`	The record ID.
`field_properties`	Includes arrays of `hidden`, editable (`edit`), and `redacted` fields. To return only hidden or redacted fields, set the `X-VaultAPI-RecordProperties` header to `hidden` or `redacted`, respectively.
`permissions`	Includes whether this record has `read`, `edit`, `create`, and `delete` permissions.
`subquery_properties`	Includes an array of hidden subquery relationships for this record.
`field_additional_data`	Includes configuration data for `link` type formula fields. To return only this data, set the `X-VaultAPI-RecordProperties` header to `weblink`.

For each field, the field_additional_data metadata includes the name of the field and the web_link object, which contains the following metadata:

Metadata Field	Description
`label`	The text that appears as a link in the Vault UI.
`target`	Determines whether the link will open in a `new_window` or the `same_window`.
`connection`	Populates another Vault's DNS within the URL utilizing a configured `connection__sys` object record.

About the X-VaultAPI-DocumentProperties Header

When you include the X-VaultAPI-DocumentProperties header, the query response includes the document_properties object describing the properties of a document. If set to all, the response includes for each document:

Name	Description
`id`	The document ID.
`document_version`	The specific version of the document.
`permissions`	Includes boolean flags for all lifecycle state permissions the querying user has for this document.
`field_properties`	Includes arrays of the editable (`edit`) and read-only fields included in the query.

About the X-VaultAPI-Facets Header

When you include the X-VaultAPI-Facets header with a list of facetable fields, the response includes the facets object containing the count of unique values for each facetable field. Determine which fields are facetable using the Retrieve Object Metadata API. For each facetable field included in the header, the response includes:

Name	Description
`label`	The label for the facetable field in the Vault UI.
`type`	The field’s data type.
`name`	The name of the facetable field.
`count`	The number of unique values for this field in the Vault.
`truncated_list`	A boolean indicating that the list is truncated because it contains more than 50 values.

The values metadata contains the unique values for the facetable field in the Vault, sorted first by result_count and secondly by value.

Metadata Field	Description
`value`	A value of this facetable field in the Vault. For example, `ophthalmology__c`.
`result_count`	The number of records with this field value in the Vault.