From 3d6d5096170d1a99bb9c960cf9a1c0b65e0a01d9 Mon Sep 17 00:00:00 2001 From: Manuel Gerding Date: Wed, 2 Sep 2026 15:16:32 +0200 Subject: [PATCH 1/4] docs: document line comments in the query language A query can now carry a `//` comment, so the reason a target was excluded lives next to the exclusion. Two caveats get their own bullets because both surprise people. A `//` inside a quoted value is part of the value, not a comment, so URLs keep working. And a query made up of nothing but comments is an empty query, which matches everything -- commenting a query out widens it rather than emptying it. Note this page already used `//` for its own annotations in two examples, which until now would have been syntax errors if pasted into the editor. They are valid as of this release. --- concepts/query-language/README.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/concepts/query-language/README.md b/concepts/query-language/README.md index 2ffa131a..f73702b3 100644 --- a/concepts/query-language/README.md +++ b/concepts/query-language/README.md @@ -150,3 +150,33 @@ Keys containing special characters like `:` and `/` needs to be quoted to work p // Quoting keys with special characters is necessary "label.aws:ec2launchtemplate/version"="some value" ``` + +#### Comments + +A query can explain itself. Anything from `//` to the end of the line is a comment: it is ignored +when the query is evaluated, and it is stored with the query, so the reason a target was excluded +stays next to the exclusion. + +A comment can stand on its own line: + +``` +// The canary tier is deployed continuously, so it is expected to be unstable. +k8s.cluster-name="prod" +AND NOT k8s.label.tier="canary" +``` + +or follow a query on the same line: + +``` +k8s.cluster-name="prod" // only production +``` + +Comments work everywhere queries do — environment scopes, service target scopes, experiment blast +radii, the target explorer and the API. + +Two things to be aware of: + +- A `//` inside a quoted value is part of the value, not a comment, so URLs keep working: + `"label.url"="https://example.com"`. +- A query made up of nothing but comments is treated as an empty query, and an empty query matches + **everything**. Commenting out an entire query therefore widens it rather than emptying it. From 4d4c866123f1e5f480b68dbe7d254e35a19e93e4 Mon Sep 17 00:00:00 2001 From: Manuel Gerding Date: Wed, 2 Sep 2026 15:39:25 +0200 Subject: [PATCH 2/4] docs: say what "matches everything" actually means for a comment-only query "An empty query matches everything" read as if commenting a query out could reach past the environment it lives in, or past what a team is permitted to use. It cannot: a query is always ANDed with its scope, so it only ever narrows what that scope already contains. The bullet now says that, and spells out the two ordinary cases -- a blast radius stays within the experiment's environment and the action's target type, a service scope within its environment -- before naming the one that really is tenant-wide: an environment's own scope, where the query is the boundary rather than a filter inside one. Also drops a line break from the first example. The comment is what needs its own line; splitting the query across two suggested the AND had to be there. --- concepts/query-language/README.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/concepts/query-language/README.md b/concepts/query-language/README.md index f73702b3..56c3228f 100644 --- a/concepts/query-language/README.md +++ b/concepts/query-language/README.md @@ -161,8 +161,7 @@ A comment can stand on its own line: ``` // The canary tier is deployed continuously, so it is expected to be unstable. -k8s.cluster-name="prod" -AND NOT k8s.label.tier="canary" +k8s.cluster-name="prod" AND NOT k8s.label.tier="canary" ``` or follow a query on the same line: @@ -178,5 +177,9 @@ Two things to be aware of: - A `//` inside a quoted value is part of the value, not a comment, so URLs keep working: `"label.url"="https://example.com"`. -- A query made up of nothing but comments is treated as an empty query, and an empty query matches - **everything**. Commenting out an entire query therefore widens it rather than emptying it. +- A query made up of nothing but comments is treated as an empty query. A query only ever *narrows* + what its scope already contains, so commenting one out stops the narrowing rather than emptying + the selection: an experiment's blast radius then covers every target of that action's target type + in the experiment's environment, and a service's target scope every target in its environment. The + one to watch is an [environment's own scope](/install-and-configure/manage-environments/#define-your-own-environment), + where the query *is* the boundary — commenting that out covers every target in the tenant. From 6f8accda2b801684dc2703b9134943b1389d7356 Mon Sep 17 00:00:00 2001 From: Manuel Gerding Date: Wed, 2 Sep 2026 15:47:41 +0200 Subject: [PATCH 3/4] docs: make the query language page's heading levels consecutive The page went from `#` straight to `###`, then to `####` for each example, so every section sat one level deeper than it needed to and the top level was skipped entirely. Promoting each by one gives `#` > `##` > `###` with nothing missing, which is what the page-level table of contents and screen readers both read the structure from. Headings only -- verified no line inside a code fence starts with `#`, and no other page links to this one by anchor. Anchors derive from heading text rather than level in any case, so existing links are unaffected. --- concepts/query-language/README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/concepts/query-language/README.md b/concepts/query-language/README.md index 56c3228f..168aee64 100644 --- a/concepts/query-language/README.md +++ b/concepts/query-language/README.md @@ -1,12 +1,12 @@ # Query Language -### What is the Query Language? +## What is the Query Language? There are some use cases, where you want to restrict the targets discovered by Steadybit. One use case can be that you want to [design an experiment](/use-steadybit/experiments/design.md#basic-elements) and make sure, that there are only targets of a specific Kubernetes cluster affected by the experiment. Another use case is that you want to restrict the available targets when [configuring an environment](/install-and-configure/manage-environments/#define-your-own-environment). Boiling down to a set of targets can result in complex statements. For instance, you want to make sure that the targets are matching some sets of key-value pairs but also not in your production cluster. Expressions like these can now easily be written in Steadybits Query Language. The Query Language is a textual representation of the Query UI but with a more advanced feature set. It allows you to build semantic expression blocks, combining them with other expressions or negating them. The Query UI and the Query Language always come together, so it is up to you to choose the style. -### How to switch between the Query UI and the Query Langauge +## How to switch between the Query UI and the Query Langauge

The same query can be expressed with the Query UI on the left and the Query Language on the right

@@ -16,9 +16,9 @@ Please note that the Query UI is limited in regard to the queries you write. For

Complex queries can only be edited in the Query language editor.

-### Query Examples +## Query Examples -#### Key-value comparison +### Key-value comparison Keys and values can be compared using `=`, `!=`, `~`, `!~`, `=*`, `!=*`, `~*`, `!~*`, `IN ()` and `NOT IN ()` @@ -75,7 +75,7 @@ k8s.cluster-name IS PRESENT k8s.label.service-tier IS NOT PRESENT ``` -#### Using variables and placeholders +### Using variables and placeholders You can use an experiment [variable](../../use-steadybit/experiments/variables.md) (`{{...}}`) or a template placeholder (`[[...]]`) as a value in a query. Markers may be written with or without quotes: @@ -99,7 +99,7 @@ A `=` (or `!=`) comparison against a multi-value variable also works: it matches {% endhint %} -#### Aggregations +### Aggregations To aggregate a key's value, you can use the `COUNT` function to check for the number of distinct values with numeric operators like `<`,`<=`,`=`,`>=` and `>`. @@ -112,7 +112,7 @@ COUNT(aws.zone) >= 2 COUNT(k8s.pod.name) = 1 ``` -#### Expression Concatenation +### Expression Concatenation Simple expressions can be chained with AND & OR. @@ -125,7 +125,7 @@ k8s.cluster-name="prod" OR k8s.cluster-name="staging" k8s.cluster-name="prod" AND host.hostname="ip-1-2-3-4" ``` -#### Expression Negation +### Expression Negation You can negate a specific key-value expression using NOT. @@ -134,7 +134,7 @@ You can negate a specific key-value expression using NOT. NOT k8s.cluster-name="prod" ``` -#### Parenthesis +### Parenthesis Expression blocks can be encapsulated using parenthesis. @@ -142,7 +142,7 @@ Expression blocks can be encapsulated using parenthesis. (k8s.cluster-name="prod" OR k8s.cluster-name="staging") AND aws.zone="eu-central-1b" ``` -#### Quoting Special Characters +### Quoting Special Characters Keys containing special characters like `:` and `/` needs to be quoted to work properly. @@ -151,7 +151,7 @@ Keys containing special characters like `:` and `/` needs to be quoted to work p "label.aws:ec2launchtemplate/version"="some value" ``` -#### Comments +### Comments A query can explain itself. Anything from `//` to the end of the line is a comment: it is ignored when the query is evaluated, and it is stored with the query, so the reason a target was excluded From f4d4f3577565f88d84a9ae3301e54b0236559352 Mon Sep 17 00:00:00 2001 From: Manuel Gerding Date: Wed, 2 Sep 2026 15:49:14 +0200 Subject: [PATCH 4/4] docs: fix "Langauge" typo in the query language page Note this changes that heading's anchor. Nothing in the repository referenced it -- SUMMARY.md links the page rather than the heading, and no other page links this one by anchor -- and an anchor carrying the misspelling is unlikely to have been linked deliberately from outside. --- concepts/query-language/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/concepts/query-language/README.md b/concepts/query-language/README.md index 168aee64..b22d5988 100644 --- a/concepts/query-language/README.md +++ b/concepts/query-language/README.md @@ -6,7 +6,7 @@ There are some use cases, where you want to restrict the targets discovered by S Boiling down to a set of targets can result in complex statements. For instance, you want to make sure that the targets are matching some sets of key-value pairs but also not in your production cluster. Expressions like these can now easily be written in Steadybits Query Language. The Query Language is a textual representation of the Query UI but with a more advanced feature set. It allows you to build semantic expression blocks, combining them with other expressions or negating them. The Query UI and the Query Language always come together, so it is up to you to choose the style. -## How to switch between the Query UI and the Query Langauge +## How to switch between the Query UI and the Query Language

The same query can be expressed with the Query UI on the left and the Query Language on the right