Documentation Index
Fetch the complete documentation index at: https://docs.vantage.sh/llms.txt
Use this file to discover all available pages before exploring further.
Cost Reports VQL Schema
VQL comprises two namespaces:costs and tags, which represent the available filters on Cost Reports in the Vantage console. To reference a filter, use the following syntax: namespace.field (e.g., costs.provider or tags.name).
| Namespace | Field | VQL Example |
|---|---|---|
costs | provider (optional) | Filter across all providers or combine specific providers |
costs | allocation | Cost allocation example |
costs | region | Region example |
costs | marketplace | Marketplace example |
costs | account_id | Account ID example |
costs | provider_account_id | Provider account ID example |
costs | service | Service example |
costs | category | Category example |
costs | subcategory | Subcategory example |
costs | resource_id | Resource example |
costs | charge_type | Charge Type example |
tags | name | Tags name/value example |
tags | value | Untagged example |
costs.provider is optional. Omit it to filter across every connected provider in a single query—see Filter Across All Providers. Provider-specific fields (such as AWS costs.marketplace) only apply when costs.provider is included for that provider.Availability of the fields listed above varies among different cloud providers. For a comprehensive list of available fields per provider, including the source billing field each one maps to, see the Data Dictionary.
Keywords
VQL includes a set of keywords to create complex filter conditions. These keywords function similar to their SQL equivalents.| Keyword | Description | VQL Sample | Explanation |
|---|---|---|---|
AND | Logical AND operator | costs.provider = 'aws' AND costs.service = 'EC2' | This example filters AWS costs for the EC2 service, where both conditions must be true. |
OR | Logical OR operator | costs.provider = 'azure' OR costs.provider = 'aws' | This example retrieves costs from either Azure or AWS. At least one condition must be true. |
IN | Used to compare against an array list | costs.provider = 'azure' AND costs.account_id IN ('account-1', 'account-2') | This example filters based on a list of account IDs, returning data for the specified accounts. You can also use IN along with a special syntax for filtering by multiple tags. See Filter by Multiple Tags for details. costs.provider IN (...) is supported and is expanded into one filter set per provider. costs.provider NOT IN (...) is not supported. |
LIKE | Performs string comparisons | costs.provider = 'gcp' AND tags.name = 'environment' AND tags.value LIKE '%prod%' | This example selects data where the tag value contains prod, such as production-1. |
NOT | Represents negation | costs.provider = 'aws' AND costs.region NOT IN ('us-east-1', 'us-east-2') | This example filters out data from both specified regions, providing all AWS costs not in these regions. Use NOT IN to specify a list of single or multiple values. You can also use the != or <> operators for “is not.” costs.provider = 'aws' AND costs.region != 'us-east-1' You can use NOT LIKE to perform string comparisons: costs.provider = 'gcp' AND tags.name = 'environment' AND tags.value NOT LIKE '%prod%' |
~* | Flexible match operator for tag values | costs.provider = 'aws' AND (tags.name = 'teams' AND tags.value ~* 'Team A') | Searches for all items where the tag value loosely matches Team A, ignoring case, whitespace, hyphens, and punctuation. |
!~* | Does not flexible match operator for tag values | costs.provider = 'aws' AND (tags.name = 'teams' AND tags.value !~* 'Team A') | Filters out all items where the tag value loosely matches Team A, ignoring case, whitespace, hyphens, and punctuation. |
Syntax
You can think of VQL in its current iteration as theWHERE clause of a SQL query. By combining the schema and keywords above with parentheses, you can form complex filter operations, such as:
VQL Examples
The following examples cover common use cases for VQL.Filter Across All Providers
You can omitcosts.provider to filter across every connected provider in a single query. This is useful for multi-cloud questions where the same filter logic should apply regardless of where the cost was incurred—for example, finding all costs tagged with a specific team across AWS, Azure, GCP, and any other connected providers.
costs.provider when you want to scope a filter to a single provider; this feature only removes the requirement to do so. Provider-specific fields (such as AWS-only costs.marketplace) still need costs.provider to be set for that provider.
An entirely empty filter (no rules at all) is also valid VQL and is equivalent to filtering across every connected provider with no constraints. This is the representation used for the default unfiltered All Resources Cost Report and for any other report whose filter set spans all providers with no rules applied. If you click View as VQL on such a report, the query string will be empty.
Filtering across all providers queries data from every connected provider, which is more work than filtering by a single provider. The impact is most pronounced on tag-heavy queries and Virtual Tag rules. For guidance on scoping providerless filters efficiently, including granular filters, exact-match operators, and when to prefer per-provider
OR over a fully providerless query, see Best Practices for Filtering Across All Providers in the Tagging documentation.Combining Providers
To reference a Custom Provider in VQL queries, navigate to the Integrations page. Use the displayed Provider ID (e.g.,
custom_provider:accss_crdntl_123a45bfdaf38765).Cost Allocation
Set cost allocation to0.5.
Costs from a List of Regions
Filter for Snowflake costs in two regions. Note that you will need to use the region code, such asus-east-1 in the case of AWS, or AWS_US_EAST_1 in the case of Snowflake, below.
Get Marketplace Transactions
Retrieve costs associated with the AWS Marketplace.Costs by Account ID
Costs for a specific set of services and account ID.Costs by Provider Account ID
The following example represents costs from a specific AWS billing account or costs from a specific Azure subscription.Per-Resource Costs and Costs by Service
Resource costs require bothprovider and service in addition to the resource_id.
Multiple Resource IDs
Costs by Specific Category
Filter costs to see a specific cost category. Category costs requireprovider, service, and category. To filter across all services, use costs.service = '*' as a wildcard.
Costs by Specific Subcategory
Filter costs by a specific service and subcategory. Subcategory costs requireprovider, service, and subcategory. To filter across all services, use costs.service = '*' as a wildcard.
Cost by Charge Type
Filter costs by a specific charge type.Filter by Tag
Filter by Single Tag
Filter costs based on a specific tag, such asenvironment, with the value production, in AWS.
Filter for Multiple Values from a Single Tag Key
If you want to filter for multiple tag values that are tied to one tag key (e.g., costs tagged with theteam tag of mobile and data), use the below syntax.
Filter by Multiple Tags
If you want to filter for resources that have more than one tag associated, you can use the syntax shown in the example below.environment tag with a value of staging as well as the team tag with a value of engineering. This filter is the same as creating the following manual filter in the console.
Filter for Matching Tags Using LIKE
Filter for Tags Using Flexible Matching
TeamA, team-a, and team_a to a single Team A tag value. See the Flexible Match documentation for details.
Filter for Untagged Resources
On providers that have a Not Tagged/Not Labeled filter option in the console, you can use the below VQL to see untagged resources across every connected provider.OR:
Troubleshooting
If you are receiving an error when trying to complete a query, check the following troubleshooting tips.- Each provider exposes certain names to the API. Those names are normalized within the schema. Check the Data Dictionary for normalized field names.
- Query parameter values should be wrapped in single quotes.
Click to view examples
Click to view examples
- Currently, there is a limitation where
ANDandORare not supported together in a single “query group.”
Click to view examples
Click to view examples
- The
costs.providerfield is optional. Omit it to filter across every connected provider in a single query, or include it to scope the filter to a specific provider. See Filter Across All Providers for details and performance considerations.
Click to view examples
Click to view examples
- Provider-specific fields only apply when
costs.provideris set for that provider. For example, AWS exposescosts.marketplace, but it has no effect when used without an AWS provider scope.
Click to view examples
Click to view examples
- The
costs.providerfield supportsIN(which is expanded into one filter set per provider), but does not supportNOT IN.
Click to view examples
Click to view examples
- Resource costs require both provider and service in addition to the resource ID.
Click to view examples
Click to view examples
- Category and subcategory costs also require provider and service. To filter across all services, use
costs.service = '*'as a wildcard.
Click to view examples
Click to view examples