feat: Implement Mustache template support for search queries

[Bharathi-Kanna]

Description

This PR implements backend support for Mustache templates in search queries using OpenSearch's native
ScriptService

Key Changes:

Integrated Mustache Templating

• Modified SearchRelevancePlugin.javato capture and pass ScriptService
• Updated SearchRequestBuilder.java to compile and execute Mustache templates
• Added automatic detection: queries with {{ use Mustache, others use legacy %SearchText%

Maintained Backward Compatibility

• All existing %SearchText% queries continue to work without changes
• No data model modifications
• No migration required

Example Usage

Mustache Template (New):

{
  "query": {
    "match": { "title": "{{queryText}}" }
  }
}

Legacy Placeholder (Still Works):

{
  "query": {
    "match": { "title": "%SearchText%" }
  }
}

Both syntaxes work side-by-side. The system auto-detects which one to use.

Current Limitation: Single-parameter queries only (matches existing QuerySetEntry as List)
Multi-parameter support (e.g., {{brand}}, {{category}}) requires data model changes and will be addressed in a future PR.

Issues Resolved

Relates to #41

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[epugh]

Looks like you are on the right path..

[epugh]

@Bharathi-Kanna could you set up signing of yoru commits? WHen you sign with git commit -s -S you will get a green "VERIFIED" mark here:

[epugh]

Looks like good progress. We still need some tests for handling it.. Let me know how I can help!

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 0.00%. Comparing base (2fcc381) to head (eeeebec).

Additional details and impacted files

@@     Coverage Diff     @@
##   main   #342   +/-   ##
===========================
===========================

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Bharathi-Kanna]

Hi @epugh,

Thanks for the feedback! I've added:

• Test methods
• DCO sign-off on commits
• CHANGELOG entry

This PR enables Mustache templating with {{query_string}} support.

Would you prefer this incremental approach, or include data model changes in this PR?

[heemin32]

This is good but I think we could extend this further and support multiple custom variables instead of single fixed query text.

Example 1

{
    "query": {
      "bool": {
        "must": {
          "match": { "title": "{{query_string}}" }
        },
        "filter": [
          { "term": { "status": "{{status}}" } },
          { "term": { "category": "{{category}}" } }
        ]
      }
    }
  }

Example 2

{
    "query": {
      "bool": {
        "must": {
          "match": { "title": "{{query_string}}" }
        },
        "filter": [ {{filter}} ]
      }
    }
  }

[Bharathi-Kanna]

Hi @heemin32 !

Thank you for the feedback, I completely agree.

I've just pushed a major update to this PR that fully implements what you described!
Users can now define their queries with arbitrary keys like this:

{
  "queryText": "laptop",
  "status": "active",
  "category": "electronics"
}

And those values will automatically hydrate the exact Mustache template configurations you provided in your examples (e.g., {{status}}, {{category}}).

To ensure a seamless implementation, I also:
Updated the LLM Judgment processor cache to include the custom fields in the deduplication key so we don't accidentally serve cached judgments for queries that share the same queryText but have different filters.

[heemin32]

@Bharathi-Kanna Thanks for the change! By the way, wouldn't it be sufficient to simply use string replacement instead of relying on the script service?

Or at least can we disable partial from mustache?

MustacheFactory factory = new DefaultMustacheFactory(name -> null);

[Bharathi-Kanna]

Thanks @heemin32 !

On string replacement: I'd prefer to keep ScriptService. It uses OpenSearch's managed Mustache engine, which JSON-escapes values automatically. Plain string replacement would break on quotes and other special characters in the query text, and could also introduce a DSL injection risk.

On partials: You're right, I checked, and OpenSearch's CustomMustacheFactory doesn't disable them. However, the DefaultMustacheFactory(name -> null) approach can't be wired in directly because we go through ScriptService, not the raw Mustache library. Instead, I'll reject templates containing {{> during validation to close that vector while keeping the managed engine. Does that sound reasonable?

[heemin32]

Thanks @heemin32 !

On string replacement: I'd prefer to keep ScriptService. It uses OpenSearch's managed Mustache engine, which JSON-escapes values automatically. Plain string replacement would break on quotes and other special characters in the query text, and could also introduce a DSL injection risk.

On partials: You're right, I checked, and OpenSearch's CustomMustacheFactory doesn't disable them. However, the DefaultMustacheFactory(name -> null) approach can't be wired in directly because we go through ScriptService, not the raw Mustache library. Instead, I'll reject templates containing {{> during validation to close that vector while keeping the managed engine. Does that sound reasonable?

Simple validation won't handle several other edge cases. One example is {{ > partial}} space before >. I think we might delay the support of mustache until OpenSearch core disable partial unless we use Mustache library directly.

[heemin32]

We could use mustache now as OpenSearch core disabled partial template resolution.
opensearch-project/OpenSearch#22438

[heemin32]

@Bharathi-Kanna could you open the corresponding document update pr for this change?

[github-actions]

PR Code Analyzer ❗

AI-powered 'Code-Diff-Analyzer' found issues on commit 0a9290b.

Path	Line	Severity	Description
build.gradle	248	high	New dependency added: 'org.opensearch.plugin:lang-mustache-client:${opensearch_version}'. Per mandatory supply chain rule, all dependency additions must be flagged regardless of apparent legitimacy. Maintainers should verify the artifact resolves to the expected OpenSearch core module and that the version variable is pinned as intended.
src/test/resources/searchconfig/CreateSearchConfigurationQueryWithPartial.json	4	low	Test fixture contains a Mustache partial referencing '/etc/passwd' ({{>/etc/passwd}}). Context indicates this is a defensive security test verifying that partial templates are rejected by the engine. The corresponding test explicitly asserts a 'Partial templates are not supported' failure, making malicious intent implausible, but the path reference is anomalous and warrants maintainer awareness.

The table above displays the top 10 most important findings.

Total: 2 | Critical: 0 | High: 1 | Medium: 0 | Low: 1

---

Pull Requests Author(s): Please update your Pull Request according to the report above.

Repository Maintainer(s): You can bypass diff analyzer by adding label skip-diff-analyzer after reviewing the changes carefully, then re-run failed actions. To re-enable the analyzer, remove the label, then re-run all actions.

---

⚠️ Note: The Code-Diff-Analyzer helps protect against potentially harmful code patterns. Please ensure you have thoroughly reviewed the changes beforehand.

Thanks.

[Bharathi-Kanna]

Hi @heemin32,
I've opened the corresponding documentation PR: opensearch-project/documentation-website#12810

[heemin32]

Hi @heemin32, I've opened the corresponding documentation PR: opensearch-project/documentation-website#12810

Thanks. While I reviewing the document, I found this is a little confusing.

Mustache Template (New):

{
  "query": {
    "match": { "title": "{{query_string}}" }
  }
}

Legacy Placeholder (Still Works):

{
  "query": {
    "match": { "title": "%SearchText%" }
  }
}

Shouldn't we just keep it consistent from query sets field name?

{
  "query": {
    "match": { "title": "{{queryText}}" }
  }
}

[Bharathi-Kanna]

Applied and updated all ,Thanks @heemin32 !