> ## 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.

# VQL for Financial Commitment Reports

> Learn how to use VQL when querying Financial Commitment Reports in the API or using the Terraform Provider.

<Tip>
  If you need help constructing a VQL query, navigate to the [**Financial Commitment Reports**](https://console.vantage.sh/financial_planning/financial_commitment_reports) page and click **New Report**. From the top left, open the **Filters** menu. Create a filter and click the **View as VQL** button at the top of the **Filters** menu to see a filter's VQL representation. You can copy this syntax to use within your API calls. You can also [edit VQL directly](/vql#edit-vql-in-the-console) and click **Apply** to update the filter.
</Tip>

## Financial Commitment Reports VQL Schema

VQL for Financial Commitment Reports comprises one namespace, `financial_commitments`, which represents the available [filters](/financial_commitment_reports#create-a-financial-commitment-report) on Financial Commitment Reports in the Vantage console. To reference a filter, use the following syntax: `namespace.field` (e.g., `financial_commitments.service`). The following fields are available within the `financial_commitments` namespace.

| Namespace | Field | Description | VQL Example |
| - | - | - | - |
| `financial_commitments` | `provider` | Cloud provider. Supported values are `aws`, `azure`, and `gcp`. This field is optional. Omit it to include all connected providers. | [Syntax](/vql_financial_commitment_report#syntax) |
| `financial_commitments` | `service` | Provider service name | [Service example](/vql_financial_commitment_report#financial-commitments-by-service) |
| `financial_commitments` | `resource_account_id` | Account that used the commitment, such as an AWS account, Azure subscription, or GCP project | [Account example](/vql_financial_commitment_report#financial-commitments-by-specific-account) |
| `financial_commitments` | `provider_account_id` | Provider billing account identifier | [Billing Account example](/vql_financial_commitment_report#financial-commitments-by-specific-billing-account) |
| `financial_commitments` | `commitment_type` | Type of financial commitment | [Commitment Type example](/vql_financial_commitment_report#see-specific-commitment-types) |
| `financial_commitments` | `commitment_id` | Commitment identifier, such as an AWS ARN, Azure benefit or reservation ID, or GCP consumption model ID | [Commitment ID example](/vql_financial_commitment_report#financial-commitments-by-commitment-id) |
| `financial_commitments` | `cost_type` | Charge type, such as Usage | [Charge Type example](/vql_financial_commitment_report#financial-commitments-by-charge-type) |
| `financial_commitments` | `cost_category` | Cost category | [Category example](/vql_financial_commitment_report#financial-commitments-by-category) |
| `financial_commitments` | `cost_sub_category` | Provider-specific cost subcategory | [Subcategory example](/vql_financial_commitment_report#financial-commitments-by-subcategory) |
| `financial_commitments` | `instance_type` | Instance type covered by the commitment. This field is not populated for GCP. | [Instance Type example](/vql_financial_commitment_report#financial-commitments-by-instance-types) |
| `financial_commitments` | `region` | Provider region | [Region example](/vql_financial_commitment_report#financial-commitments-by-region) |
| `financial_commitments` | `resource_tags` | Resource tag key and value, selected with `->>` | [Tags example](/vql_financial_commitment_report#financial-commitments-by-tags) |

### Keywords

VQL includes a set of keywords to create complex filter conditions. These keywords function similar to their SQL equivalents. The provider condition is optional. The examples below omit it and apply to all connected Financial Commitment Report providers.

| Keyword | Description | VQL Sample | Explanation |
| - | - | - | - |
| `AND` | Logical AND operator | `((financial_commitments.resource_tags->>'environment' = 'production') AND (financial_commitments.cost_type = 'Usage'))` | This example filters for a specific tag and charge type, where both conditions must be true. |
| `OR` | Logical OR operator | `((financial_commitments.service = 'AmazonEC2') OR (financial_commitments.service = 'Compute Engine'))` | This example returns either AWS EC2 or GCP Compute Engine results. At least one condition must be true. |
| `!=` | Is not | `(financial_commitments.cost_type != 'Credit')` | This example returns any charge type except for `Credit`. |
| `IN` and `NOT IN` | Used to compare against an array/list | `(financial_commitments.provider IN ('aws','azure'))` | This example limits the report to AWS and Azure. Use `NOT IN` to exclude the listed values. |
| `LIKE` and `NOT LIKE` | Performs string comparisons | `(financial_commitments.commitment_id LIKE '%reservationOrders%')` | This example selects Azure commitment IDs that contain `reservationOrders`. Use `NOT LIKE` to exclude matching values. |
| `->>` | This operator is used only when constructing queries related to tags | `(financial_commitments.resource_tags->>'environment' = 'staging')` | This example looks for results with the tag name of `environment` and value of `staging`. |

With these operators and keywords, you can construct complex filter conditions in VQL.

## Syntax

VQL resembles the `WHERE` clause of a SQL query. The provider condition is optional.

Omit `financial_commitments.provider` to query all connected providers:

```sql theme={null}
financial_commitments.cost_type = 'Usage'
```

To query a single provider, add its provider value:

```sql theme={null}
financial_commitments.provider = 'aws' AND financial_commitments.service = 'AmazonEC2' AND financial_commitments.region = 'us-east-1'
```

To query a subset of providers, use `IN`:

```sql theme={null}
financial_commitments.provider IN ('azure','gcp') AND financial_commitments.cost_type = 'Usage'
```

For provider-specific branches in an `OR` query, include the corresponding provider condition in each branch:

```sql theme={null}
(financial_commitments.provider = 'azure' AND financial_commitments.service = 'Virtual Machines') OR (financial_commitments.provider = 'gcp' AND financial_commitments.service = 'Compute Engine')
```

Use single quotes around string values. See [Provider Coverage](/financial_commitment_reports#provider-coverage) for the commitments and charge types available for each provider.

## VQL Examples

The following examples cover common use cases for VQL.

### Financial Commitments by Service

Filter for services across multiple providers.

```sql theme={null}
(financial_commitments.service IN ('AmazonEC2','Virtual Machines','Compute Engine'))
```

### Financial Commitments by Specific Account

Filter down to an individual account. The account is an AWS account, Azure subscription, or GCP project.

```sql theme={null}
(financial_commitments.resource_account_id = 'my-gcp-project')
```

### Financial Commitments by Specific Billing Account

Filter down to an individual billing account.

```sql theme={null}
(financial_commitments.provider = 'gcp' AND financial_commitments.provider_account_id = '00EE89-6CAE74-12345')
```

### See Specific Commitment Types

Filter out certain commitment types to see everything else.

```sql theme={null}
(financial_commitments.commitment_type NOT IN ('credit','free'))
```

### Financial Commitments by Commitment ID

See the impact of a specific GCP committed use discount by its consumption model ID.

```sql theme={null}
(financial_commitments.provider = 'gcp' AND financial_commitments.commitment_id = '70D7-D1AB-12A4')
```

### Financial Commitments by Charge Type

See only usage-related commitments.

```sql theme={null}
(financial_commitments.cost_type = 'Usage')
```

### Financial Commitments by Category

All data transfer-related commitments.

```sql theme={null}
(financial_commitments.provider = 'aws' AND financial_commitments.cost_category = 'Data Transfer')
```

### Financial Commitments by Subcategory

Filter for Cloudfront and data transfer egress in APN2.

```sql theme={null}
(financial_commitments.provider = 'aws' AND financial_commitments.cost_sub_category IN ('APN2-DataTransfer-Out-Bytes','APN2-CloudFront-Out-Bytes'))
```

### Financial Commitments by Instance Types

Filter from a list of different instance types.

```sql theme={null}
(financial_commitments.provider = 'aws' AND financial_commitments.instance_type IN ('c7a.12xlarge','c7gn.large','c7gn.medium'))
```

<Note>
  The `instance_type` field is not populated for GCP.
</Note>

### Financial Commitments by Region

See all financial commitments in `us-east-1`.

```sql theme={null}
(financial_commitments.region = 'us-east-1')
```

### Financial Commitments by Tags

Filter based on an `environment` tag and a list of provided values.

```sql theme={null}
(financial_commitments.resource_tags->>'environment' IN ('production','staging'))
```

### Multiple Filters

Combine provider-specific statements using `OR`.

```sql theme={null}
(financial_commitments.provider = 'azure' AND financial_commitments.resource_account_id = 'e4631eaa-c721-42c0-9a40-24435bc1f9b0' AND financial_commitments.service = 'Virtual Machines') OR (financial_commitments.provider = 'gcp' AND financial_commitments.resource_account_id = 'my-gcp-project' AND financial_commitments.service = 'Compute Engine')
```

### Real-World Examples

Find EC2 usage commitments for an account in `us-east-1`:

```sql theme={null}
financial_commitments.provider = 'aws' AND financial_commitments.service = 'AmazonEC2' AND financial_commitments.resource_account_id = '123456789012' AND financial_commitments.cost_type = 'Usage' AND financial_commitments.region = 'us-east-1'
```

Find production commitments that are not credits across all connected providers:

```sql theme={null}
financial_commitments.cost_type != 'Credit' AND financial_commitments.resource_tags->>'environment' = 'production'
```

## Troubleshooting

* Wrap string values in single quotes, not double quotes.
* Omit `financial_commitments.provider` to include all connected Financial Commitment Report providers.
* Use `financial_commitments.provider = 'aws'`, `financial_commitments.provider = 'azure'`, or `financial_commitments.provider = 'gcp'` to scope a query to one provider.
* For provider-specific `OR` branches, include the corresponding provider condition in each branch.
* Use `financial_commitments.resource_tags->>'KEY'` to filter a tag.
* Keep complete conditions together when mixing `AND` and `OR`; use parentheses to separate each branch.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.