> ## Documentation Index
> Fetch the complete documentation index at: https://controlplanecorporation-kyle-cron-and-quotas.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Query

> Filter and select resources using tags, properties, and relations. Used by groups, policies, and GVCs for dynamic resource targeting and membership.

Queries allow clients and resources to filter and select other resources using [tags](/core/misc#tags), item `properties`, or item `relations`.

Queries also support sorting resource lists by property in ascending or descending order.

Examples of resources that use queries:

* [Groups](/reference/group) can dynamically assign users
* [Policies](/reference/policy) can target items or principals with queries
* [GVCs](/reference/gvc) can dynamically update assigned locations

***

## Filtering

A query consists of one or more terms that target tags, properties, or relations (`rel`).

For a `rel` term, the value depends on the resource kind. For example, workloads have a `gvc` relation, which allows you to filter workloads in an org by the GVC they belong to.

<Tabs>
  <Tab title="Console UI">
    In the Console, each page that lists items of a kind has a query button at the top of the table.

    The `Match Tags By` selector values are:

    | Selector | Definition                  |
    | :------- | :-------------------------- |
    | All      | All tag items must match    |
    | Any      | At least one tag must match |
    | None     | No tag items may match      |

    To filter resources based on their tags:

    1. Click the `Query` button
    2. Select which term you want to target: tag, property, or rel
    3. Type a value for the selected term key
    4. Select the operator and type the term value if needed
    5. Click `Apply` and the filtered resources will be displayed

    To remove the filter, click the `Query` button again and click `Clear`.
  </Tab>

  <Tab title="CLI">
    Every item kind supports a query command. Below are a few examples:

    ```bash theme={null}
    cpln workload query --match any --rel gvc=my-first-gvc --rel gvc=my-second-gvc
    ```

    ```bash theme={null}
    cpln workload query --match all --tag environment=production --tag region=europe
    ```

    ```bash theme={null}
    cpln workload query --match all --rel gvc=emea --tag payment-service=true --tag thisTagExists --tag version
    ```

    See the [CLI reference](/cli-reference/overview) for the corresponding item kind for more details.
  </Tab>

  <Tab title="API">
    Every item kind supports an API request path that ends with `/-query` and accepts `POST` as the HTTP method. Below are a few examples:

    ```text theme={null}
    https://api.cpln.io/org/myorg/workload/-query
    ```

    ```text theme={null}
    https://api.cpln.io/org/myorg/agent/-query
    ```

    Here is an example request body for querying with the API:

    ```json theme={null}
    {
      "spec": {
        "match": "all",
        "terms": [
          { "op": "=", "tag": "region", "value": "emea" },
          { "rel": "gvc", "op": "=", "value": "mygvc" }
        ],
        "sort": { "by": "name", "order": "asc" }
      }
    }
    ```

    See the [API reference](/api-reference/api) for the corresponding item kind for more details.
  </Tab>
</Tabs>

***

## Sorting

When fetching a list of items, you can sort by various properties in ascending or descending order.

### Sort Order

| Order  | Description                                         |
| :----- | :-------------------------------------------------- |
| `asc`  | Ascending order (A-Z, oldest first, lowest first)   |
| `desc` | Descending order (Z-A, newest first, highest first) |

### Common Sort Fields

The following sort fields are available for most resources:

| Field          | Description                 |
| :------------- | :-------------------------- |
| `id`           | Unique resource identifier  |
| `name`         | Resource name               |
| `version`      | Resource version number     |
| `description`  | Resource description        |
| `created`      | Creation timestamp          |
| `lastModified` | Last modification timestamp |

### Resource-Specific Sort Fields

Some resources have additional sort fields:

<AccordionGroup>
  <Accordion title="Location" icon="location-dot">
    | Field      | Description                      |
    | :--------- | :------------------------------- |
    | `origin`   | Origin of the location           |
    | `provider` | Cloud provider (aws, gcp, azure) |
    | `region`   | Cloud region                     |
  </Accordion>

  <Accordion title="Group" icon="users">
    | Field    | Description         |
    | :------- | :------------------ |
    | `origin` | Origin of the group |
  </Accordion>

  <Accordion title="Cloud Account" icon="cloud">
    | Field      | Description                           |
    | :--------- | :------------------------------------ |
    | `provider` | Cloud provider (aws, gcp, azure, ngs) |
  </Accordion>

  <Accordion title="User" icon="user">
    | Field   | Description        |
    | :------ | :----------------- |
    | `idp`   | Identity provider  |
    | `email` | User email address |
  </Accordion>

  <Accordion title="Policy" icon="shield-check">
    | Field    | Description          |
    | :------- | :------------------- |
    | `origin` | Origin of the policy |
  </Accordion>
</AccordionGroup>