Document '_name' field in 'function_score' query's function definition (

opensearch-project#7340) * Document '_name' field in 'function_score' query function definition Signed-off-by: Łukasz Rynek <lukasz.rynek@gmail.com> * Ensure real request JSON payload Signed-off-by: Łukasz Rynek <lukasz.rynek@gmail.com> * Ensure real response JSON payload + finish the paragraph Signed-off-by: Łukasz Rynek <lukasz.rynek@gmail.com> * Add missing copy-curl tag Signed-off-by: Łukasz Rynek <lukasz.rynek@gmail.com> * Add missing article Signed-off-by: Łukasz Rynek <lukasz.rynek@gmail.com> * 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 <nbower@amazon.com> Signed-off-by: Łukasz Rynek <36886649+lrynek@users.noreply.github.com> --------- Signed-off-by: Łukasz Rynek <lukasz.rynek@gmail.com> 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 <nbower@amazon.com> Signed-off-by: Sander van de Geijn <sandervandegeijn@icloud.com>
sandervandegeijn · Jul 30, 2024 · 6a22bbe · 6a22bbe
1 parent f2ba70c
commit 6a22bbe
Showing 1 changed file with 194 additions and 1 deletion.
diff --git 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:
   }
 }
 ```
-</details>
+</details>
+
+## 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`:
+
+<details open markdown="block">
+  <summary>
+    Response
+  </summary>
+  {: .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": []
+                }
+              ]
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+</details>
+