> ## 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 Kubernetes Efficiency Reports

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

<Tip>
  If you need help constructing a VQL query, navigate to the [**Kubernetes Efficiency Reports**](https://console.vantage.sh/kubernetes/efficiency_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>

## Kubernetes Efficiency Reports VQL Schema

VQL for Kubernetes Efficiency Reports comprises one namespace, `kubernetes`, which represents the available [filters](/kubernetes#create-efficiency-reports) on Kubernetes Efficiency Reports in the Vantage console. To reference a filter, use the following syntax: `namespace.field` (e.g., `kubernetes.category`). The following fields are available within the `kubernetes` namespace.

| Namespace | Field | Description | VQL Example |
| - | - | - | - |
| `kubernetes` | `namespace` | Kubernetes namespace | [Namespace example](/vql_kubernetes_efficiency_report#multiple-namespaces) |
| `kubernetes` | `cluster_id` | Cluster identifier | [Cluster ID example](/vql_kubernetes_efficiency_report#results-from-a-list-of-clusters) |
| `kubernetes` | `category` | Efficiency category, such as cpu | [Category example](/vql_kubernetes_efficiency_report#costs-by-category) |
| `kubernetes` | `labels` | Kubernetes label key and value, selected with `->>` | [Labels example](/vql_kubernetes_efficiency_report#filter-by-label) |
| `kubernetes` | `pod` | Pod name | [Pod example](/vql_kubernetes_efficiency_report#filter-by-pod) |
| `kubernetes` | `region` | Cluster region | [Region example](/vql_kubernetes_efficiency_report#filter-by-region) |

### 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 | `(kubernetes.namespace = 'kube-system') AND (kubernetes.labels->>'app' = 'vantage-agent')` | This example filters for a specific namespace and label, where both conditions must be true. |
| `OR` | Logical OR operator | `(kubernetes.namespace = 'gpu-operator') OR (kubernetes.namespace = 'vantage-dev')` | This example looks for results in two different namespaces. At least one condition must be true. |
| `!=` | Is not | `(kubernetes.cluster_id != 'dev-eks-gpu-0')` | This example looks for results that are in any cluster except for `dev-eks-gpu-0`. |
| `IN` and `NOT IN` | Used to compare against an array/list | `(kubernetes.labels->>'app.kubernetes.io/component' IN ('csi-driver','gpu-operator','metrics'))` | This example searches for results with the `app.kubernetes.io/component` key and multiple values. <br /><br /> This same query also works for `NOT IN` where the results are anything matching the label key except for those particular values: `(kubernetes.labels->>'app.kubernetes.io/component' NOT IN ('csi-driver','gpu-operator','metrics'))`. |
| `LIKE` and `NOT LIKE` | Performs string comparisons | `(kubernetes.labels->>'app' LIKE '%test%')` | This example selects data where the `app` label value contains `test`, such as `test-app`. <br /><br /> This same query also works for `NOT LIKE` where data does not contain a particular string: `(kubernetes.labels->>'app' NOT LIKE '%test%')`. |
| `->>` | This operator is used only when constructing queries related to labels | `(kubernetes.labels->>'container' = 'kube-prometheus-stack-48.4.0')` | This example looks for results with the label name of `container` and value of `kube-prometheus-stack-48.4.0`. |

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

## Syntax

VQL resembles the `WHERE` clause of a SQL query. Use `->>` to select a Kubernetes label:

```sql theme={null}
kubernetes.cluster_id IN ('production-1', 'production-2') AND kubernetes.namespace = 'payments' AND kubernetes.labels->>'app' = 'api'
```

Use single quotes around string values.

## VQL Examples

The following examples cover common use cases for VQL.

### Multiple Namespaces

Filter for one or the other namespace.

```sql theme={null}
(kubernetes.namespace = 'kube-system') OR (kubernetes.namespace = 'default')
```

### Results from a List of Clusters

Filter for a list of different clusters.

```sql theme={null}
(kubernetes.cluster_id IN ('dev-eks-gpu-0','dev-eks-UVmPe9YN'))
```

### Costs by Category

Costs for a specific category, like `cpu`.

```sql theme={null}
(kubernetes.category = 'cpu')
```

### Filter by Label

Filter based on a specific Kubernetes label, such as `app`, with the value `rollouts-demo`.

```sql theme={null}
(kubernetes.labels->>'app' = 'rollouts-demo')
```

### Filter by Pod

Filter for a specific pod.

```sql theme={null}
(kubernetes.pod = 'my-pod-name')
```

### Filter by Region

Filter for clusters in multiple regions.

```sql theme={null}
kubernetes.region IN ('us-east-1', 'us-west-2')
```

### Multiple Filters

Complex filter that shows combining two different statements using `OR` with multiple criteria.

```sql theme={null}
((kubernetes.cluster_id IN ('dev-eks-gpu-0','dev-eks-UVmPe9YN')) AND (kubernetes.category = 'cpu')) OR ((kubernetes.cluster_id IN ('dev-eks-gpu-0','dev-eks-UVmPe9YN')) AND (kubernetes.category = 'gpu'))
```

### Real-World Examples

Find CPU costs for production API workloads:

```sql theme={null}
kubernetes.cluster_id IN ('production-1', 'production-2') AND kubernetes.category = 'cpu' AND kubernetes.labels->>'app' = 'api'
```

Find platform workloads running outside the primary region:

```sql theme={null}
kubernetes.namespace = 'platform' AND kubernetes.region != 'us-east-1' AND kubernetes.labels->>'team' = 'platform'
```

## Troubleshooting

* Wrap string values in single quotes, not double quotes.
* Use `kubernetes.labels->>'KEY'` to filter a label; `kubernetes.labels.KEY` is not valid VQL.
* Keep complete conditions together when mixing `AND` and `OR`; use parentheses to separate each branch.
* Use the cluster, region, category, and label values shown by **View as VQL**.


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