Skip to content

Commit b0ebb50

Browse files
lrynekkolchfa-awsnatebower
authored
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>
1 parent 0d9fc0e commit b0ebb50

File tree

1 file changed

+194
-1
lines changed

1 file changed

+194
-1
lines changed

‎_query-dsl/compound/function-score.md

+194-1
Original file line numberDiff line numberDiff line change
@@ -826,4 +826,197 @@ The results contain the three matching blog posts:
826826
}
827827
}
828828
```
829-
</details>
829+
</details>
830+
831+
## Named functions
832+
833+
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.
834+
835+
### Example
836+
837+
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:
838+
839+
```json
840+
GET blogs/_search
841+
{
842+
"explain": true,
843+
"size": 1,
844+
"query": {
845+
"function_score": {
846+
"functions": [
847+
{
848+
"_name": "likes_function",
849+
"script_score": {
850+
"script": {
851+
"lang": "painless",
852+
"source": "return doc['likes'].value * 2;"
853+
}
854+
},
855+
"weight": 0.6
856+
},
857+
{
858+
"_name": "views_function",
859+
"field_value_factor": {
860+
"field": "views",
861+
"factor": 1.5,
862+
"modifier": "log1p",
863+
"missing": 1
864+
},
865+
"weight": 0.3
866+
},
867+
{
868+
"_name": "comments_function",
869+
"gauss": {
870+
"comments": {
871+
"origin": 1000,
872+
"scale": 800
873+
}
874+
},
875+
"weight": 0.1
876+
}
877+
]
878+
}
879+
}
880+
}
881+
```
882+
{% include copy-curl.html %}
883+
884+
The response explains the scoring process. For each function, the explanation contains the function `_name` in its `description`:
885+
886+
<details open markdown="block">
887+
<summary>
888+
Response
889+
</summary>
890+
{: .text-delta}
891+
892+
```json
893+
{
894+
"took": 14,
895+
"timed_out": false,
896+
"_shards": {
897+
"total": 1,
898+
"successful": 1,
899+
"skipped": 0,
900+
"failed": 0
901+
},
902+
"hits": {
903+
"total": {
904+
"value": 3,
905+
"relation": "eq"
906+
},
907+
"max_score": 6.1600614,
908+
"hits": [
909+
{
910+
"_shard": "[blogs][0]",
911+
"_node": "_yndTaZHQWimcDgAfOfRtQ",
912+
"_index": "blogs",
913+
"_id": "1",
914+
"_score": 6.1600614,
915+
"_source": {
916+
"name": "Semantic search in OpenSearch",
917+
"views": 1200,
918+
"likes": 150,
919+
"comments": 16,
920+
"date_posted": "2022-04-17"
921+
},
922+
"_explanation": {
923+
"value": 6.1600614,
924+
"description": "function score, product of:",
925+
"details": [
926+
{
927+
"value": 1,
928+
"description": "*:*",
929+
"details": []
930+
},
931+
{
932+
"value": 6.1600614,
933+
"description": "min of:",
934+
"details": [
935+
{
936+
"value": 6.1600614,
937+
"description": "function score, score mode [multiply]",
938+
"details": [
939+
{
940+
"value": 180,
941+
"description": "product of:",
942+
"details": [
943+
{
944+
"value": 300,
945+
"description": "script score function(_name: likes_function), computed with script:\"Script{type=inline, lang='painless', idOrCode='return doc['likes'].value * 2;', options={}, params={}}\"",
946+
"details": [
947+
{
948+
"value": 1,
949+
"description": "_score: ",
950+
"details": [
951+
{
952+
"value": 1,
953+
"description": "*:*",
954+
"details": []
955+
}
956+
]
957+
}
958+
]
959+
},
960+
{
961+
"value": 0.6,
962+
"description": "weight",
963+
"details": []
964+
}
965+
]
966+
},
967+
{
968+
"value": 0.9766541,
969+
"description": "product of:",
970+
"details": [
971+
{
972+
"value": 3.2555137,
973+
"description": "field value function(_name: views_function): log1p(doc['views'].value?:1.0 * factor=1.5)",
974+
"details": []
975+
},
976+
{
977+
"value": 0.3,
978+
"description": "weight",
979+
"details": []
980+
}
981+
]
982+
},
983+
{
984+
"value": 0.035040613,
985+
"description": "product of:",
986+
"details": [
987+
{
988+
"value": 0.35040614,
989+
"description": "Function for field comments:",
990+
"details": [
991+
{
992+
"value": 0.35040614,
993+
"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)",
994+
"details": []
995+
}
996+
]
997+
},
998+
{
999+
"value": 0.1,
1000+
"description": "weight",
1001+
"details": []
1002+
}
1003+
]
1004+
}
1005+
]
1006+
},
1007+
{
1008+
"value": 3.4028235e+38,
1009+
"description": "maxBoost",
1010+
"details": []
1011+
}
1012+
]
1013+
}
1014+
]
1015+
}
1016+
}
1017+
]
1018+
}
1019+
}
1020+
```
1021+
</details>
1022+

0 commit comments

Comments
 (0)