mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-05 20:48:22 +00:00
8a2d424d68
Adds "Appending B. Painless API Reference", a reference of all classes and methods available from Painless. Removes links to java packages because they contain methods that we don't expose and don't contain methods that we do expose (the ones in Augmentation). Instead this generates a list of every class and every exposed method using the same type information available to the interpreter/compiler/whatever-we-call-it. From there you can jump to the relevant docs. Right now you build all the asciidoc files by running ``` gradle generatePainlessApi ``` These files are expected to be committed because we build the docs without running `gradle`. Also changes the output of `Debug.explain` so that it is easy to search for the class in the generated reference documentation. You can also run it in an IDE safely if you pass the path to the directory in which to generate the docs as the first parameter. It'll blow away the entire directory an recreate it from scratch so be careful. And then you can build the docs by running something like: ``` ../docs/build_docs.pl --out ../built_docs/ --doc docs/reference/index.asciidoc --open ``` That is, if you have checked out https://github.com/elastic/docs in `../docs`. Wait a minute or two and your browser will pop open in with all of Elasticsearch's reference documentation. If you go to `http://localhost:8000/painless-api-reference.html` you can see this list. Or you can get there by following the links to `Modules` and `Scripting` and `Painless` and then clicking the link in the paragraphs below titled `Appendix B. Painless API Reference`. I like having these in asciidoc because we can deep link to them from the rest of the guide with constructs like `<<painless-api-reference-Object-hashCode-0>>` and `<<painless-api-reference->>` and we get link checking. Then the only brittle link maintenance bit is the link generation for javadoc. Which sucks. But I think it is important that we link to the methods directly so they are easy to find. Relates to #22720
97 lines
3.8 KiB
Plaintext
97 lines
3.8 KiB
Plaintext
[[modules-scripting-painless-debugging]]
|
|
=== Painless Debugging
|
|
|
|
experimental[The Painless scripting language is new and is still marked as experimental. The syntax or API may be changed in the future in non-backwards compatible ways if required.]
|
|
|
|
==== Debug.Explain
|
|
|
|
Painless doesn't have a
|
|
https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop[REPL]
|
|
and while it'd be nice for it to have one one day, it wouldn't tell you the
|
|
whole story around debugging painless scripts embedded in Elasticsearch because
|
|
the data that the scripts have access to or "context" is so important. For now
|
|
the best way to debug embedded scripts is by throwing exceptions at choice
|
|
places. While you can throw your own exceptions
|
|
(`throw new Exception('whatever')`), Painless's sandbox prevents you from
|
|
accessing useful information like the type of an object. So Painless has a
|
|
utility method, `Debug.explain` which throws the exception for you. For
|
|
example, you can use the <<search-explain>> to explore the context available to
|
|
a <<query-dsl-script-query>>.
|
|
|
|
[source,js]
|
|
---------------------------------------------------------
|
|
PUT /hockey/player/1?refresh
|
|
{"first":"johnny","last":"gaudreau","goals":[9,27,1],"assists":[17,46,0],"gp":[26,82,1]}
|
|
|
|
POST /hockey/player/1/_explain
|
|
{
|
|
"query": {
|
|
"script": {
|
|
"script": "Debug.explain(doc.goals)"
|
|
}
|
|
}
|
|
}
|
|
---------------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[s/_explain/_explain?error_trace=false/ catch:/painless_explain_error/]
|
|
// The test system sends error_trace=true by default for easier debugging so
|
|
// we have to override it to get a normal shaped response
|
|
|
|
Which shows that the class of `doc.first` is
|
|
`org.elasticsearch.index.fielddata.ScriptDocValues.Longs` by responding with:
|
|
|
|
[source,js]
|
|
---------------------------------------------------------
|
|
{
|
|
"error": {
|
|
"type": "script_exception",
|
|
"to_string": "[1, 9, 27]",
|
|
"painless_class": "org.elasticsearch.index.fielddata.ScriptDocValues.Longs",
|
|
"java_class": "org.elasticsearch.index.fielddata.ScriptDocValues$Longs",
|
|
...
|
|
},
|
|
"status": 500
|
|
}
|
|
---------------------------------------------------------
|
|
// TESTRESPONSE[s/\.\.\./"script_stack": $body.error.script_stack, "script": $body.error.script, "lang": $body.error.lang, "caused_by": $body.error.caused_by, "root_cause": $body.error.root_cause, "reason": $body.error.reason/]
|
|
|
|
You can use the same trick to see that `_source` is a `LinkedHashMap`
|
|
in the `_update` API:
|
|
|
|
[source,js]
|
|
---------------------------------------------------------
|
|
POST /hockey/player/1/_update
|
|
{
|
|
"script": "Debug.explain(ctx._source)"
|
|
}
|
|
---------------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued s/_update/_update?error_trace=false/ catch:/painless_explain_error/]
|
|
|
|
The response looks like:
|
|
|
|
[source,js]
|
|
---------------------------------------------------------
|
|
{
|
|
"error" : {
|
|
"root_cause": ...,
|
|
"type": "illegal_argument_exception",
|
|
"reason": "failed to execute script",
|
|
"caused_by": {
|
|
"type": "script_exception",
|
|
"to_string": "{gp=[26, 82, 1], last=gaudreau, assists=[17, 46, 0], first=johnny, goals=[9, 27, 1]}",
|
|
"painless_class": "LinkedHashMap",
|
|
"java_class": "java.util.LinkedHashMap",
|
|
...
|
|
}
|
|
},
|
|
"status": 400
|
|
}
|
|
---------------------------------------------------------
|
|
// TESTRESPONSE[s/"root_cause": \.\.\./"root_cause": $body.error.root_cause/]
|
|
// TESTRESPONSE[s/\.\.\./"script_stack": $body.error.caused_by.script_stack, "script": $body.error.caused_by.script, "lang": $body.error.caused_by.lang, "caused_by": $body.error.caused_by.caused_by, "reason": $body.error.caused_by.reason/]
|
|
// TESTRESPONSE[s/"to_string": ".+"/"to_string": $body.error.caused_by.to_string/]
|
|
|
|
Once you have a class you can go to <<painless-api-reference>> to see a list of
|
|
available methods.
|