docs(clp-json): Update list of characters that requires escaping in queries. #617
Conversation
WalkthroughThe documentation for the CLP JSON search syntax has been revised to enhance clarity regarding the rules for querying JSON logs. Key updates include refined escape character rules, expanded wildcard handling, and clarified numeric comparison operators. The documentation specifies the interpretation of queries with spaces, limitations on partial key queries, and differences with KQL, providing users with a clearer understanding of how to construct effective queries. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Documentation
participant CLP
User->>Documentation: Request for search syntax
Documentation->>User: Provide updated search syntax rules
User->>CLP: Construct query based on rules
CLP-->>User: Return search results
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (3)
docs/src/user-guide/reference-json-search-syntax.md (3)
36-40: Consider adding examples to illustrate escaping rulesThe escaping rules are clear but would benefit from concrete examples showing both correct and incorrect usage. This would help users better understand when and how to apply these rules.
Consider adding examples like:
Keys or values with the following literal characters must escape the characters using a `\` (backslash): `\`, `"`. + +For example: +``` +# Correct +path\\"to\\file: value # Escaping quotes and backslashes + +# Incorrect +path"to\file: value # Unescaped quotes and backslashes +``` + Unquoted keys or values must also escape the following characters: `(`, `)`, `:`, `<`, `>`, `{`, `}`. The unquoted keywords `and`, `or`, and `not` can also be escaped with a `\`. + +For example: +``` +# Correct +response\:code: 200 # Escaping colon in unquoted key +"response:code": 200 # Alternative: using quotes instead of escaping + +# Incorrect +response:code: 200 # Unescaped colon in unquoted key +```
42-46: Clarify the relationship between different escaping contextsWhile the rules for escaping wildcards and nested key indicators are accurate, it would be helpful to explicitly state how these rules interact with the general escaping rules mentioned above.
Consider adding a clarifying note:
Values containing `?` and `*` can escape these characters with a `\` to differentiate them from the `?` and `*` characters used to specify arbitrary single character match and wildcard match. Keys containing `.` can escape the `.` with `\` to differentiate from the special `.` character that indicates nested keys. + +Note: These escaping rules for special characters (`?`, `*`, `.`) apply in addition to the general +escaping rules mentioned above. For example, a key containing both quotes and dots would need both +characters escaped: +``` +my\.quoted\"key: value # Escaping both the dot and the quote +```
36-46: Overall documentation improvements look goodThe changes effectively clarify the character escaping rules in JSON search, which aligns well with the PR objectives. The documentation now provides clear guidance on which characters need escaping and in what contexts.
Consider adding a small table of contents or summary at the start of the escaping rules section to help users quickly find specific escaping rules they're looking for.
Add a summary like:
+### Character Escaping Rules + +Quick reference: +- Always escape: `\` and `"` +- Escape when unquoted: `(`, `)`, `:`, `<`, `>`, `{`, `}` +- Special characters: + - Wildcards (`?`, `*`): Escape to use literally in values + - Dot (`.`): Escape to use literally in keys + Keys or values with the following literal characters must escape the characters using a `\` (backslash): `\`, `"`.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (2)
docs/src/user-guide/reference-json-search-syntax.md (2)
167-193: Consider adding examples for better clarity.While the escaping rules are well-organized, adding examples would make them more accessible. Consider adding a subsection with examples like:
#### Examples of character escaping **In keys:** ```json { "my\\.key": "value", // Escaped dot in key "my\"quoted\"key": "value" // Escaped quotes in key }In values:
{ "key": "value with \\", // Escaped backslash "key": "value with \"quote" // Escaped quote }In unquoted contexts:
key\:value // Escaped colon when unquoted<details> <summary>🧰 Tools</summary> <details> <summary>🪛 Markdownlint (0.35.0)</summary> 183-183: Expected: asterisk; Actual: underscore Emphasis style (MD049, emphasis-style) --- 183-183: Expected: asterisk; Actual: underscore Emphasis style (MD049, emphasis-style) </details> </details> --- `183-184`: **Fix markdown emphasis style.** For consistency with the rest of the document, use asterisks instead of underscores for emphasis. ```diff -_Unquoted_ keys or values containing the following literal characters must also escape the +*Unquoted* keys or values containing the following literal characters must also escape the🧰 Tools
🪛 Markdownlint (0.35.0)
183-183: Expected: asterisk; Actual: underscore
Emphasis style(MD049, emphasis-style)
183-183: Expected: asterisk; Actual: underscore
Emphasis style(MD049, emphasis-style)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
docs/src/user-guide/reference-json-search-syntax.md(2 hunks)
🧰 Additional context used
🪛 Markdownlint (0.35.0)
docs/src/user-guide/reference-json-search-syntax.md
183-183: Expected: asterisk; Actual: underscore
Emphasis style
(MD049, emphasis-style)
183-183: Expected: asterisk; Actual: underscore
Emphasis style
(MD049, emphasis-style)
🔇 Additional comments (1)
docs/src/user-guide/reference-json-search-syntax.md (1)
42-47: LGTM! Well-placed introductory note.
The note effectively alerts users about special character handling and provides a clear reference to the detailed section.
gibber9809
changed the title
…ueries. (y-scope#617) Co-authored-by: Kirk Rodrigues <[email protected]>
…ueries. (y-scope#617) Co-authored-by: Kirk Rodrigues <[email protected]>
Description
Update docs for JSON search to clarify what characters need to be escaped and when.
Validation performed
Validated that markdown renders as expected.
Summary by CodeRabbit