Query - Control Plane

Queries allow clients and resources to filter and select other resources using 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 can dynamically assign users
Policies can target items or principals with queries
GVCs 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.

Console UI
CLI
API

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:

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

To remove the filter, click the Query button again and click Clear.

Every item kind supports a query command. Below are a few examples:

cpln workload query --match any --rel gvc=my-first-gvc --rel gvc=my-second-gvc

cpln workload query --match all --tag environment=production --tag region=europe

cpln workload query --match all --rel gvc=emea --tag payment-service=true --tag thisTagExists --tag version

See the CLI reference for the corresponding item kind for more details.

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:

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

See the API reference for the corresponding item kind for more details.

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:

Location

Field	Description
`origin`	Origin of the location
`provider`	Cloud provider (aws, gcp, azure)
`region`	Cloud region

Group

Field	Description
`origin`	Origin of the group

Cloud Account

Field	Description
`provider`	Cloud provider (aws, gcp, azure, ngs)

User

Field	Description
`idp`	Identity provider
`email`	User email address

Policy

Field	Description
`origin`	Origin of the policy

​Filtering

​Sorting

​Sort Order

​Common Sort Fields

​Resource-Specific Sort Fields

Filtering

Sorting

Sort Order

Common Sort Fields

Resource-Specific Sort Fields