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.

Related

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