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 to match any element of the array, as in ApprovedBy ? '7c61626f-ddbe-41af-93f6-b69f4ab6d308'. Arrays can perform LEN() to check for length, as in LEN(ApprovedBy) > 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'.

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').

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.