Skip to main content

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.

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

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