elasticsearch/docs/plugins/lang-python.asciidoc

[[lang-python]]
=== Python Language Plugin

The Python language plugin enables the use of Python in Elasticsearch
scripts, via the http://www.jython.org/[Jython] Java implementation of Python.

[[lang-python-install]]
[float]
==== Installation

This plugin can be installed using the plugin manager:

[source,sh]
----------------------------------------------------------------
sudo bin/elasticsearch-plugin install lang-python
----------------------------------------------------------------

The plugin must be installed on every node in the cluster, and each node must
be restarted after installation.

[[lang-python-remove]]
[float]
==== Removal

The plugin can be removed with the following command:

[source,sh]
----------------------------------------------------------------
sudo bin/elasticsearch-plugin remove lang-python
----------------------------------------------------------------

The node must be stopped before removing the plugin.

[[lang-python-usage]]
==== Using Python in Elasticsearch

Once the plugin has been installed, Python can be used at a scripting
language by setting the `lang` parameter to `python`.

Scripting is available in many APIs, but we will use an example with the
`function_score` for demonstration purposes:

[[lang-python-inline]]
[float]
=== Inline scripts

WARNING: Enabling inline scripting on an unprotected Elasticsearch cluster is dangerous.
See <<lang-python-file>> for a safer option.

If you have enabled {ref}/modules-scripting-security.html#enable-dynamic-scripting[inline scripts],
you can use Python as follows:

[source,js]
----
PUT test/doc/1
{
  "num": 1.0
}

PUT test/doc/2
{
  "num": 2.0
}

GET test/_search
{
  "query": {
    "function_score": {
      "script_score": {
        "script": {
          "inline": "doc[\"num\"].value * factor",
          "lang": "python",
          "params": {
            "factor": 2
          }
        }
      }
    }
  }
}
----
// CONSOLE

[[lang-python-stored]]
[float]
=== Stored scripts

WARNING: Enabling stored scripts on an unprotected Elasticsearch cluster is dangerous.
See <<lang-python-file>> for a safer option.

If you have enabled {ref}/modules-scripting-security.html#enable-dynamic-scripting[stored scripts],
you can use Python as follows:

[source,js]
----
PUT test/doc/1
{
  "num": 1.0
}

PUT test/doc/2
{
  "num": 2.0
}

POST _scripts/python/my_script  <1>
{
  "script": "doc[\"num\"].value * factor"
}

GET test/_search
{
  "query": {
    "function_score": {
      "script_score": {
        "script": {
          "id": "my_script", <2>
          "lang": "python",
          "params": {
            "factor": 2
          }
        }
      }
    }
  }
}

----
// CONSOLE

<1> We store the script under the id `my_script`.
<2> The function score query retrieves the script with id `my_script`.


[[lang-python-file]]
[float]
=== File scripts

You can save your scripts to a file in the `config/scripts/` directory on
every node. The `.py` file suffix identifies the script as containing
Python:

First, save this file as `config/scripts/my_script.py` on every node
in the cluster:

[source,python]
----
doc["num"].value * factor
----

then use the script as follows:

[source,js]
----
PUT test/doc/1
{
  "num": 1.0
}

PUT test/doc/2
{
  "num": 2.0
}

GET test/_search
{
  "query": {
    "function_score": {
      "script_score": {
        "script": {
          "file": "my_script", <1>
          "lang": "python",
          "params": {
            "factor": 2
          }
        }
      }
    }
  }
}
----
// CONSOLE

<1> The function score query retrieves the script with filename `my_script.py`.