OpenSearch/docs/reference/migration/migrate_5_0/scripting.asciidoc

[[breaking_50_scripting]]
=== Script related changes

==== Indexed scripts and templates

Indexed scripts and templates have been replaced by <<modules-scripting-stored-scripts,stored scripts>>
which stores the scripts and templates in the cluster state instead of a dedicate `.scripts` index.

For the size of stored scripts there is a soft limit of 65535 bytes. If scripts exceed that size then
the `script.max_size_in_bytes` setting can be added to elasticsearch.yml to change the soft limit to a higher value.
If scripts are really large, other options like native scripts should be considered.

Previously indexed scripts in the `.scripts` index will not be used any more as
Elasticsearch will now try to fetch the scripts from the cluster state. Upon upgrading
to 5.x the `.scripts` index will remain to exist, so it can be used by a script to migrate
the stored scripts from the `.scripts` index into the cluster state. The format of the scripts
hasn't changed.

===== Python migration script

The following Python script can be used to import your indexed scripts into the cluster state
as stored scripts:

[source,python]
-----------------------------------
from elasticsearch import Elasticsearch,helpers

es = Elasticsearch([
	{'host': 'localhost'}
])

for doc in helpers.scan(es, index=".scripts", preserve_order=True):
	es.put_script(lang=doc['_type'], id=doc['_id'], body=doc['_source'])
-----------------------------------

This script makes use of the official Elasticsearch Python client and
therefore you need to make sure that your have installed the client in your
environment. For more information on this please see
https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/index.html[`elasticsearch-py`].

===== Perl migration script

The following Perl script can be used to import your indexed scripts into the cluster state
as stored scripts:

[source,perl]
-----------------------------------
use Search::Elasticsearch;

my $es     = Search::Elasticsearch->new( nodes => 'localhost:9200');
my $scroll = $es->scroll_helper( index => '.scripts', sort => '_doc');

while (my $doc = $scroll->next) {
  $e->put_script(
    lang => $doc->{_type},
    id   => $doc->{_id},
    body => $doc->{_source}
  );
}
-----------------------------------

This script makes use of the official Elasticsearch Perl client and
therefore you need to make sure that your have installed the client in your
environment. For more information on this please see
https://metacpan.org/pod/Search::Elasticsearch[`Search::Elasticsearch`].

===== Verifying script migration

After you have moved the scripts via the provided script or otherwise then you can verify with the following
request if the migration has happened successfully:

[source,js]
-----------------------------------
GET _cluster/state?filter_path=metadata.stored_scripts
-----------------------------------

The response should include all your scripts from the `.scripts` index.
After you have verified that all your scripts have been moved, optionally as a last step,
you can delete the `.scripts` index as Elasticsearch no longer uses it.

==== Indexed scripts Java APIs

All the methods related to interacting with indexed scripts have been removed.
The Java API methods for interacting with stored scripts have been added under `ClusterAdminClient` class.
The sugar methods that used to exist on the indexed scripts API methods don't exist on the methods for
stored scripts. The only way to provide scripts is by using `BytesReference` implementation, if a string needs to be
provided the `BytesArray` class should be used.

==== Scripting engines now register only a single language

Prior to 5.0.0, script engines could register multiple languages. The Javascript
script engine in particular registered both `"lang": "js"` and `"lang":
"javascript"`. Script engines can now only register a single language. All
references to `"lang": "js"` should be changed to `"lang": "javascript"` for
existing users of the lang-javascript plugin.

==== Scripting engines now register only a single extension

Prior to 5.0.0 scripting engines could register multiple extensions. The only
engine doing this was the Javascript engine, which registered "js" and
"javascript". It now only registers the "js" file extension for on-disk scripts.

==== `.javascript` files are no longer supported (use `.js`)

The Javascript engine previously registered "js" and "javascript". It now only
registers the "js" file extension for on-disk scripts.