[DOC] Missing documentation executing stored scripts in update/bulk operations

[camerondurham]

What do you want to do?

• Request a change to existing documentation
• Add new documentation
• Report a technical problem with the documentation
• Other

Tell us about your request. Provide a summary of the request and all versions that are affected.

As an OpenSearch user, I would like to have documentation around how to perform operations using a stored script. The docs cover how to use inline scripts but not how to reference a stored script.

Please let me know if I maybe missed it in documentation, or if this is too much of an "edge-case" to be useful.

Here's a specific, potentially useful example it would nice to have documentation around:

Example below executes the conditional script in a cluster with incoming doc in params to conditionally update the doc with _id=test-1. I came across this while answering this amazon-opensearch question and didn't find docs to link to.

curl -XPOST "http://localhost:9200/_bulk?_source=true" -H 'Content-Type: application/json' -d'
    {"update":{"_index":"overflow-index","_type":"_doc","_id":"test-1","retry_on_conflict":1}}
    {"script":{"id":"conditional","params":{ "uuid": "test", "status": false, "timestamp": "3994-01-31T23:05:09.909525Z"}}}
'

Also, I'm happy PR as long I know where and how documentation owners think this should be updated.

Thanks!

What other resources are available? Provide links to related issues, POCs, steps for testing, etc.

• Current bulk documentation for scripts: https://opensearch.org/docs/latest/api-reference/document-apis/bulk/
• Update by query includes how to add a script to your query but now how to reference a stored script: https://opensearch.org/docs/latest/api-reference/document-apis/update-by-query/

[hdhalter]

Thanks, @camerondurham, did you look in this section? https://opensearch.org/docs/latest/api-reference/script-apis/create-stored-script/

[camerondurham]

Hi @hdhalter ,
Thanks for pointing out that documentation, (https://opensearch.org/docs/latest/api-reference/script-apis/exec-stored-script/#running-a-painless-stored-script-with-parameters). I had missed it earlier.

Would it be helpful to clarify if/when stored scripts can be used in other contexts (bulk, update by query, index, etc.)? Or should developers infer that stored scripts can be referenced wherever scripts are allowed?

Ref:

• documentation-website/_api-reference/script-apis/exec-stored-script.md

  Line 14 in fe979d5

  OpenSearch provides several ways to run a script; the following sections show how to run a script by passing script information in the request body of a `GET <index>/_search` request.

• documentation-website/_api-reference/document-apis/bulk.md

  Line 131 in fe979d5

  { "script" : { "source": "ctx._source.title = \"World War Z\"" } }

• documentation-website/_api-reference/document-apis/update-by-query.md

  Line 14 in fe979d5

  You can include a query and a script as part of your update request so OpenSearch can run the script to update all of the documents that match the query.

I'm okay to close the issue if the current documentation is sufficient.

[hdhalter]

@dhwanilpatel - Do you have any thoughts on this?

[dhwanilpatel]

While passing script in APIs, we need to pass either "source" or "id", so it seems we can pass the id for the stored script instead of source.

https://github.com/opensearch-project/OpenSearch/blob/f2ed7d6071145d1e4e98f6e988be9392fdf9939a/server/src/main/java/org/opensearch/script/Script.java#L363-L366

We can include this one liner in our documentation so users wont have to go through the code to understand this.

[leanneeliatra]

I'll update this @hdhalter, please assign me.