Query

Clients and items can select/filter other items with the help of queries. Queries utilize 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 can dynamically assign users
Policy can target items or principals with queries
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.

Console UI
CLI
API

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:

Click on 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 on 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 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 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`	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:

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

Documentation

Quickstart

Concepts

Core

Reference

Filtering

Sorting

Sort Order

Common Sort Fields

Resource-Specific Sort Fields

Documentation

Quickstart

Concepts

Core

Reference

​Filtering

​Sorting

​Sort Order

​Common Sort Fields

​Resource-Specific Sort Fields

Filtering

Sorting

Sort Order

Common Sort Fields

Resource-Specific Sort Fields