OpenSearch/docs/reference/query-dsl/script-query.asciidoc

[[query-dsl-script-query]]
=== Script query
++++
<titleabbrev>Script</titleabbrev>
++++

Filters documents based on a provided <<modules-scripting-using,script>>. The
`script` query is typically used in a <<query-filter-context,filter context>>.


[[script-query-ex-request]]
==== Example request

[source,console]
----
GET /_search
{
    "query": {
        "bool" : {
            "filter" : {
                "script" : {
                    "script" : {
                        "source": "doc['num1'].value > 1",
                        "lang": "painless"
                     }
                }
            }
        }
    }
}
----


[[script-top-level-params]]
==== Top-level parameters for `script`

`script`::
(Required, <<modules-scripting-using, script object>>) Contains a script to run
as a query. This script must return a boolean value, `true` or `false`.

[[script-query-notes]]
==== Notes

[[script-query-custom-params]]
===== Custom Parameters

Like <<query-filter-context,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:

[source,console]
----
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 <<query-dsl-allow-expensive-queries, `search.allow_expensive_queries`>>
is set to false.