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

#7340) * Document '_name' field in 'function_score' query function definition Signed-off-by: Łukasz Rynek <[email protected]> * Ensure real request JSON payload Signed-off-by: Łukasz Rynek <[email protected]> * Ensure real response JSON payload + finish the paragraph Signed-off-by: Łukasz Rynek <[email protected]> * Add missing copy-curl tag Signed-off-by: Łukasz Rynek <[email protected]> * Add missing article Signed-off-by: Łukasz Rynek <[email protected]> * Apply suggestions from code review Co-authored-by: kolchfa-aws <[email protected]> Signed-off-by: Łukasz Rynek <[email protected]> * Apply suggestions from code review Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: Łukasz Rynek <[email protected]> --------- Signed-off-by: Łukasz Rynek <[email protected]> Signed-off-by: Łukasz Rynek <[email protected]> Co-authored-by: kolchfa-aws <[email protected]> Co-authored-by: Nathan Bower <[email protected]>
opensearch-project · Jul 9, 2024 · b0ebb50 · b0ebb50
1 parent 0d9fc0e
commit b0ebb50
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>
+