Filters

In ConfigHub, configuration isn't organized in a file tree. Configuration is stored in units, which reside in spaces. This comparatively flat structure can be adorned with metadata attributes, especially Labels, which can be used to organize your configuration assets and other entities within ConfigHub. List API calls and bulk operations, such as patches and function invocations, can specify filters that limit the scope of what they return or operate upon.

As ConfigHub is a configuration database, its filters are inspired by SQL queries. Filters primarily take the form of where clauses specified via where query parameters. When a filter to applies to an entity other than the primary type being operated upon the parameter name is suffixed with the entity type, such as where_space and where_mutation. Filters may also be saved as entities.

Filters support conjunctions of relational expressions of the form attribute, operator attribute_or_literal. The attribute names are case-sensitive and PascalCase, as in the API JSON encoding.

String comparisons support the following operators: <, >, <=, >=, =, !=, LIKE, NOT LIKE, ILIKE, ~~, !~~, ~, ~*, !~, !~*, IN, NOT IN. String pattern operators: LIKE and ~~ for pattern matching with % and _ wildcards, ILIKE for case-insensitive pattern matching, NOT LIKE and !~~ for negated pattern matching. String regex operators: ~ for regex matching, ~* for case-insensitive regex, !~ and !~* for regex not matching (case-sensitive and insensitive).Integer comparisons support the following operators: <, >, <=, >=, =, !=, IN, NOT IN. UUIDs and boolean attributes support equality and inequality only.

UUID and time literals must be quoted as string literals. String literals are quoted with single quotes, such as 'string'. Time literals use the same form as when serialized as JSON, such as: CreatedAt > '2025-02-18T23:16:34'. Integer and boolean literals are also supported for attributes of those types.

Arrays support the ? operator to match any element of the array, as in InScopeSpaceIDs ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'. Arrays can perform LEN() to check for length, as in LEN(InScopeSpaceIDs) > 0. Map support the dot notation to specify a particular map key, as in Labels.tier = 'Backend'.

The IN and NOT IN operators accept a comma-separated list of values in parentheses, such as Slug IN ('slugone', 'slugtwo') or Labels.Environment IN ('production', 'staging').

Comparison results can be tested with IS TRUE, IS FALSE, IS NOT TRUE, and IS NOT FALSE. These truth-value tests are post-fix modifiers applied to the result of a comparison expression. They are useful for nullable columns: MergeSourceID = '<uuid>' IS NOT FALSE matches rows where MergeSourceID equals the value OR is NULL.

Conjunctions are supported using the AND operator. An example conjunction is: CreatedAt >= '2025-01-07' AND Slug = 'test' AND Labels.mykey = 'myvalue'. There is no OR and no grouping with parentheses: for alternative values of one attribute use IN (...), and for anything else run a query for each alternative.

Supported attributes for each entity type are documented in the OpenAPI specification.

Related entities referenced by an entity may also generally be referenced in filters. For example, for an entity within a space, it can be useful to filter by their attributes, such as Space.Labels.Environment IN ('production', 'staging').

Some attributes reference several entities rather than one: a unit's outgoing links, a space's triggers and attributes, a revision's tags, change orders, releases, and attestations. A * segment selects every one of them, and the expression holds when any one satisfies it:

cub unit list --where "FromLink.*.Slug = 'upgrade-app'"
cub space list --where "Triggers.*.Slug LIKE 'validate-%'"
cub revision list --space my-space my-unit --where "Tags.*.Slug = 'v1'"
cub revision list --space my-space my-unit --where "ChangeOrders.*.Slug = 'release-5'"

Because any element satisfying the expression is enough, a negated operator reads as "some element is not this" rather than "no element is this", the same way it does for a data path selecting several values. An entity with none of the referenced entities matches nothing, so ask whether the set is empty with LEN() on the attribute holding the identifiers instead, as in LEN(FromLinkID) = 0.

The * is required. Some of these attributes are maps keyed by the identifiers, and for those the dot notation without a * keeps its usual meaning of naming a map key, as in Releases.<release-id> = ''. Where the attribute is not a map, omitting the * is an error, since the attribute names no single value to compare.

Some attributes hold a JSON document rather than a single value or a map, such as a release's LiveStatus, a change order's Releases, and an invocation's FunctionInvocations. A filter reaches into one with the same path syntax as configuration data: keys separated by dots, * for every element of a list, a number for one element, and ?key=value for the elements whose key has that value. As with the multi-entity attributes above, the expression holds when any value the path selects satisfies it:

cub release list --space my-app-prod --where "LiveStatus.Health = 'Degraded'"
cub changeorder list --space my-app-base --where "Releases.*.ReleaseNum >= 4"
cub changeorder list --space my-app-base --where "Releases.?SpaceID=<space-id>.ReleaseID = '<release-id>'"

Comparisons follow the literal's type and match only values of that type, so Releases.*.ReleaseNum = '4' matches nothing, and neither does != '4'. A path that selects nothing matches no comparison, and IS NULL and IS NOT NULL ask whether it selects anything.

In addition to these filters on the attributes of ConfigHub entities, unit filters based on configuration data are also supported through the resource_type and where_data query parameters and using the where-filter function.

Unified filters with Data prefix

For units, configuration data paths can be included directly in --where expressions using the Data. prefix. This allows metadata and data filters to be combined in a single expression. The Data. prefix is stripped and the expression is evaluated against the unit's configuration data content.

For example:

cub unit list --space my-space --where "Slug LIKE 'app-%' AND Data.spec.replicas > 1"

This is equivalent to specifying separate --where and --where-data parameters:

cub unit list --space my-space --where "Slug LIKE 'app-%'" --where-data "spec.replicas > 1"

Data path expressions support the full configuration data filter syntax, including wildcards (*), associative matching (?key=value), and split paths (.|). A path to a container image can end in #reference or #uri to compare only the image's tag or digest, or only its repository, as in spec.template.spec.containers.*.image#reference = ':latest'. Data and metadata fields cannot be mixed in the same relational expression — each comparison must reference either a metadata attribute or a Data. path on the left side.

When both Data. expressions in --where and explicit --where-data are specified, they are combined with AND logic.