Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(clp-json): Update list of characters that requires escaping in queries. #617

Merged
merged 3 commits into from
Dec 2, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 33 additions & 3 deletions docs/src/user-guide/reference-json-search-syntax.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,15 +33,18 @@ To search for a key or value with multiple words, you must quote the key/value w
"multi-word key": "multi-word value"
```

Queries for keys or values with the following literal characters must escape the characters using a
`\` (backslash): `\`, `(`, `)`, `:`, `<`, `>`, `"`, `*`, `{`, `}`.

:::{caution}
Currently, a query that contains spaces is interpreted as a substring search, i.e., it will match
log events that contain the value as a *substring*. In a future version of CLP, these queries will
be interpreted as _exact_ searches unless they include [wildcards](#wildcards-in-values).
:::

:::{note}
Certain characters have special meanings when used in keys or values, so to search for the
characters literally, you must escape them. For a list of such characters, see
[Escaping special characters](#escaping-special-characters).
:::

### Querying nested kv-pairs

If the kv-pair is nested in one or more objects, you can specify the key in one of two ways:
Expand Down Expand Up @@ -161,6 +164,33 @@ There are three supported boolean operators:

You can use parentheses (`()`) to apply an operator to a group of expressions.

### Escaping special characters

Keys containing the following literal characters must escape the characters using a `\` (backslash):

* `\`
* `"`
* `.`

Values containing the following literal characters must escape the characters using a `\`
(backslash):

* `\`
* `"`
* `?`
* `*`

_Unquoted_ keys or values containing the following literal characters must also escape the
characters using a `\` (backslash):

* `(`
* `)`
* `:`
* `<`
* `>`
* `{`
* `}`

## Examples

**Search for log events that contain a specific key-value pair:**
Expand Down
Loading