Learn Vantage Query Language (VQL), a SQL-like language for filtering cloud cost data across providers for API and Terraform integrations.
The Vantage Query Language (VQL) is a SQL-like language for filtering cloud cost data. It includes a normalized schema across cloud providers and basic filter syntax for creating complex filters. VQL is available in the Vantage console, as part of the Vantage API, and within the Vantage Terraform provider.
Console. On Cost, Kubernetes Efficiency, Financial Commitment, and Network Flow Reports, as well as Virtual Tag filter configurations and Saved Filters, you can view and edit VQL directly in the filter builder. On Resource Reports, you can view and copy VQL.
API. On supported endpoints, such as /cost_reports, /resource_reports, /financial_commitment_reports, /kubernetes_efficiency_reports, and /network_flow_log_reports, you can use VQL in the filter parameter to programmatically create and fetch reports.
Terraform provider. In supported Terraform resources, such as vantage_saved_filter or vantage_cost_report, you can use VQL for the filter argument to create filtered Cost Reports or saved filters.
On supported reports and filter configurations, you can edit VQL directly within the Vantage console. This allows you to modify filter logic as code—making it faster to adjust complex filters, reuse queries across reports and Virtual Tags, and iterate on cost analysis without rebuilding filters from scratch.
Open the Filters menu. Create a filter or view an existing one.
3
At the top of the Filters menu, click View as VQL to see the current filter represented in VQL.
4
Click Edit VQL. The VQL text becomes editable.
5
Modify the VQL query as needed. You can adjust filter conditions, add or remove criteria, or paste in VQL from another source, such as a different report or a Terraform configuration.
6
Click Apply. Vantage validates the query and updates the filter configuration. If the VQL contains errors, an error message is displayed, and the filter is not updated until the query is corrected.
You can also use the VQL view to copy filter logic between different parts of Vantage. For example, copy VQL from a Cost Report and paste it into a Virtual Tag filter configuration to reuse the same filter criteria.
You can switch between the visual filter builder and the VQL editor at any time. Changes made in one view are reflected in the other.
To edit VQL in reports, you need editor or higher permissions and access to the report. To edit VQL in Virtual Tags, you must have the Owner role.
The below example shows how to use VQL on both the API and the Terraform provider. This example creates a saved filter in your Vantage account using VQL.
API
Terraform Provider
curl --request POST \ --url https://api.vantage.sh/v2/saved_filters \ --header 'content-type: application/json' \ --header 'authorization: Bearer <ACCESS_TOKEN>' \ --data @- <<EOF { "filter": "(costs.provider = 'aws' AND costs.service = 'Amazon Relational Database Service') OR (costs.provider = 'gcp' AND costs.service = 'Cloud SQL')", "title": "RDS and Cloud SQL", "workspace_token": "wrkspc_abcde12345" } EOF
resource "vantage_saved_filter" "rds_cloud_sql" { title = "RDS and Cloud SQL" filter = "(costs.provider = 'aws' AND costs.service = 'Amazon Relational Database Service') OR (costs.provider = 'gcp' AND costs.service = 'Cloud SQL')" workspace_token = "wrkspc_abcde1234" }
VQL is based on the following key concepts, further described in subsequent sections.
Schema
Keywords
Syntax
VQL uses a schema that organizes filters into namespaces. These namespaces comprise various fields that you can leverage to filter and retrieve specific cost-related data.
VQL includes keywords, like AND, OR, IN, LIKE, and NOT, to create complex and precise filter conditions. These keywords vary per report type/scope.
VQL syntax closely resembles the WHERE clause of a SQL query. You can construct filter operations to extract desired cost insights.
VQL has a separate scope for each type of report—meaning that you cannot use VQL statements for Cost Reports when querying Resource Reports. See the following pages to learn more about each VQL scope.
