IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Rank feature query Script score query »
Elastic Docs ›Elasticsearch Guide [8.12] ›Query DSL ›Specialized queries

Script query

edit

Script query

edit

Runtime fields provide a very similar feature that is more flexible. You write a script to create field values and they are available everywhere, such as fields, all queries, and aggregations.

Filters documents based on a provided script. The script query is typically used in a filter context.

Using scripts can result in slower search speeds. See Scripts, caching, and search speed.

Example request

edit
response = client.search(
  body: {
    query: {
      bool: {
        filter: {
          script: {
            script: "\n            double amount = doc['amount'].value;\n            if (doc['type'].value == 'expense') {\n              amount *= -1;\n            }\n            return amount < 10;\n          "
          }
        }
      }
    }
  }
)
puts response
GET /_search
{
  "query": {
    "bool": {
      "filter": {
        "script": {
          "script": """
            double amount = doc['amount'].value;
            if (doc['type'].value == 'expense') {
              amount *= -1;
            }
            return amount < 10;
          """
        }
      }
    }
  }
}

You can achieve the same results in a search query by using runtime fields. Use the fields parameter on the _search API to fetch values as part of the same query:

response = client.search(
  body: {
    runtime_mappings: {
      'amount.signed' => {
        type: 'double',
        script: "\n        double amount = doc['amount'].value;\n        if (doc['type'].value == 'expense') {\n          amount *= -1;\n        }\n        emit(amount);\n      "
      }
    },
    query: {
      bool: {
        filter: {
          range: {
            'amount.signed' => {
              lt: 10
            }
          }
        }
      }
    },
    fields: [
      {
        field: 'amount.signed'
      }
    ]
  }
)
puts response
GET /_search
{
  "runtime_mappings": {
    "amount.signed": {
      "type": "double",
      "script": """
        double amount = doc['amount'].value;
        if (doc['type'].value == 'expense') {
          amount *= -1;
        }
        emit(amount);
      """
    }
  },
  "query": {
    "bool": {
      "filter": {
        "range": {
          "amount.signed": { "lt": 10 }
        }
      }
    }
  },
  "fields": [{"field": "amount.signed"}]
}

Top-level parameters for script

edit
script
(Required, script object) Contains a script to run as a query. This script must return a boolean value, true or false.

Notes

edit

Custom Parameters

edit

Like filters, scripts are cached for faster execution. If you frequently change the arguments of a script, we recommend you store them in the script’s params parameter. For example:

response = client.search(
  body: {
    query: {
      bool: {
        filter: {
          script: {
            script: {
              source: "doc['num1'].value > params.param1",
              lang: 'painless',
              params: {
                "param1": 5
              }
            }
          }
        }
      }
    }
  }
)
puts response
GET /_search
{
  "query": {
    "bool": {
      "filter": {
        "script": {
          "script": {
            "source": "doc['num1'].value > params.param1",
            "lang": "painless",
            "params": {
              "param1": 5
            }
          }
        }
      }
    }
  }
}

Allow expensive queries

edit

Script queries will not be executed if search.allow_expensive_queries is set to false.

« Rank feature query Script score query »