Accessing document fields and special variables

Depending on where a script is used, it will have access to certain special variables and document fields.

A script used in the update, update-by-query, or reindex API will have access to the ctx variable which exposes:

With the exception of script fields which are executed once per search hit, scripts used in search and aggregations will be executed once for every document which might match a query or an aggregation. Depending on how many documents you have, this could mean millions or billions of executions: these scripts need to be fast!

Field values can be accessed from a script using doc-values, or stored fields or _source field, which are explained below.

Scripts used in the function_score query, in script-based sorting, or in aggregations have access to the _score variable which represents the current relevance score of a document.

Here’s an example of using a script in a function_score query to alter the relevance _score of each document:

PUT my_index/my_type/1?refresh
{
  "text": "quick brown fox",
  "popularity": 1
}

PUT my_index/my_type/2?refresh
{
  "text": "quick fox",
  "popularity": 5
}

GET my_index/_search
{
  "query": {
    "function_score": {
      "query": {
        "match": {
          "text": "quick brown fox"
        }
      },
      "script_score": {
        "script": {
          "lang": "expression",
          "source": "_score * doc['popularity']"
        }
      }
    }
  }
}

By far the fastest most efficient way to access a field value from a script is to use the doc['field_name'] syntax, which retrieves the field value from doc values. Doc values are a columnar field value store, enabled by default on all fields except for analyzed text fields.

PUT my_index/my_type/1?refresh
{
  "cost_price": 100
}

GET my_index/_search
{
  "script_fields": {
    "sales_price": {
      "script": {
        "lang":   "expression",
        "source": "doc['cost_price'] * markup",
        "params": {
          "markup": 0.2
        }
      }
    }
  }
}

Doc-values can only return "simple" field values like numbers, dates, geo- points, terms, etc, or arrays of these values if the field is multi-valued. It cannot return JSON objects.

Stored fields — fields explicitly marked as "store": true — can be accessed using the _fields['field_name'].value or _fields['field_name'].values syntax.

The document _source, which is really just a special stored field, can be accessed using the _source.field_name syntax. The _source is loaded as a map-of-maps, so properties within object fields can be accessed as, for example, _source.name.first.

For instance:

PUT my_index
{
  "mappings": {
    "my_type": {
      "properties": {
        "title": { 
          "type": "text"
        },
        "first_name": {
          "type": "text",
          "store": true
        },
        "last_name": {
          "type": "text",
          "store": true
        }
      }
    }
  }
}

PUT my_index/my_type/1?refresh
{
  "title": "Mr",
  "first_name": "Barry",
  "last_name": "White"
}

GET my_index/_search
{
  "script_fields": {
    "source": {
      "script": {
        "lang": "painless",
        "source": "params._source.title + ' ' + params._source.first_name + ' ' + params._source.last_name" 
      }
    },
    "stored_fields": {
      "script": {
        "lang": "painless",
        "source": "params._fields['first_name'].value + ' ' + params._fields['last_name'].value"
      }
    }
  }
}