> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/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.

Clients and items can select/filter other items with the help of queries. Queries utilize [tags](/core/misc#tags), `properties` of an item or the `relations` of it to execute.

Query is also used for sorting items when fetching a list of items, by any property and by ascending or descending order.

Some examples of items that use queries:

* [Group](/reference/group) can dynamically assign users
* [Policy](/reference/policy) can target items or principals with queries
* [GVC](/reference/gvc) can dynamically update its assigned locations

***

## Filtering

A query consists of terms, each term can target tags, properties or relations (`rel`).

For `rel` term, the value depends on the kind. For example, workload has `gvc` rel, 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 on top of the table.

    The `Match Tags By` selector values are:

    | Selector | Definition                      |
    | :------- | :------------------------------ |
    | All      | All tag items should match      |
    | Any      | Any of the tags should match    |
    | None     | None of these tags should match |

    To filter resources based on their tags:

    1. Click on 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 on 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 [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:

    ```
    https://api.cpln.io/org/myorg/workload/-query
    ```

    ```
    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 [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`           | Resource unique 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>