From 9439d30bbeffc9a95f6b88355c1649fc9a751ff0 Mon Sep 17 00:00:00 2001
From: Devin Gibson <gibber9809@users.noreply.github.com>
Date: Mon, 2 Dec 2024 15:16:04 -0500
Subject: [PATCH] docs(clp-json): Update list of characters that requires
 escaping in queries. (#617)

Co-authored-by: Kirk Rodrigues <2454684+kirkrodrigues@users.noreply.github.com>
---
 .../reference-json-search-syntax.md           | 36 +++++++++++++++++--
 1 file changed, 33 insertions(+), 3 deletions(-)

diff --git a/docs/src/user-guide/reference-json-search-syntax.md b/docs/src/user-guide/reference-json-search-syntax.md
index ca6898984..18d0e4267 100644
--- a/docs/src/user-guide/reference-json-search-syntax.md
+++ b/docs/src/user-guide/reference-json-search-syntax.md
@@ -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:
@@ -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:**