mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-29 09:54:06 -04:00
94cad286bc
In a few previous PR's we restructured the ES|QL docs to make it possible to generate them dynamically. This PR just moves a few files around to make the query languages docs easier to work with, and a little more organized like the ES|QL docs. A bit part of this was setting up redirects to the new locations, so other repo's could correctly link to the elasticsearch docs.
115 lines
3.2 KiB
Markdown
115 lines
3.2 KiB
Markdown
---
|
||
navigation_title: "Script"
|
||
mapped_pages:
|
||
- https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-script-query.html
|
||
---
|
||
|
||
# Script query [query-dsl-script-query]
|
||
|
||
|
||
::::{note}
|
||
[Runtime fields](docs-content://manage-data/data-store/mapping/runtime-fields.md) 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`](/reference/elasticsearch/rest-apis/retrieve-selected-fields.md), [all queries](/reference/query-languages/querydsl.md), and [aggregations](/reference/data-analysis/aggregations/index.md).
|
||
::::
|
||
|
||
|
||
Filters documents based on a provided [script](docs-content://explore-analyze/scripting/modules-scripting-using.md). The `script` query is typically used in a [filter context](/reference/query-languages/query-dsl/query-filter-context.md).
|
||
|
||
::::{warning}
|
||
Using scripts can result in slower search speeds. See [Scripts, caching, and search speed](docs-content://explore-analyze/scripting/scripts-search-speed.md).
|
||
::::
|
||
|
||
|
||
## Example request [script-query-ex-request]
|
||
|
||
```console
|
||
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`](/reference/elasticsearch/rest-apis/retrieve-selected-fields.md) parameter on the `_search` API to fetch values as part of the same query:
|
||
|
||
```console
|
||
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-top-level-params]
|
||
|
||
`script`
|
||
: (Required, [script object](docs-content://explore-analyze/scripting/modules-scripting-using.md)) Contains a script to run as a query. This script must return a boolean value, `true` or `false`.
|
||
|
||
|
||
## Notes [script-query-notes]
|
||
|
||
### Custom parameters [script-query-custom-params]
|
||
|
||
Like [filters](/reference/query-languages/query-dsl/query-filter-context.md), 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:
|
||
|
||
```console
|
||
GET /_search
|
||
{
|
||
"query": {
|
||
"bool": {
|
||
"filter": {
|
||
"script": {
|
||
"script": {
|
||
"source": "doc['num1'].value > params.param1",
|
||
"lang": "painless",
|
||
"params": {
|
||
"param1": 5
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
|
||
### Allow expensive queries [_allow_expensive_queries_4]
|
||
|
||
Script queries will not be executed if [`search.allow_expensive_queries`](/reference/query-languages/querydsl.md#query-dsl-allow-expensive-queries) is set to false.
|
||
|
||
|
||
|