From b0ebb50900acc57a08d3061bab08fd89be0e80dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Rynek?= <36886649+lrynek@users.noreply.github.com> Date: Tue, 9 Jul 2024 18:59:52 +0200 Subject: [PATCH] Document '_name' field in 'function_score' query's function definition (#7340) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Document '_name' field in 'function_score' query function definition Signed-off-by: Łukasz Rynek * Ensure real request JSON payload Signed-off-by: Łukasz Rynek * Ensure real response JSON payload + finish the paragraph Signed-off-by: Łukasz Rynek * Add missing copy-curl tag Signed-off-by: Łukasz Rynek * Add missing article Signed-off-by: Łukasz Rynek * Apply suggestions from code review Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Signed-off-by: Łukasz Rynek <36886649+lrynek@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: Łukasz Rynek <36886649+lrynek@users.noreply.github.com> --------- Signed-off-by: Łukasz Rynek Signed-off-by: Łukasz Rynek <36886649+lrynek@users.noreply.github.com> Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Co-authored-by: Nathan Bower --- _query-dsl/compound/function-score.md | 195 +++++++++++++++++++++++++- 1 file changed, 194 insertions(+), 1 deletion(-) diff --git a/_query-dsl/compound/function-score.md b/_query-dsl/compound/function-score.md index 8180058ae6..98568e0965 100644 --- a/_query-dsl/compound/function-score.md +++ b/_query-dsl/compound/function-score.md @@ -826,4 +826,197 @@ The results contain the three matching blog posts: } } ``` - \ No newline at end of file + + +## Named functions + +When defining a function, you can specify its name using the `_name` parameter at the top level. This name is useful for debugging and understanding the scoring process. Once specified, the function name is included in the score calculation explanation whenever possible (this applies to functions, filters, and queries). You can identify the function by its `_name` in the response. + +### Example + +The following request sets `explain` to `true` for debugging purposes in order to obtain a scoring explanation in the response. Each function contains a `_name` parameter so that you can identify the function unambiguously: + +```json +GET blogs/_search +{ + "explain": true, + "size": 1, + "query": { + "function_score": { + "functions": [ + { + "_name": "likes_function", + "script_score": { + "script": { + "lang": "painless", + "source": "return doc['likes'].value * 2;" + } + }, + "weight": 0.6 + }, + { + "_name": "views_function", + "field_value_factor": { + "field": "views", + "factor": 1.5, + "modifier": "log1p", + "missing": 1 + }, + "weight": 0.3 + }, + { + "_name": "comments_function", + "gauss": { + "comments": { + "origin": 1000, + "scale": 800 + } + }, + "weight": 0.1 + } + ] + } + } +} +``` +{% include copy-curl.html %} + +The response explains the scoring process. For each function, the explanation contains the function `_name` in its `description`: + +
+ + Response + + {: .text-delta} + +```json +{ + "took": 14, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 3, + "relation": "eq" + }, + "max_score": 6.1600614, + "hits": [ + { + "_shard": "[blogs][0]", + "_node": "_yndTaZHQWimcDgAfOfRtQ", + "_index": "blogs", + "_id": "1", + "_score": 6.1600614, + "_source": { + "name": "Semantic search in OpenSearch", + "views": 1200, + "likes": 150, + "comments": 16, + "date_posted": "2022-04-17" + }, + "_explanation": { + "value": 6.1600614, + "description": "function score, product of:", + "details": [ + { + "value": 1, + "description": "*:*", + "details": [] + }, + { + "value": 6.1600614, + "description": "min of:", + "details": [ + { + "value": 6.1600614, + "description": "function score, score mode [multiply]", + "details": [ + { + "value": 180, + "description": "product of:", + "details": [ + { + "value": 300, + "description": "script score function(_name: likes_function), computed with script:\"Script{type=inline, lang='painless', idOrCode='return doc['likes'].value * 2;', options={}, params={}}\"", + "details": [ + { + "value": 1, + "description": "_score: ", + "details": [ + { + "value": 1, + "description": "*:*", + "details": [] + } + ] + } + ] + }, + { + "value": 0.6, + "description": "weight", + "details": [] + } + ] + }, + { + "value": 0.9766541, + "description": "product of:", + "details": [ + { + "value": 3.2555137, + "description": "field value function(_name: views_function): log1p(doc['views'].value?:1.0 * factor=1.5)", + "details": [] + }, + { + "value": 0.3, + "description": "weight", + "details": [] + } + ] + }, + { + "value": 0.035040613, + "description": "product of:", + "details": [ + { + "value": 0.35040614, + "description": "Function for field comments:", + "details": [ + { + "value": 0.35040614, + "description": "exp(-0.5*pow(MIN[Math.max(Math.abs(16.0(=doc value) - 1000.0(=origin))) - 0.0(=offset), 0)],2.0)/461662.4130844683, _name: comments_function)", + "details": [] + } + ] + }, + { + "value": 0.1, + "description": "weight", + "details": [] + } + ] + } + ] + }, + { + "value": 3.4028235e+38, + "description": "maxBoost", + "details": [] + } + ] + } + ] + } + } + ] + } +} +``` +
+