› › ›

Script query

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

resp = client.search(
    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          "
                }
            }
        }
    },
)
print(resp)

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

const response = await client.search({
  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          ",
        },
      },
    },
  },
});
console.log(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:

resp = client.search(
    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"
        }
    ],
)
print(resp)

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

const response = await client.search({
  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",
    },
  ],
});
console.log(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`

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

Notes

Custom Parameters

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:

resp = client.search(
    query={
        "bool": {
            "filter": {
                "script": {
                    "script": {
                        "source": "doc['num1'].value > params.param1",
                        "lang": "painless",
                        "params": {
                            "param1": 5
                        }
                    }
                }
            }
        }
    },
)
print(resp)

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

const response = await client.search({
  query: {
    bool: {
      filter: {
        script: {
          script: {
            source: "doc['num1'].value > params.param1",
            lang: "painless",
            params: {
              param1: 5,
            },
          },
        },
      },
    },
  },
});
console.log(response);

GET /_search
{
  "query": {
    "bool": {
      "filter": {
        "script": {
          "script": {
            "source": "doc['num1'].value > params.param1",
            "lang": "painless",
            "params": {
              "param1": 5
            }
          }
        }
      }
    }
  }
}

Allow expensive queries

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

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/query-dsl-script-query.html