Skip to main content

VQL (Vantage Query Language)

info

Beta: VQL and the Vantage Write API (API V2) are currently in Beta.

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 vntg_tkn_826f419b7b78c693f874e8c48719beb9398dck37' \
     --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.

NamespaceField
costsprovider
allocation
region
marketplace
account_id
provider_account_id
service
category
subcategory
resource_id
tagsname
value

Different providers have different fields available. For a full listing of available fields please consult the data dictionary.

Keywords​

KeywordDescription
ANDLogical and
ORLogical or
INCompare against array list
LIKEString comparison
NOTNegation

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'))
info

Beta: Please contact support@vantage.sh or chat us with Intercom to request a list of values for filters in your account. We are currently working on a way to expose this information in the Vantage console.

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