VQL (Vantage Query Language)
Introduction
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 currently available as part of the Vantage API. On supported endpoints, such as /cost_reports
you can include VQL snippets in the filter
parameter to programmatically create and fetch cost reports.
For example, the following API call would create a saved filter in your Vantage account using VQL.
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 = 'kubernetes'",
"title": "RDS and Kubernetes",
"workspace_token": "wrkspc_abcde12345"
}
EOF
Schema
VQL contains two namespaces representative of the filters which are available in the Vantage console.
Namespace | Field |
---|---|
costs | provider allocation region marketplace account_id provider_account_id service category subcategory resource_id |
tags | name value |
Different providers have different fields available. For a full listing of available fields please consult the data dictionary.
Keywords
Keyword | Description |
---|---|
AND | Logical and |
OR | Logical or |
IN | Compare against array list |
LIKE | String comparison |
NOT | Negation |
Syntax
You can think of VQL in its current iteration as the WHERE
clause of a SQL query. By combining the schema and keywords above with parentheses you can form complex filter operations such as:
costs.provider = 'mongo' AND costs.allocation = 1.0 AND (costs.service = 'REALM' AND costs.resource_id IN ('s3')) OR (costs.provider = 'aws' AND costs.allocation = 1.0 AND costs.account_id IN ('123456798'))
Examples
The following examples cover common use cases for VQL.
Combining Providers
costs.provider = 'mongo' OR costs.provider = 'aws'
Cost Allocation
costs.allocation = 0.5
Per Resource Costs
Resource costs require both provider
and service
in addition to the resource_id
costs.provider = 'aws' AND costs.service = 'Amazon Relational Database Service' AND costs.resource_id = 'arn:aws:rds:us-east-1:123456789:db:primary-01'
costs.provider = 'aws' AND costs.service = 'Amazon Relational Database Service' AND costs.resource_id IN ('arn:aws:rds:us-east-1:123456789:db:primary-01', 'arn:aws:rds:us-east-1:123456789:db:primary-02')
Filtering by Tag
costs.provider = 'aws' AND tags.name = 'environment' AND tags.value = 'production'
Get Marketplace Transactions
costs.provider = 'aws' AND costs.marketplace = true