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.

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

[DOCS] Reformats validate API #46389

Merged
merged 9 commits into from
Sep 18, 2019
Merged

[DOCS] Reformats validate API #46389

Changes from 8 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
22454cc
[DOCS] Reformats validate API.
szabosteve Sep 5, 2019
f8c76e5
Update docs/reference/search/validate.asciidoc
szabosteve Sep 16, 2019
4b7ffbc
Update docs/reference/search/validate.asciidoc
szabosteve Sep 16, 2019
51d2708
Update docs/reference/search/validate.asciidoc
szabosteve Sep 16, 2019
52bc432
[DOCS] Adds test comments to fix CI tests.
szabosteve Sep 16, 2019
a4cab76
[DOCS] Changes query parameter description to a common param reference.
szabosteve Sep 16, 2019
cbc34c4
[DOCS] Changes snippet comments.
szabosteve Sep 17, 2019
ba1e258
Merge branch 'master' into reformat.validate
szabosteve Sep 17, 2019
d056d14
[DOCS] Adds test comment to an examplle snippet.
szabosteve Sep 18, 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
144 changes: 103 additions & 41 deletions docs/reference/search/validate.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,73 @@
[[search-validate]]
=== Validate API

The validate API allows a user to validate a potentially expensive query
without executing it. We'll use the following test data to explain _validate:
Validates a potentially expensive query without executing it.

[source,console]
--------------------------------------------------
GET twitter/_validate/query?q=user:foo
--------------------------------------------------
// TEST[setup:twitter]

szabosteve marked this conversation as resolved.
Show resolved Hide resolved

[[search-validate-api-request]]
==== {api-request-title}

`GET /<index>/_validate/<query>`


[[search-validate-api-desc]]
==== {api-description-title}

The validate API allows you to validate a potentially expensive query
without executing it. The query can be sent either as a path parameter or in the
request body.


[[search-validate-api-path-params]]
==== {api-path-parms-title}

include::{docdir}/rest-api/common-parms.asciidoc[tag=index]

include::{docdir}/rest-api/common-parms.asciidoc[tag=query]


[[search-validate-api-query-params]]
==== {api-query-parms-title}

`all_shards`::
(Optional, boolean) If `true`, the validation is executed on all shards
instead of one random shard per index. Defaults to `false`.

include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]

include::{docdir}/rest-api/common-parms.asciidoc[tag=analyzer]

include::{docdir}/rest-api/common-parms.asciidoc[tag=analyze_wildcard]

include::{docdir}/rest-api/common-parms.asciidoc[tag=default_operator]

include::{docdir}/rest-api/common-parms.asciidoc[tag=df]

include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]

`explain`::
(Optional, boolean) If `true`, the response returns detailed information if an
error has occured. Defautls to `false`.

include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]

include::{docdir}/rest-api/common-parms.asciidoc[tag=lenient]

`rewrite`::
(Optional, boolean) If `true`, returns a more detailed explanation showing the
actual Lucene query that will be executed. Defaults to `false`.

include::{docdir}/rest-api/common-parms.asciidoc[tag=search-q]


[[search-validate-api-example]]
==== {api-examples-title}

[source,console]
--------------------------------------------------
Expand All @@ -12,14 +77,16 @@ PUT twitter/_bulk?refresh
{"index":{"_id":2}}
{"user" : "kimchi", "post_date" : "2009-11-15T14:12:13", "message" : "My username is similar to @kimchy!"}
--------------------------------------------------
// TESTSETUP


When sent a valid query:

[source,console]
--------------------------------------------------
GET twitter/_validate/query?q=user:foo
--------------------------------------------------
// TEST[continued]

szabosteve marked this conversation as resolved.
Show resolved Hide resolved

The response contains `valid:true`:

Expand All @@ -29,31 +96,6 @@ The response contains `valid:true`:
--------------------------------------------------


[float]
=== Request Parameters

When executing exists using the query parameter `q`, the query passed is
a query string using Lucene query parser. There are additional
parameters that can be passed:

[cols="<,<",options="header",]
|=======================================================================
|Name |Description
|`df` |The default field to use when no field prefix is defined within the
query.

|`analyzer` |The analyzer name to be used when analyzing the query string.

|`default_operator` |The default operator to be used, can be `AND` or
`OR`. Defaults to `OR`.

|`lenient` |If set to true will cause format based failures (like
providing text to a numeric field) to be ignored. Defaults to false.

|`analyze_wildcard` |Should wildcard and prefix queries be analyzed or
not. Defaults to `false`.
|=======================================================================

The query may also be sent in the request body:

[source,console]
Expand All @@ -74,13 +116,14 @@ GET twitter/_validate/query
}
}
--------------------------------------------------
// TEST[continued]

NOTE: The query being sent in the body must be nested in a `query` key, same as
szabosteve marked this conversation as resolved.
Show resolved Hide resolved
the <<search-search,search api>> works

If the query is invalid, `valid` will be `false`. Here the query is
invalid because Elasticsearch knows the post_date field should be a date
due to dynamic mapping, and 'foo' does not correctly parse into a date:
If the query is invalid, `valid` will be `false`. Here the query is invalid
because {es} knows the `post_date` field should be a date due to dynamic
mapping, and 'foo' does not correctly parse into a date:

[source,console]
--------------------------------------------------
Expand All @@ -94,14 +137,17 @@ GET twitter/_validate/query
}
}
--------------------------------------------------
// TEST[continued]

[source,console-result]
--------------------------------------------------
{"valid":false,"_shards":{"total":1,"successful":1,"failed":0}}
--------------------------------------------------

An `explain` parameter can be specified to get more detailed information
about why a query failed:
===== The explain parameter

An `explain` parameter can be specified to get more detailed information about
why a query failed:

[source,console]
--------------------------------------------------
Expand All @@ -115,8 +161,10 @@ GET twitter/_validate/query?explain=true
}
}
--------------------------------------------------
// TEST[continued]

responds with:

szabosteve marked this conversation as resolved.
Show resolved Hide resolved
The API returns the following response:

[source,console-result]
--------------------------------------------------
Expand All @@ -136,11 +184,11 @@ responds with:
--------------------------------------------------
// TESTRESPONSE[s/"error" : "[^\"]+"/"error": "$body.explanations.0.error"/]

When the query is valid, the explanation defaults to the string
representation of that query. With `rewrite` set to `true`, the explanation
is more detailed showing the actual Lucene query that will be executed.
===== The rewrite parameter

For More Like This:
When the query is valid, the explanation defaults to the string representation
of that query. With `rewrite` set to `true`, the explanation is more detailed
showing the actual Lucene query that will be executed.

[source,console]
--------------------------------------------------
Expand All @@ -158,7 +206,8 @@ GET twitter/_validate/query?rewrite=true
--------------------------------------------------
// TEST[skip:the output is randomized depending on which shard we hit]

Response:

The API returns the following response:

[source,console-result]
--------------------------------------------------
Expand All @@ -179,13 +228,25 @@ Response:
}
--------------------------------------------------


===== Rewrite and all_shards parameters

By default, the request is executed on a single shard only, which is randomly
selected. The detailed explanation of the query may depend on which shard is
being hit, and therefore may vary from one request to another. So, in case of
query rewrite the `all_shards` parameter should be used to get response from
all available shards.

For Fuzzy Queries:
////
[source,console]
--------------------------------------------------
PUT twitter/_bulk?refresh
{"index":{"_id":1}}
{"user" : "kimchy", "post_date" : "2009-11-15T14:12:12", "message" : "trying out Elasticsearch"}
{"index":{"_id":2}}
{"user" : "kimchi", "post_date" : "2009-11-15T14:12:13", "message" : "My username is similar to @kimchy!"}
--------------------------------------------------
////

szabosteve marked this conversation as resolved.
Show resolved Hide resolved
[source,console]
--------------------------------------------------
Expand All @@ -202,7 +263,8 @@ GET twitter/_validate/query?rewrite=true&all_shards=true
}
--------------------------------------------------

Response:

Copy link
Contributor

Choose a reason for hiding this comment

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

The prior snippet needs // TEST[continued].

Copy link
Contributor Author

@szabosteve szabosteve Sep 18, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

@jrodewig Thank you so much, it solved the problem! Please approve when you have time.

The API returns the following response:

[source,console-result]
--------------------------------------------------
Expand Down