query-spec

name: query-spec description: "Filters, selects, and sorts Control Plane resources with the query spec language. Use when the user asks about targetQuery, memberQuery, cpln query commands, tag-based selection, property filtering, or dynamic location selection."

Query Spec — Filtering & Selecting Resources

Control Plane has one query language used in two ways: ad-hoc filtering of a resource list (CLI / API), and dynamic targeting embedded inside three resource fields.

Where	Field / command	Purpose
Policy	`targetQuery`	Target resources by tag/property instead of listing `targetLinks` (see access-control)
Group	`memberQuery`	Assign members dynamically — users only
GVC	`spec.staticPlacement.locationQuery`	Select locations dynamically instead of listing `locationLinks`
CLI	`cpln KIND query`	Ad-hoc filtering — every resource kind
API	`POST /org/ORG/KIND/-query`	Ad-hoc filtering — every resource kind

Not an MCP list parameter. list_resources has no filter argument (list a kind, then filter the table yourself); query_audit_events filters by kind/name/subject/context/time; query_metrics takes PromQL. The query spec appears only inside the three resource fields above, set when you create or update that resource.

Structure

kind: workload          # resource kind being selected
fetch: items            # "items" (objects, default) or "links" (references)
spec:
  match: all            # "all" (default), "any", or "none"
  terms:
    - op: "="
      tag: environment
      value: production
    - op: exists
      tag: monitored
  sort:
    by: name
    order: asc

Terms

Each term targets exactly one of three fields (mutually exclusive — the schema rejects a term that sets more than one):

Field	Targets	Example
`tag`	Resource tags (key/value labels)	`tag: environment`, `value: production`
`property`	Built-in properties (`name`, `description`, `status.phase`, …)	`property: name`, `value: my-app`
`rel`	Relationships to other resources	`rel: gvc`, `value: my-gvc`

Operators

Operator	Needs `value`	Meaning
`=`	yes	Equal (default when `op` is omitted)
`!=`	yes	Not equal
`>` `>=` `<` `<=`	yes	Numeric / date comparison
`~`	yes	Pattern match (schema op name `match`)
`=~`	yes	Regex match (schema op name `regex`)
`contains`	yes	Substring match
`exists`	no	Tag/property is present (any value)
`!exists`	no	Tag/property is absent

value accepts a string, number, boolean, or ISO date. Boolean values are auto-converted to strings on tag terms only — store monitored=true and you must query value: "true", not value: true, or it silently matches nothing.

Match modes

Mode	Behavior
`all`	Every term must match (default)
`any`	At least one term matches
`none`	No term may match

Sorting

sort:
  by: name            # required
  order: asc          # "asc" (default) or "desc"

Sort is API- and manifest-only — the cpln KIND query CLI has no sort flag, so a sort directive passed there is ignored.

Common fields (most kinds): id, name, version, description, created, lastModified. Kind-specific: location adds origin/provider/region; cloudaccount adds provider; user adds idp/email; policy and group add origin.

CLI

Ad-hoc filtering — every kind supports query:

cpln workload query --tag environment=production
cpln workload query --match all --tag environment=production --tag region=europe
cpln workload query --rel gvc=my-gvc
cpln policy query --prop name=my-policy
cpln workload query --tag monitored                       # existence (no value)
cpln workload query --match any --rel gvc=one --rel gvc=two

Flag	Alias	Notes
`--match`		`all` / `any` / `none` (default `all`); single value
`--tag`		`KEY=VALUE`, or `KEY` for existence; repeatable
`--property`	`--prop`	`KEY=VALUE`; repeatable
`--rel`		`KEY=VALUE`; repeatable

Results cap at 50 by default — raise with --max 0 for all records.

Authoring dynamic targeting — gvc, policy, and group create/update commands embed a query via --query-match, --query-tag, --query-property, --query-rel (group also --query-kind user):

cpln policy create --name img-policy --query-kind image --query-property repository=my-app ...

API

POST https://api.cpln.io/org/ORG/workload/-query

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

Dynamic targeting examples

Policy targetQuery — applies to matching resources, including ones created later:

kind: policy
targetKind: image
targetQuery:
  spec:
    terms:
      - { property: repository, value: my-app }
bindings:
  - permissions: [pull, view]
    principalLinks: [//group/developers]

Group memberQuery — dynamic membership by user tag (users only; service accounts must be added via memberLinks):

kind: group
memberQuery:
  kind: user
  spec:
    terms:
      - { tag: "firebase/sign_in_provider", value: "microsoft.com" }

Defaults & gotchas

Omitted op defaults to =; omitted match defaults to all; omitted fetch defaults to items; omitted sort order defaults to asc.
Boolean tag values become strings — query "true", not true.
targetQuery is retroactive: tag a new resource and matching policies cover it automatically — a scope to watch when granting permissions.
memberQuery ignores service accounts.

access-control (policy targetQuery / group memberQuery in context) · cpln (CLI command surface).