[BUG] Wildcard Query: Escaped Backslash before operator

[lumaier]

Describe the bug

An escaped backslash directly in front of the wildcard operator * is not correctly handled.

Related component

Search:Query Capabilities

To Reproduce

1. Create an index with a wildcard field:

curl -X PUT "http://localhost/my-index" -H 'Content-Type: application/json' -d'
{
    "mappings": {
        "properties": {
            "wildcard_field": {
                "type": "wildcard"
            }
        }
    }
}
'

2. Insert a document containing a backslash:

curl -X POST "http://localhost/my-index/_doc/1" -H 'Content-Type: application/json' -d'
{
  "wildcard_field": "some\\string"
}
'

3. Query the document:

This query correctly returns the document:

curl -X GET "http://localhost/my-index/search" -H 'Content-Type: application/json' -d'
{
  "query": {
    "wildcard": {
      "wildcard_field": {
        "value": "*some\\\\str*"
      }
    }
  }
}
'

But this query returns nothing (even tough it should return the same document):

curl -X GET "http://localhost/my-index/search" -H 'Content-Type: application/json' -d'
{
  "query": {
    "wildcard": {
      "wildcard_field": {
        "value": "*some\\\\*"
      }
    }
  }
}
'

Expected behavior

An escaped backslash before the operator * in a wildcard query must be treated as the literal character \.

Additional Details

Plugins
None

Screenshots
None

Host/Environment (please complete the following information):

• OS: Docker image (Host: Linux Ubuntu 24)
• Version docker.io/opensearchproject/opensearch:3.2.0 and docker.io/opensearchproject/opensearch:3.3.0

Additional context
None

[msfroh]

We have a unit test for general escaped wildcard queries:

OpenSearch/server/src/test/java/org/opensearch/index/mapper/WildcardFieldTypeTests.java

Line 99 in e62bf1a

public void testEscapedWildcardQuery() {

There is escaping logic in

OpenSearch/server/src/main/java/org/opensearch/index/mapper/WildcardFieldMapper.java

Line 534 in f0f8078

private static String performEscape(String str, boolean regexpMode) {

, which does treat \ as a special character that can be escaped.

For whoever picks this up, I would start by creating a unit test in WildcardFieldTypeTests to reproduce the issue. That might be enough to show what's not working. Also, adding a test to the yaml REST tests would be a good idea.

A mild challenge with the wildcard field type is that queries have a two-phase behavior -- the first phase tries to match trigrams (which in this case should be som, ome, and me\) while the second phase checks the matched strings against the wildcard pattern. If either phase is wrong, you'd miss results.

[Deven009]

Hi @lumaier @msfroh @sandeshkr419, I’d like to work on this issue. This will be my first open-source contribution, and since it’s tagged as a “good first issue,” I think it’s a great place to start.

Could you please assign it to me or let me know if it’s available?

[Deven009]

@sandeshkr419 Thank you for giving me this opportunity.

@lumaier Thank you for detailed bug report.

@msfroh Thank you so much for excellent debugging hints. Your description of the two-phase behavior was particularly helpful in tracking down the root cause.

Root Cause

• The bug is in the getNonWildcardSequence. When processing *some\\* (escaped backslash + wildcard), it checks if the character before * is a backslash but doesn't account for that backslash itself being escaped.

• Result: getNonWildcardSequence("*some\\\\*", 1) returns "some\\\\*" instead of "some\\\\", causing invalid ngrams like e\* that include the wildcard character.

Fix

Count consecutive backslashes before wildcards:

• Even count: wildcard is NOT escaped → end sequence
• Odd count: wildcard IS escaped → continue

Will raise a PR soon. Thanks! 🙏