[FEATURE] Document '_name' field in 'function_score' query function definition and in explanation response

[reta]

Is your feature request related to a problem?
As part of opensearch-project/OpenSearch#1711, we have introduced _name support of 'function_score' functions (complementing queries and filters in these regards). The _name, if specified, is returned back as part of explanation whenever it dims possible (it applies to functions, filters and queries).

What solution would you like?
Document the usage of _name field and its impact on explanation descriptions. Couple of examples below:

• request / response with script function score

"functions": [
    {
      "script_score": {
        "script": {
          "lang": "painless",
          "source": "return doc['user_name'].contains('cash') ? 1 : 0;"            }
      },
      "weight": 65,
      // NEW: Function name 
      "_name": "func1"
    }, ...    
]

{
    "value": 0.0,
      // NEW: Function name is returned back
    "description": "script score function(_name: func1), computed with script:\"Script{type=inline, lang='painless', idOrCode='return doc['user_name'].contains('cash') ? 1 : 0;', options={}, params={}}\"",
    "details": [
        {
            "value": 1.0,
            "description": "_score: ",
            "details": [
                {
                    "value": 1.0,
                    "description": "*:*",
                    "details": []
                }
            ]
        }
    ]
}

• request / response with random function score

"functions": [
    {
        "random_score": {
           // NEW: Function name 
           "_name": "func2"
        }
    }, ...    
]

{
    "value": 0.38554674,
    // NEW: Function name is returned back
    "description": "random score function (seed: 738562412, field: null, _name: func2)",
    "details": []
} ...

• request / response with filter score function

"functions": [
    {
        "filter": {
            "terms": {
               // Query names are supported
                "_name": "terms_filter",
                "abc": [
                  "1"
                ]
              }
            },
        "weight": 35
    }, ...    
]

{
    "value": 1.0,
    // NEW: Query name is returned back
    "description": "match filter(_name: terms_filter): abc:{1}",
    "details": []
}

• request / response with function score query

 "function_score": {
      "query": {
        "match_all": {
            // Query names are supported
            "_name": "q1"
        }
      },
      ...
}

{
    "value": 1.0,
    "description": "_score: ",
    "details": [
        {
            "value": 1.0,
            // NEW: Query name is returned back
            "description": "*:* (_name: q1)",
            "details": []
        }
    ]
}

What alternatives have you considered?
N/A

Do you have any additional context?
N/A

[Naarcha-AWS]

@reta: Looks like the function_score query isn't documented. Do you have a design document or would be to explain to me where the function_score fits into our current DSL documentation?

[reta]

Hey @Naarcha-AWS , precisely, the function_score largely corresponds to the original feature in Elasticsearch [1], we certainly won't be copying it as-is but I am wondering what was/is our approach to replicating Elasticsearch documentation in the Opensearch for same features? Thank you!

[1] https://www.elastic.co/guide/en/elasticsearch/reference/7.10/query-dsl-function-score-query.html

[lrynek]

@Naarcha-AWS @dblock @reta Are we going to document this feature // any help I can provide on this one? 🤔

[reta]

@lrynek thanks, it would be great to know where exactly we should add that, afaik there is (was) no documentation for function_score at all

[hdhalter]

Reassigning to Fanit, as she is handling query DSL. We had another request to document function_score: #3218

[hdhalter]

The function_score query is now documented here: https://opensearch.org/docs/latest/query-dsl/compound/function-score/. We have not specifically called out _name, though.

@kolchfa-aws - can you please take a look at this when you switch back to query DSL? Thanks!

[lrynek]

@hdhalter If you want I can edit the function_score query page accordingly to what @reta proposed - only refer to me any guidance material on how to contribute to the documentation, thx! 🙂

[kolchfa-aws]

That would be wonderful, @lrynek, thanks! We have contributing info in the https://github.com/opensearch-project/documentation-website/blob/main/CONTRIBUTING.md file. Let me know if you have any questions, I'll be happy to help.

[hdhalter]

Hi @lrynek , just checking in to see if you still want to update the content? Let us know if you need additional guidance. Thanks, in advance!

[lrynek]

@hdhalter It has taken me some considerable amount of time to read through all the docs about contributing 😅 I've stuck a bit in the setup of the project locally but I will love to proceed on the next 2 days max with it // maybe I wanted to be too perfect for the first iteration, sorry 😉

[kolchfa-aws]

Thanks, @lrynek! Let me know if I can help in any way.

[lrynek]

I have to pass as stopped on bundler installation of the documentation app in Ruby... 🤷🏻 Sorry, at least tried here...

[hdhalter]

Thanks for trying again @lrynek , we will take a look at the instructions to see what the problem is. In the meantime, there is an easier way to contribute. You can open the page you want to edit (for example, https://opensearch.org/docs/latest/query-dsl/compound/function-score/) and click the 'Edit this page' link. It allows you to edit the markdown and push up a pull request pretty quickly. You just won't be able to test the page locally.

[lrynek]

Ok, I thought for a larger contribution it would be advisable to not push a PR failing on many quality checks but if it's acceptable, I'll give it a try directly 👍 (but surely the docs drove me a bit that "perfect way", as I initially had taken the initiative with less effort in mind 😉)

[hdhalter]

Yeah, for structural changes it makes sense to test locally, but changes to a single topic can typically be made directly to the page and pushed up. We do a pretty thorough review before merging, so we'll catch anything that may be out of whack. Of course, perfect PRs are preferred :), but we gladly accept any contribution that corrects technical inaccuracies. Thanks again.

[hdhalter]

Hi @lrynek , just circling back to see if you wanted to attempt another pass at updating the content? We've made some updates and added a troubleshooting section to the contribution file, so maybe this time it will work? Thanks!

[lrynek]

Hi @hdhalter, thanks for that ❤️. I will give it a try over the week, as recently it was very busy period than at the moment of the first attempt. In touch - if I won't manage I will let you know within the upcoming week. Thanks for reminding 🙏🏻

[lrynek]

@hdhalter @kolchfa-aws I've prepared the draft PR #7340 - please correct whatever makes sense there // I'm still on the explanation side (I'll setup the week that follows an analogical index as to the blog documents that are described in the docs to fetch actual OpenSearch generated response explanation in the example there).