v5.0-18. Script related changes

Switched Default Language from Groovy to Painlessedit

The default scripting language for Elasticsearch is now Painless. Painless is a custom-built language with syntax similar to Groovy designed to be fast as well as secure. Many Groovy scripts will be identitical to Painless scripts to help make the transition between languages as simple as possible.

Elasticsearch의 기본 script 언어는 이제 Painless이다. Painless은 Groovy와 유사한 구문을 사용하는 맞춤형 언어로, 빠르고 안전하도록 설계되었습니다. 많은 Groovy script는 가능한 간단하게 언어간 전환을 하는데 도움이 되는 Painless script와 동일하다.

Documentation for Painless can be found at Painless Scripting Language

Painless에 대한 Documentation는 Painless Scripting Language에서 찾을 수 있다.

One common difference to note between Groovy and Painless is the use of parameters — all parameters in Painless must be prefixed with params. now. The following example shows the difference:

Groovy와 Painless 사이에 주목해야 할 한가지 공통점은 parameter의 사용이다. Painless의 모든 parameter 앞에는 params. 접두사가 있어야 한다. 다음 예제는 그 차이점을 보여준다.

Groovy:

{
  "script_score": {
    "script": {
      "lang": "groovy",
      "source": "Math.log(_score * 2) + my_modifier",
      "params": {
        "my_modifier": 8
      }
    }
  }
}

Painless (my_modifer is prefixed with params):

Painless (my_modifer 앞에 params 접두사가 있다):

{
  "script_score": {
    "script": {
      "lang": "painless",
      "source": "Math.log(_score * 2) + params.my_modifier",
      "params": {
        "my_modifier": 8
      }
    }
  }
}

The script.default_lang setting has been removed. It is no longer possible set the default scripting language. If a different language than painless is used then this should be explicitly specified on the script itself.

script.default_lang 설정이 제거되었다. 더 이상 기본 script 언어를 설정할 수 없다. painless 가 아닌 다른 언어가 사용되면 script 자체에 명시 적으로 지정되어야 한다.

For scripts with no explicit language defined, that are part of already stored percolator queries, the default language can be controlled with the script.legacy.default_lang setting.

명시적으로 언어가 정의되지 않은 script의 경우 이미 저장된 percolator query의 일부이므로script.legacy.default_lang 설정을 통해 기본 언어를 제어할 수 있다.

Removed 1.x script and template syntaxedit

The deprecated 1.x syntax of defining inline scripts / templates and referring to file or index base scripts / templates have been removed.

inline script / template을 정의하고 파일 또는 index 기반 script / template을 참조하는 deprecate된 1.x 구문이 제거되었다.

The script and params string parameters can no longer be used and instead the script object syntax must be used. This applies for the update api, script sort, script_score function, scriptquery, scripted_metric aggregation and script_heuristic aggregation.

script 및 params string parameter는 더 이상 사용할 수 없으며 script object 구문을 사용해야 한다. 이것은 update api, script sort, script_score 함수, script query, scripted_metric aggregation과 script_heuristic aggregation에 적용된다.

So this usage of inline scripts is no longer allowed:

inline script의 사용은 더 이상 허용되지 않는다.

{
  "script_score": {
    "lang": "groovy",
    "script": "Math.log(_score * 2) + my_modifier",
    "params": {
      "my_modifier": 8
    }
  }
}

and instead this syntax must be used:

대신 아래 구문을 사용해야 한다.

{
  "script_score": {
    "script": {
      "lang": "groovy",
      "source": "Math.log(_score * 2) + my_modifier",
      "params": {
        "my_modifier": 8
      }
    }
  }
}

The script or script_file parameter can no longer be used to refer to file based scripts and templates and instead file must be used.

script 또는 script_file parameter는 더 이상 파일 기반 script와 template을 참조하는 데 사용할 수 없으며 대신 file 을 사용해야 한다.

This usage of referring to file based scripts is no longer valid:

파일 기반 script의 참조는 더 이상 유효하지 않다.

{
  "script_score": {
    "script": "calculate-score",
    "params": {
      "my_modifier": 8
    }
  }
}

This usage is valid:

아래 사용은 유효하다.

{
  "script_score": {
    "script": {
      "lang": "groovy",
      "file": "calculate-score",
      "params": {
        "my_modifier": 8
      }
    }
  }
}

The script_id parameter can no longer be used the refer to indexed based scripts and templates and instead id must be used.

script_id parameter는 더 이상 index 기반 script / template을 참조할 수 없으며 대신 id 를 사용해야 한다.

This usage of referring to indexed scripts is no longer valid:

아래 indexed script의 사용은 더 이상 유효하지 않다.

{
  "script_score": {
    "script_id": "indexedCalculateScore",
    "params": {
      "my_modifier": 8
    }
  }
}

This usage is valid:

아래 사용은 유효하다.

{
  "script_score": {
    "script": {
      "id": "indexedCalculateScore",
      "lang" : "groovy",
      "params": {
        "my_modifier": 8
      }
    }
  }
}

Template queryedit

The query field in the template query can no longer be used. This 1.x syntax can no longer be used:

template query의 query field는 더 이상 사용할 수 없다. 아래 1.x 구문은 더 이상 사용할 수 없다.

{
    "query": {
        "template": {
            "query": {"match_{{template}}": {}},
            "params" : {
                "template" : "all"
            }
        }
    }
}

and instead the following syntax should be used:

대신 다음 구문이 사용되어야 한다.

{
    "query": {
        "template": {
            "source": {"match_{{template}}": {}},
            "params" : {
                "template" : "all"
            }
        }
    }
}

Search templatesedit

The top level template field in the search template api has been replaced with consistent template / script object syntax. This 1.x syntax can no longer be used:

search template API에서 top level template field는 consistent template / script object로 대체되었다. 아래 1.x 구문은 더 이상 사용할 수 없다.

{
    "template" : {
        "query": { "match" : { "{{my_field}}" : "{{my_value}}" } },
        "size" : "{{my_size}}"
    },
    "params" : {
        "my_field" : "foo",
        "my_value" : "bar",
        "my_size" : 5
    }
}

and instead the following syntax should be used:

대신 다음 구문이 사용되어야 한다.

{
    "source" : {
        "query": { "match" : { "{{my_field}}" : "{{my_value}}" } },
        "size" : "{{my_size}}"
    },
    "params" : {
        "my_field" : "foo",
        "my_value" : "bar",
        "my_size" : 5
    }
}

Indexed scripts and templatesedit

Indexed scripts and templates have been replaced by stored scripts which stores the scripts and templates in the cluster state instead of a dedicate .scripts index.

indexed script와 template은 전용 .scripts index 대신 script와 template을 cluster state에 저장하는stored scripts로 대체되었다.

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.

stored script의 크기에는 65535 byte의 soft limit이 있다. script가 이 크기를 초과하면 soft limit를 더 큰 값으로 변경하기 위해 elasticsearch.yml에 script.max_size_in_bytes 설정을 추가할 수 있다. script가 아주 큰 경우 native script 같은 다른 option을 고려해야 한다.

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 current format of the scripts and templates hasn’t been changed, only the 1.x format has been removed.

Elasticsearch가 이제 cluster state에서 script를 가져오기 때문에 .scripts index에 있는 이전의 indexed script는 더 이상 사용되지 않는다. 5.x 로 upgrade를 해도 .scripts index는 그대로 있으므로, .scriptsindex의 stored script를 cluster state로 migration해 사용할 수 있다. script 및 template의 현재 형식은 변경되지 않았으며 1.x 형식만 제거되었다.

Python migration scriptedit

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

다음의 Python script를 사용하여 indexed script를 stored script로서 cluster state로 가져올 수 있다.

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 seeelasticsearch-py.

이 script는 공식 Elasticsearch Python client를 사용하므로, 사용자 환경에 client가 설치되어 있는지 확인해야 한다. 이에 대한 더 많은 정보는 elasticsearch-py를 참조하자.

Perl migration scriptedit

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

다음의 Perl script를 사용하여 indexed script를 stored script로서 cluster state로 가져올 수 있다.

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 seeSearch::Elasticsearch.

이 script는 공식 Elasticsearch Perl client를 사용하므로, 사용자 환경에 client가 설치되어 있는지 확인해야 한다. 이에 대한 더 많은 정보는 Search::Elasticsearch를 참조하자.

Verifying script migrationedit

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:

제공된 script나 다른 방법을 통해 script를 옮긴 후 migration이 성공적이었는지를 다음 request를 통해 확인할 수 있다.

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.

response는 .scripts index의 모든 script를 포함해야 한다. 모든 script가 옮겨졌다는 것을 확인한 후에, (마지막 단계로서 선택적) Elasticsearch가 더 이상 그것을 사용하지 않으므로 .scripts index를 삭제할 수 있다.

Indexed scripts Java APIsedit

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.

indexed script와 상호 작용하는 것과 관련된 모든 method가 제거되었습니다. stored script와 상호 작용하기 위한 Java API method가 ClusterAdminClient class 아래에 추가되었다. indexed script API method에 존재했던 sugar method는 stored script의 method에 존재하지 않는다. script를 제공하는 유일한 방법은 BytesReference 구현을 사용하는 것입니다. 문자열을 제공해야 할 경우 BytesArray 클래스를 사용해야 한다.

Scripting engines now register only a single languageedit

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.

5.0.0 이전에는 script engine이 여러 언어를 등록할 수 있었다. Javascript script engine은 특히 "lang": "js" 와 "lang": "javascript" 모두를 등록했었다. 이제 script engine은 단일 언어만 등록 할 수 있다. "lang": "js" 에 대한 모든 참조는 lang-javascript plugin의 기존 사용자에 대해 "lang": "javascript"로 변경되어야 한다.

Scripting engines now register only a single extensionedit

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.

5.0.0 이전에는 script 엔진이 여러 확장자로 등록할 수 있었다. 이를 하는 유일한 엔진은 "js" 와 "javascript" 를 등록한 Javascript engine이었다. 이제 디스크상의 script를 위한 "js" 파일 확장자만 등록할 수 있다.

.javascript files are no longer supported (use .js)edit

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

Javascript engine은 이전에 "js" 와 "javascript" 를 등록했었다. 이제 디스크상의 script를 위한 "js" 파일 확장자만 등록할 수 있다.

Removed scripting query string parameters from update rest apiedit

The script, script_id and scripting_upsert query string parameters have been removed from the update api.

script, script_id, scripting_upsert query string parameter는 update API에서 제거되었다.

Java transport clientedit

The TemplateQueryBuilder has been moved to the lang-mustache module. Therefor when using the TemplateQueryBuilder from the Java native client the lang-mustache module should be on the classpath. Also the transport client should load the lang-mustache module as plugin:

TemplateQueryBuilder 가 lang-mustache module로 옮겨졌다. 따라서 Java native client에서TemplateQueryBuilder 를 사용할 때 lang-mustache module이 classpath에 있어야 한다. 또한 transport client는 lang-mustache module을 plugin으로 로드해야 한다.

TransportClient transportClient = TransportClient.builder()
        .settings(Settings.builder().put("node.name", "node"))
        .addPlugin(MustachePlugin.class)
        .build();
transportClient.addTransportAddress(
        new InetSocketTransportAddress(new InetSocketAddress(InetAddresses.forString("127.0.0.1"), 9300))
);

Also the helper methods in QueryBuilders class that create a TemplateQueryBuilder instance have been removed, instead the constructors on TemplateQueryBuilder should be used.

또한 TemplateQueryBuilder instance를 생성하는 QueryBuilders class의 helper method가 제거되었으므로 `TemplateQueryBuilder`의 생성자가 사용되어야 한다.

Template queryedit

The template query has been deprecated in favour of the search template api. The template query is scheduled to be removed in the next major version.

template query는 search template API를 위하여 deprecate되었다. template query는 다음 major version에서 제거될 예정이다.

GeoPoint scriptsedit

The following helper methods have been removed from GeoPoint scripting:

GeoPoint script에서 다음 helper method가 제거되었다.

• factorDistance
• factorDistanceWithDefault
• factorDistance02
• factorDistance13
• arcDistanceInKm
• arcDistanceInKmWithDefault
• arcDistanceInMiles
• arcDistanceInMilesWithDefault
• distanceWithDefault
• distanceInKm
• distanceInKmWithDefault
• distanceInMiles
• distanceInMilesWithDefault
• geohashDistanceInKm
• geohashDistanceInMiles

Instead use arcDistance, arcDistanceWithDefault, planeDistance, planeDistanceWithDefault, geohashDistance, geohashDistanceWithDefault and convert from default units (meters) to desired units using the appropriate constance (e.g., multiply by 0.001 to convert to Km).

대신.arcDistance, arcDistanceWithDefault, planeDistance, planeDistanceWithDefault, geohashDistance, geohashDistanceWithDefault 를 사용하자. 적절한 단위를 사용하여 기본 단위(meter)에서 원하는 단위로 변경하자. (예 : 0.001 을 곱하여 Km으로 변환).

Only 15 unique scripts can be compiled per minute by defaultedit

If you compile too many unique scripts within a small amount of time, Elasticsearch will reject the new dynamic scripts with a circuit_breaking_exception error. By default, up to 15 inline scripts per minute will be compiled. You can change this setting dynamically by settingscript.max_compilations_per_minute.

짧은 시간 안에 너무 많은 고유한 script를 compile하면 Elasticsearch는 새로운 동적 스크립트를 거부하고circuit_breaking_exception 오류가 발생시킨다. 기본적으로 분(minute)당 최대 15 개의 inline script가 compile된다. script.max_compilations_per_minute 를 설정하여 이 설정을 동적으로 변경할 수 있다.

You should watch out for this if you are hard-coding values into your scripts.

script에 값을 hard-coding하는 경우에는 주의해야 한다.

Elasticsearch recommends the usage of parameters for efficient script handling. See details here.

Elasticsearch는 효율적인 script 처리를 위해 parameter 사용을 권장한다. 자세한 내용은 여기를 참조하십시오.