mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-29 09:54:06 -04:00
a8b2428dd1
* Restructure query-languages docs files for clarity (#124797) 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. * After running tests, we revert a few features * Fix build.gradle and improved some generating code * After running tests * Update x-pack/plugin/esql/build.gradle
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.
|
||
|
||
|
||
|