[DOC] Document new doc/term frequency functions in Painless score scripts

[msfroh]

What do you want to do?

• Request a change to existing documentation
• Add new documentation
• Report a technical problem with the documentation
• Other

Tell us about your request. Provide a summary of the request and all versions that are affected.
Starting in version 2.10, OpenSearch will support four new frequency functions to be used in Painless score scripts. While this is likely to be an expert feature only, we should document their existence and what they do.

Note that these functions should show equivalent behavior to the similarly named functions in Apache Solr, since the underlying Lucene implementation is the same: https://solr.apache.org/guide/solr/latest/query-guide/function-queries.html

What other resources are available? Provide links to related issues, POCs, steps for testing, etc.

• [Feature] Expose term frequency in Painless script score context OpenSearch#9081
• Expose term frequency in Painless script score context OpenSearch#7558
• [RFC] Enhanced Access to Term-Level Statistics in OpenSearch OpenSearch#8702

[kolchfa-aws]

@msfroh @noCharger We don't have any documentation on Painless or script score query. Given that this is a very specific expert use case, I propose that we hold documenting these frequency functions until we have at least some basic Painless documentation. In the meantime, if you add an example to this issue, we can point users here. What are your thoughts?

[noCharger]

I'd recommend putting the new features here.

1. Create a new section regarding term frequency functions, similar to https://opensearch.org/docs/latest/query-dsl/compound/function-score#decay-functions, but indicate that they are only supported in 'script_score' on 2.10.
2. Include a link to the new section in https://opensearch.org/docs/latest/query-dsl/compound/function-score/#the-script-score-function.

[noCharger]

Supported functions:

int termFreq(String, String)
float tf(String, String)
long totalTermFreq(String, String)
long sumTotalTermFreq(String)

Their solr examples:

• termfreq
• tf
• totaltermfreq
• sumtotaltermfreq

Example query

GET /demo_index_v1/_search
{
  "query": {
    "function_score": {
      "query": {
        "match_all": {}
      },
      "script_score": {
        "script": {
          "source": """
            for (int x = 0; x < params.fields.length; x++) {
              String field = params.fields[x];
              if (field != null) {
                return params.multiplier * totalTermFreq(field, params.term);
              }
            }
            return params.default_value;
            
          """,
          "params": {
              "fields": ["title", "description"],
              "term": "ai",
              "multiplier": 2,
              "default_value": 1
          }
        }
      }
    }
  }
}

[kolchfa-aws]

I'm proposing an alternative location: I will create a script_score query page with basic details, and then we can add these four new methods to that page.

[noCharger]

#4970 Merged 👍