VQL for Virtual Tags

Virtual Tags use VQL to determine which costs receive a value or allocation. Virtual Tag filters use the same costs and tags schema, keywords, and syntax as Cost Reports.

To build a Virtual Tag filter in the console, navigate to the Tags page, create or edit a Virtual Tag, and add a value. In an input or output costs filter, click View as VQL, then Edit VQL, to edit the query directly.

You must have the Organization Owner role to edit Virtual Tag VQL in the console.

Where Virtual Tags Use VQL

A Virtual Tag configuration can contain VQL in the following locations:

Location	API or Terraform field	Purpose
Value output filter	`values[].filter`	Identifies the costs that receive a custom value or that are allocated using a business metric, cost metric, or percentages
Cost-based input filter	`values[].cost_metric.filter`	Identifies the input costs used to calculate the allocation percentages
Collapsed tag key filter	`collapsed_tag_keys[].filter`	Limits the costs for which values from a collapsed tag key are copied into the Virtual Tag

The API examples on this page are request bodies for POST /v2/virtual_tag_configs. The order of objects in values determines precedence among value filters. When more than one value filter matches a cost, Vantage applies the first matching value. Value filters also take precedence over collapsed tag keys.

Schema

The schema below is the same one used for Cost Reports. VQL comprises two namespaces: costs and tags, which represent the available filters on Cost Reports in the Vantage console. Reference a filter as namespace.field, such as costs.provider or tags.name.

Availability of the fields listed below 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.

Namespace	Field	Description	Example
`costs`	`provider` (optional)	Provider that generated the cost	Filter across all providers or combine providers
`costs`	`allocation`	Fraction of a cost allocated to the result	Cost allocation
`costs`	`region`	Provider region associated with the cost	Regions
`costs`	`marketplace`	Whether an AWS cost is a Marketplace transaction	Marketplace transactions
`costs`	`account_id`	Resource account, project, or subscription identifier	Account ID
`costs`	`provider_account_id`	Billing account identifier	Provider account ID
`costs`	`service`	Normalized provider service name	Service
`costs`	`category`	Normalized cost category	Category
`costs`	`subcategory`	Provider-specific cost subcategory	Subcategory
`costs`	`resource_id`	Provider identifier for a resource	Resource ID
`costs`	`charge_type`	Normalized charge type, such as usage or credit	Charge type
`costs`	`usage_unit`	Unit used to measure usage	Usage unit
`tags`	`name`	Provider or Virtual Tag key	Tags
`tags`	`value`	Value associated with a tag key	Untagged costs

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.

Keywords

The keywords below are the same ones used for Cost Reports. 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 = 'Amazon Elastic Compute Cloud - Compute'`	This example filters AWS costs for the Amazon Elastic Compute Cloud - Compute 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.
`!~*`	Negated 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.

With these keywords, you can construct complex filter conditions in VQL, providing flexibility and precision when querying and analyzing cloud cost data.

Syntax

The syntax below is the same one used for Cost Reports. 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 ('123456789012'))

Value Output Filters

Every object in values requires a filter. For a custom value, the filter identifies the costs assigned that value. For business metric, cost-based, and percent-based values, it identifies the output costs to allocate. The following examples map AWS accounts to team values. Because Platform appears first, it takes precedence if the filters overlap.

API
Terraform

{
  "key": "Team",
  "overridable": false,
  "values": [
    {
      "name": "Platform",
      "filter": "costs.provider = 'aws' AND costs.account_id IN ('111111111111', '222222222222')"
    },
    {
      "name": "Data",
      "filter": "costs.provider = 'aws' AND costs.account_id = '333333333333'"
    }
  ]
}

resource "vantage_virtual_tag_config" "team" {
  key         = "Team"
  overridable = false

  values = [
    {
      name   = "Platform"
      filter = "costs.provider = 'aws' AND costs.account_id IN ('111111111111', '222222222222')"
    },
    {
      name   = "Data"
      filter = "costs.provider = 'aws' AND costs.account_id = '333333333333'"
    }
  ]
}

Business Metric and Percentage Output Filters

Business metric and percent-based values also use values[].filter as their output costs filter:

API
Terraform

{
  "key": "Allocated Team",
  "overridable": false,
  "values": [
    {
      "business_metric_token": "bsnss_mtrc_1234",
      "label_key": "team",
      "filter": "costs.provider = 'aws' AND costs.service = 'Amazon Elastic Compute Cloud - Compute'"
    },
    {
      "display_name": "Shared support",
      "filter": "costs.provider = 'aws' AND costs.service = 'AWS Support (Business)'",
      "percentages": [
        { "value": "Platform", "pct": 60 },
        { "value": "Data", "pct": 40 }
      ]
    }
  ]
}

resource "vantage_virtual_tag_config" "allocated_team" {
  key         = "Allocated Team"
  overridable = false

  values = [
    {
      business_metric_token = "bsnss_mtrc_1234"
      label_key             = "team"
      filter                = "costs.provider = 'aws' AND costs.service = 'Amazon Elastic Compute Cloud - Compute'"
    },
    {
      display_name = "Shared support"
      filter       = "costs.provider = 'aws' AND costs.service = 'AWS Support (Business)'"
      percentages = [
        { value = "Platform", pct = 60 },
        { value = "Data", pct = 40 }
      ]
    }
  ]
}

label_key selects the label column whose values become the tag values, and it’s required for business metrics that support named label columns. Business metrics created before multiple label columns were supported use a single label column; omit label_key for those metrics, because Vantage rejects it.

Normalize Values Across Tag Keys

Use a value filter to map inconsistent provider tag keys to one Virtual Tag value. Repeat the provider condition in each OR branch so each branch forms a complete filter set:

(costs.provider = 'aws' AND tags.name = 'environment' AND tags.value = 'production') OR (costs.provider = 'aws' AND tags.name = 'env' AND tags.value = 'prod') OR (costs.provider = 'aws' AND tags.name = 'stage' AND tags.value = 'production')

Cost-Based Allocation Filters

A cost-based value uses two VQL filters:

values[].filter selects the output costs to allocate.
values[].cost_metric.filter selects the input costs used to calculate the allocation percentages.

For most cost-based allocations, include costs.charge_type = 'Usage' in the input filter so credits, taxes, and fees do not affect the allocation.

API
Terraform

{
  "key": "Team",
  "overridable": false,
  "values": [
    {
      "display_name": "Allocate shared infrastructure",
      "filter": "costs.provider = 'aws' AND costs.service = 'Amazon Elastic Compute Cloud - Compute'",
      "cost_metric": {
        "filter": "costs.provider = 'aws' AND costs.charge_type = 'Usage' AND tags.name = 'team'",
        "aggregation": {
          "tag": "team"
        }
      }
    }
  ]
}

resource "vantage_virtual_tag_config" "team_allocation" {
  key         = "Team"
  overridable = false

  values = [
    {
      display_name = "Allocate shared infrastructure"
      filter       = "costs.provider = 'aws' AND costs.service = 'Amazon Elastic Compute Cloud - Compute'"
      cost_metric = {
        filter = "costs.provider = 'aws' AND costs.charge_type = 'Usage' AND tags.name = 'team'"
        aggregation = {
          tag = "team"
        }
      }
    }
  ]
}

Collapsed Tag Key Filters

Tag Key Collapsing copies the values of an existing tag key, either a provider tag or another Virtual Tag, into this Virtual Tag. Use collapsed_tag_keys[].filter to restrict which costs are eligible. When filter is set, do not also set providers. Put provider restrictions directly in the VQL filter. If you need only provider-level scoping and no other conditions, use providers instead of filter. Collapsed tag keys follow these precedence rules:

If a value filter and a collapsed tag key both match a cost, the value filter’s value is applied.
If more than one collapsed tag key matches a cost, the key listed first is applied.

API
Terraform

{
  "key": "Environment",
  "overridable": false,
  "collapsed_tag_keys": [
    {
      "key": "environment",
      "filter": "costs.provider = 'aws' AND costs.account_id IN ('111111111111', '222222222222')"
    },
    {
      "key": "env",
      "filter": "costs.provider = 'gcp'"
    }
  ]
}

resource "vantage_virtual_tag_config" "environment" {
  key         = "Environment"
  overridable = false

  collapsed_tag_keys = [
    {
      key    = "environment"
      filter = "costs.provider = 'aws' AND costs.account_id IN ('111111111111', '222222222222')"
    },
    {
      key    = "env"
      filter = "costs.provider = 'gcp'"
    }
  ]
}

Nested Virtual Tags

To reference an existing Virtual Tag, use its key and value with the tags namespace, just as you would use a provider tag:

costs.provider = 'aws' AND tags.name = 'Environment' AND tags.value = 'Production'

This example can be used as the output filter for a second Virtual Tag. Vantage evaluates nested tags in dependency order. Nested Virtual Tags cannot contain cyclical references, such as Tag A referencing Tag B while Tag B references Tag A. A filter that references the Virtual Tag’s own key isn’t a cycle; it matches the provider tag with the same key. If a nested relationship includes cost allocation, every referenced allocated tag must belong to the same provider-specific allocation chain. See Nested Virtual Tags for configuration details and limitations.

Performance Guidelines

Scope a filter to the providers it needs. A filter without costs.provider is evaluated against every connected provider.
Prefer exact matches with = and IN over LIKE, NOT LIKE, ~*, and !~*.
When a filter applies to only a few providers, use a complete provider-specific expression in each OR branch.
Put high-volume value rules first so most costs match early.

See Best Practices for Filtering Across All Providers for more guidance.

Troubleshooting

Wrap string values in single quotes, not double quotes.
Do not use a saved filter to define a Virtual Tag value. Enter or paste the VQL expression directly.
Do not combine providers and filter on the same collapsed tag key.
If multiple value filters match the same cost, reorder the values so the intended value appears first.
If a nested tag fails validation, check for a cyclical reference between tags or a reference to an allocated tag outside the same provider-specific allocation chain.
costs.provider IN (...) is supported, but costs.provider NOT IN (...) is not.
For invalid VQL, Vantage returns a filter: error. An invalid cost-based input filter returns a cost metrics filter: error.

Get Started

Account & Security

AI, Terraform, & Developer Tools

Provider Integrations

App Integrations

Revenue & Finance Integrations

Cost Reporting Features

Financial Planning Features

VQL for Virtual Tags

Where Virtual Tags Use VQL

Schema

Keywords

Syntax

Value Output Filters

Business Metric and Percentage Output Filters

Normalize Values Across Tag Keys

Cost-Based Allocation Filters

Collapsed Tag Key Filters

Nested Virtual Tags

Performance Guidelines

Troubleshooting

​Where Virtual Tags Use VQL

​Schema

​Keywords

​Syntax

​Value Output Filters

​Business Metric and Percentage Output Filters

​Normalize Values Across Tag Keys

​Cost-Based Allocation Filters

​Collapsed Tag Key Filters

​Nested Virtual Tags

​Performance Guidelines

​Troubleshooting

Where Virtual Tags Use VQL

Schema

Keywords

Syntax

Value Output Filters

Business Metric and Percentage Output Filters

Normalize Values Across Tag Keys

Cost-Based Allocation Filters

Collapsed Tag Key Filters

Nested Virtual Tags

Performance Guidelines

Troubleshooting