Skip to main content

Query Language

The Catalog exposes a query language to express filters that go beyond the simple label= and field= query parameters of the REST API. Queries are written as JSON, sent to the API through the rawq query parameter (URL-safe base64 encoded), and used internally by Views, Scorecards, and Campaigns to declare their scope.

This page describes the grammar of the query language and gives concrete examples.

tip

The full JSON schema describing the Catalog query language is available to download.

Where it is used​

  • rawq API parameter on any list endpoint, for ad-hoc queries.
  • Scope of a View.
  • Scope of a Scorecard or a Campaign.

The same JSON shape is accepted everywhere; the only thing that differs is how it is transported (encoded as a query string for rawq, or stored verbatim on the catalog object for scopes).

Query shape​

A query is one of four node types:

NodePurpose
Field predicateTest the value of one field on the item.
andLogical AND of two or more sub-queries.
orLogical OR of two or more sub-queries.
relatedSelect items that are related to a given item through a relationship type.

The same query can mix all four nodes freely, with the following limits applied by the server:

  • at most 20 sub-queries per and / or node,
  • at most 6 levels of nesting,
  • at most 3 related nodes per query,
  • decoded JSON must not exceed roughly 4 KiB.

Field predicates​

A field predicate has the shape:

{ "<json-path>": { "<operator>": <value> } }

Supported operators:

OperatorApplies toMeaning
eqany primitiveequal to
notEqany primitivenot equal to
gt, gte, lt, ltenumbersnumeric comparison
containsarraysthe array contains the given primitive
notContainsarraysthe array does not contain the given primitive
matchesstringsmatches a regex of the form /pattern/[i]
existsany fieldfield is present (true) / absent (false)

Field paths reach into items with dot notation, the same way the simpler field= parameter does: e.g. metadata.name, metadata.labels.env, spec.registry. Predicates on spec.* fields require that those fields are declared as selectable on the item's ITD.

Logical composition​

and and or group one or more predicates:

{ "and": [ <query>, <query>, ... ] }
{ "or":  [ <query>, <query>, ... ] }

The related operator selects items that are connected to a given item through a relationship type:

{
  "related": {
    "type": "<RelationshipType URN>",
    "as":   "source" | "target",
    "where": { "ref": "<item URN>" }
  }
}
  • type is the URN of the RelationshipType (see Relationships).
  • as declares the role the matched item plays in the relationship: source means "match items that are the source of a relationship pointing to where.ref"; target means "match items that are the target of a relationship coming from where.ref".
  • where.ref is the URN of the other endpoint.

For example, "all items owned by the team platform-team" — i.e. items that are the target of an ownership relationship whose source is platform-team:

{
  "related": {
    "type": "urn:mia-platform-catalog:mia-platform.eu:v1alpha1:RelationshipType:ownership.mia-platform.eu",
    "as":   "target",
    "where": { "ref": "urn:mia-platform-catalog:mia-platform.eu:v1:Team:platform-team" }
  }
}

Example: complex query​

A non-trivial query that combines AND / OR and a regex:

{
  "and": [
    { "spec.registry":  { "eq": "nexus.mia-platform.eu" } },
    { "spec.replicas":  { "gt": 0 } },
    {
      "or": [
        { "metadata.labels.env": { "eq": "production" } },
        { "metadata.tags":       { "contains": "critical" } }
      ]
    },
    { "metadata.name": { "matches": "/^api-.*/i" } }
  ]
}

To send this as rawq, URL-safe base64-encode the JSON and pass it:

GET /stable.example.com/v1/items/dockerimages?rawq=<base64-of-the-JSON-above>

Relationship with label= and field=​

rawq is a superset of the simpler parameters:

  • label=<key>=<value> is equivalent to { "metadata.labels.<key>": { "eq": "<value>" } }.
  • field=<path>=<value> is equivalent to { "<path>": { "eq": "<value>" } }.

Use label= and field= for one-liner filters; reach for rawq when you need disjunctions, relationship navigation, or nested logic.

See also​