Skip to content

Update query-string-syntax.asciidoc #46863

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.

Sign up for GitHub

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

Merged
jrodewig merged 5 commits into from
Sep 30, 2019
+18 −3
Merged

Update query-string-syntax.asciidoc #46863

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9a071fd
Update query-string-syntax.asciidoc
ndrwnaguib Sep 19, 2019
0c6b19f
Update query-string-syntax.asciidoc
ndrwnaguib Sep 27, 2019
ae2c159
Update docs/reference/query-dsl/query-string-syntax.asciidoc
ndrwnaguib Sep 30, 2019
28dffd4
Update docs/reference/query-dsl/query-string-syntax.asciidoc
ndrwnaguib Sep 30, 2019
cbaa328
Update query-string-syntax.asciidoc
ndrwnaguib Sep 30, 2019
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
21 changes: 18 additions & 3 deletions docs/reference/query-dsl/query-string-syntax.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -271,12 +271,27 @@ of a sub-query:
If you need to use any of the characters which function as operators in your
query itself (and not as operators), then you should escape them with
a leading backslash. For instance, to search for `(1+1)=2`, you would
need to write your query as `\(1\+1\)\=2`.
need to write your query as `\(1\+1\)\=2`. When using JSON for the request body, two preceding backslashes (`\\`) are required; the backslash is a reserved escaping character in JSON strings.

[source,console]
----
GET /twitter/_search
Content-Type: application/json

{
"query" : {
"query_string" : {
"query" : "kimchy\\!",
"fields" : ["user"]
}
}
}
----
// TEST[setup:twitter]

The reserved characters are: `+ - = && || > < ! ( ) { } [ ] ^ " ~ * ? : \ /`

Failing to escape these special characters correctly could lead to a syntax
error which prevents your query from running.
Failing to escape these special characters correctly could lead to a syntax error which prevents your query from running.

Copy link
Member

@cbuescher cbuescher Sep 25, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think better than having two notes would be to make the former example even clearer. We could first extend the paragraph with the search for "(1+1)=2" by stating this would apply to keyword-field search mostly ("... to search for (1+1)=2 in an unanalyzed keyword field ...") and then add another sentence that mentions the need for additional backslash escaping when using JSON (which is probably the most common way to use the REST API). Maybe even add an example query like:

GET /_search
{
  "query": {
    "query_string": {
      "query": "\\(1\\+1\\)\\=2"
    }
  }
}

wdyt?

Copy link
Contributor

@jrodewig jrodewig Sep 25, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think a simpler example might illustrate the point better. Maybe something more like this:

====== Reserved characters

Query string syntax reserves the following characters as operators:

....
+ - = && || > < ! ( ) { } [ ] ^ " ~ * ? : \ /
....

To use one of these characters literally,
escape it with two preceding backlashes (`\\`).

For example,
the following search request uses a query string query
to match `kimchy!` in the `user` <<keyword,keyword>> field.
Two backslashes are required to escape `!` in `kimchy!`.

[source,console]
----
GET /twitter/_search
{
  "query" : {
    "query_string" : {
      "query" : "kimchy\\!",
      "fields"  : ["user"]
    }
  }
}
----
// TEST[setup:twitter]

NOTE: `>` and `<` can't be escaped at all. The only way to prevent them from
attempting to create a range query is to remove them from the query string
entirely.

@AndrewNaguib Let me know if you think that addresses the issue. If so, please feel free to add it to your PR.

I think it might also be helpful to move this section higher in the file.

Copy link
Contributor Author

@ndrwnaguib ndrwnaguib Sep 27, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @jrodewig and @cbuescher for your response. I believe both of you have provided a much neater way on saying the same information; I will add them to the PR. I have a question tho, do you have internal policies for the documentation that I should be aware of, i.e., is it preferred, for instance, to adopt single example across the topic and so on?

Moreover, @jrodewig you were suggesting moving the section in a higher position, I'm not sure where is the appropriate place except right after Regular Expression and before Fuzziness (I think its current place is better tho because all operators would have been mentioned already, i.e., a context of why they would be reserved was already shown. WDYT?

Copy link
Contributor

@jrodewig jrodewig Sep 27, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you @AndrewNaguib.

We don't have any specific policies about adopting the examples across topics. Generally, you should use an example you feel best fits the context. The twitter example provided is kind of an unofficial default, but please feel free to use your own if you feel it is a better fit.

I don't feel strongly about relocating the section. Your point about this section following others that mention operators is a good one. Let's just leave the section where it is for now.

Thanks again for your work on this.

Copy link
Contributor Author

@ndrwnaguib ndrwnaguib Sep 27, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for your suggestions; I've added them.

NOTE: `<` and `>` can't be escaped at all. The only way to prevent them from
attempting to create a range query is to remove them from the query string
Expand Down