handle asterisks

Signed-off-by: Kai Huang <[email protected]>

Author: ahkcs

core/src/main/java/org/opensearch/sql/calcite/utils/WildcardReplaceUtils.java

@@ -19,9 +19,8 @@
  * <p>Supports wildcard patterns using '*' to match zero or more characters. Wildcards in the
  * replacement string are substituted with values captured from the pattern match.
  *
- * <p>Limitation: Literal asterisk characters cannot be matched or replaced when using wildcard
- * patterns. To replace literal asterisks in data, use non-wildcard (literal) replacement mode by
- * not including '*' in the pattern string.
+ * <p>Escape sequences: Use '\*' to match literal asterisks and '\\' to match literal backslashes.
+ * Without escapes, '*' is interpreted as a wildcard pattern.
  */
 public class WildcardReplaceUtils {
 
@@ -42,6 +41,9 @@ public static String replaceWithWildcard(String input, String pattern, String re
       return null;
     }
 
+    validateEscapeSequences(pattern);
+    validateEscapeSequences(replacement);
+
     if (!pattern.contains("*")) {
       return input.replace(pattern, replacement);
     }
@@ -54,6 +56,22 @@ public static String replaceWithWildcard(String input, String pattern, String re
     return substituteWildcards(replacement, captures);
   }
 
+  /** Validate that string doesn't end with unescaped backslash. */
+  private static void validateEscapeSequences(String str) {
+    boolean escaped = false;
+    for (char c : str.toCharArray()) {
+      if (escaped) {
+        escaped = false;
+      } else if (c == '\\') {
+        escaped = true;
+      }
+    }
+    if (escaped) {
+      throw new IllegalArgumentException(
+          "Invalid escape sequence: pattern ends with unescaped backslash");
+    }
+  }
+
   /** Match pattern against input and capture wildcard portions. */
   public static List<String> matchAndCapture(String input, String pattern) {
     Pattern compiledPattern =
@@ -71,9 +89,46 @@ public static List<String> matchAndCapture(String input, String pattern) {
     return captures;
   }
 
+  /**
+   * Split pattern on unescaped wildcards, handling escape sequences.
+   *
+   * <p>Supports: \* (literal asterisk), \\ (literal backslash)
+   *
+   * @param pattern Wildcard pattern with potential escapes
+   * @return Array of literal parts between wildcards
+   * @throws IllegalArgumentException if pattern ends with unescaped backslash
+   */
+  private static String[] splitWildcards(String pattern) {
+    List<String> parts = new ArrayList<>();
+    StringBuilder current = new StringBuilder();
+    boolean escaped = false;
+
+    for (char c : pattern.toCharArray()) {
+      if (escaped) {
+        current.append(c);
+        escaped = false;
+      } else if (c == '\\') {
+        escaped = true;
+      } else if (c == '*') {
+        parts.add(current.toString());
+        current = new StringBuilder();
+      } else {
+        current.append(c);
+      }
+    }
+
+    if (escaped) {
+      throw new IllegalArgumentException(
+          "Invalid escape sequence: pattern ends with unescaped backslash");
+    }
+
+    parts.add(current.toString());
+    return parts.toArray(new String[0]);
+  }
+
   /** Compile a wildcard pattern to a regex Pattern. */
   private static Pattern compileWildcardPattern(String pattern) {
-    String[] parts = pattern.split("\\*", -1);
+    String[] parts = splitWildcards(pattern);
     StringBuilder regexBuilder = new StringBuilder("^");
 
     for (int i = 0; i < parts.length; i++) {
@@ -89,15 +144,17 @@ private static Pattern compileWildcardPattern(String pattern) {
 
   /** Substitute wildcards in replacement string with captured values. */
   public static String substituteWildcards(String replacement, List<String> captures) {
-    if (!replacement.contains("*")) {
-      return replacement;
-    }
-
     StringBuilder result = new StringBuilder();
     int captureIndex = 0;
+    boolean escaped = false;
 
     for (char c : replacement.toCharArray()) {
-      if (c == '*') {
+      if (escaped) {
+        result.append(c);
+        escaped = false;
+      } else if (c == '\\') {
+        escaped = true;
+      } else if (c == '*') {
         if (captureIndex < captures.size()) {
           result.append(captures.get(captureIndex));
           captureIndex++;
@@ -107,14 +164,24 @@ public static String substituteWildcards(String replacement, List<String> captur
       }
     }
 
+    if (escaped) {
+      throw new IllegalArgumentException(
+          "Invalid escape sequence: replacement ends with unescaped backslash");
+    }
+
     return result.toString();
   }
 
-  /** Count the number of wildcards in a string. */
+  /** Count the number of unescaped wildcards in a string. */
   public static int countWildcards(String str) {
     int count = 0;
+    boolean escaped = false;
     for (char c : str.toCharArray()) {
-      if (c == '*') {
+      if (escaped) {
+        escaped = false;
+      } else if (c == '\\') {
+        escaped = true;
+      } else if (c == '*') {
         count++;
       }
     }

docs/user/ppl/cmd/replace.rst

@@ -251,10 +251,75 @@ When using wildcards in the replace command:
 * Pattern: ``"* - *"`` (2 wildcards), Replacement: ``"*"`` (1 wildcard) ✗ (mismatch error)
 
 
+Escape Sequences
+================
+
+To match or replace literal asterisks or backslashes in your data, use escape sequences:
+
+* ``\*`` - Matches a literal asterisk character
+* ``\\`` - Matches a literal backslash character
+
+Without escapes, asterisks are interpreted as wildcards.
+
+Example 11: Matching literal asterisks
+---------------------------------------
+
+Match and replace literal asterisk characters in data.
+
+PPL query::
+
+ os> source=accounts | eval note = 'price: *sale*' | replace 'price: \*sale\*' WITH 'DISCOUNTED' IN note | fields note;
+ fetched rows / total rows = 4/4
+ +------------+
+ | note       |
+ |------------|
+ | DISCOUNTED |
+ | DISCOUNTED |
+ | DISCOUNTED |
+ | DISCOUNTED |
+ +------------+
+
+Example 12: Wildcard with no replacement wildcards
+----------------------------------------------------
+
+Use wildcards in pattern but none in replacement to create a fixed output.
+
+PPL query::
+
+ os> source=accounts | eval test = 'prefix-value-suffix' | replace 'prefix-*-suffix' WITH 'MATCHED' IN test | fields test;
+ fetched rows / total rows = 4/4
+ +---------+
+ | test    |
+ |---------|
+ | MATCHED |
+ | MATCHED |
+ | MATCHED |
+ | MATCHED |
+ +---------+
+
+Example 13: Escaped asterisks with wildcards
+---------------------------------------------
+
+Combine escaped asterisks (literal) with wildcards for complex patterns.
+
+PPL query::
+
+ os> source=accounts | eval label = 'file123.txt' | replace 'file*.*' WITH '\**.*' IN label | fields label;
+ fetched rows / total rows = 4/4
+ +----------+
+ | label    |
+ |----------|
+ | *123.txt |
+ | *123.txt |
+ | *123.txt |
+ | *123.txt |
+ +----------+
+
+
 Limitations
 ===========
 * Pattern and replacement values must be string literals.
 * The replace command modifies the specified fields in-place.
 * Wildcard matching is case-sensitive.
 * Regular expressions are not supported (only simple wildcard patterns with ``*``).
-* Literal asterisk characters (``*``) cannot be matched or replaced when using wildcard patterns. To replace literal asterisks in your data, use non-wildcard patterns (do not include ``*`` in the pattern string).
+* Use backslash escape sequences (``\*``, ``\\``) to match literal asterisks or backslashes.

integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalciteReplaceCommandIT.java

@@ -495,4 +495,50 @@ public void testWildcardReplace_emptyStringIntegration() throws IOException {
         rows("John", "Canada"),
         rows("Jane", "Canada"));
   }
+
+  @Test
+  public void testEscapeSequence_literalAsterisk() throws IOException {
+    // Test matching literal asterisks in data using \* escape sequence
+    JSONObject result =
+        executeQuery(
+            String.format(
+                "source = %s | eval note = 'price: *sale*' | replace 'price: \\\\*sale\\\\*' WITH"
+                    + " 'DISCOUNTED' IN note | fields note | head 1",
+                TEST_INDEX_STATE_COUNTRY));
+
+    verifySchema(result, schema("note", "string"));
+    // Pattern "price: \*sale\*" matches literal asterisks, result should be "DISCOUNTED"
+    verifyDataRows(result, rows("DISCOUNTED"));
+  }
+
+  @Test
+  public void testEscapeSequence_mixedEscapeAndWildcard() throws IOException {
+    // Test combining escaped asterisks (literal) with wildcards (pattern matching)
+    JSONObject result =
+        executeQuery(
+            String.format(
+                "source = %s | eval label = 'file123.txt' | replace 'file*.*' WITH"
+                    + " '\\\\**.*' IN label | fields label | head 1",
+                TEST_INDEX_STATE_COUNTRY));
+
+    verifySchema(result, schema("label", "string"));
+    // Pattern "file*.*" captures "123" and "txt"
+    // Replacement "\**.*" has escaped * (literal), then 2 wildcards, producing "*123.txt"
+    verifyDataRows(result, rows("*123.txt"));
+  }
+
+  @Test
+  public void testEscapeSequence_noMatchLiteral() throws IOException {
+    // Test that escaped asterisk doesn't match as wildcard
+    JSONObject result =
+        executeQuery(
+            String.format(
+                "source = %s | eval test = 'fooXbar' | replace 'foo\\\\*bar' WITH 'matched' IN test"
+                    + " | fields test | head 1",
+                TEST_INDEX_STATE_COUNTRY));
+
+    verifySchema(result, schema("test", "string"));
+    // Pattern "foo\*bar" matches literal "foo*bar", not "fooXbar", so original value returned
+    verifyDataRows(result, rows("fooXbar"));
+  }
 }

ppl/src/test/java/org/opensearch/sql/ppl/calcite/WildcardReplaceUtilsTest.java

@@ -274,4 +274,82 @@ public void testWildcardExample4_infixReplacement() {
     assertEquals(
         "fooALLbar", WildcardReplaceUtils.replaceWithWildcard("fooXYZbar", "*XYZ*", "*ALL*"));
   }
+
+  @Test
+  public void testEscapedAsterisk_literal() {
+    assertEquals(
+        "foo*bar", WildcardReplaceUtils.replaceWithWildcard("foo*bar", "foo\\*bar", "foo\\*bar"));
+  }
+
+  @Test
+  public void testEscapedAsterisk_noMatch() {
+    assertEquals(
+        "fooXbar", WildcardReplaceUtils.replaceWithWildcard("fooXbar", "foo\\*bar", "replacement"));
+  }
+
+  @Test
+  public void testEscapedBackslash_beforeWildcard() {
+    assertEquals(
+        "foo\\123", WildcardReplaceUtils.replaceWithWildcard("foo\\abc", "foo\\\\*", "foo\\\\123"));
+  }
+
+  @Test
+  public void testEscapedBackslash_literal() {
+    assertEquals(
+        "foo\\bar",
+        WildcardReplaceUtils.replaceWithWildcard("foo\\bar", "foo\\\\bar", "foo\\\\bar"));
+  }
+
+  @Test
+  public void testMixedEscapes_asteriskAndBackslash() {
+    assertEquals(
+        "price: *special* $100\\ea",
+        WildcardReplaceUtils.replaceWithWildcard(
+            "price: *special* $100\\ea",
+            "price: \\*special\\* $*\\\\*",
+            "price: \\*special\\* $*\\\\*"));
+  }
+
+  @Test
+  public void testEscapedAsterisk_withWildcard_capture() {
+    assertEquals(
+        "file*.prefix-123",
+        WildcardReplaceUtils.replaceWithWildcard("file123.txt", "file*.*", "file\\*.prefix-*"));
+  }
+
+  @Test
+  public void testTrailingBackslash_shouldFail() {
+    try {
+      WildcardReplaceUtils.replaceWithWildcard("foo", "foo\\", "bar");
+      fail("Expected IllegalArgumentException");
+    } catch (IllegalArgumentException exception) {
+      assertTrue(exception.getMessage().contains("Invalid escape sequence"));
+    }
+  }
+
+  @Test
+  public void testOnlyEscapedAsterisks_noWildcards() {
+    assertEquals("***", WildcardReplaceUtils.replaceWithWildcard("***", "\\*\\*\\*", "\\*\\*\\*"));
+  }
+
+  @Test
+  public void testDoubleBackslashBeforeAsterisk() {
+    assertEquals(
+        "foo\\bar", WildcardReplaceUtils.replaceWithWildcard("foo\\abc", "foo\\\\*", "foo\\\\bar"));
+  }
+
+  @Test
+  public void testCountWildcards_withEscapes() {
+    assertEquals(2, WildcardReplaceUtils.countWildcards("foo\\*bar*baz*"));
+  }
+
+  @Test
+  public void testCountWildcards_allEscaped() {
+    assertEquals(0, WildcardReplaceUtils.countWildcards("\\*\\*\\*"));
+  }
+
+  @Test
+  public void testValidation_escapedWildcardsNotCounted() {
+    WildcardReplaceUtils.validateWildcardSymmetry("foo\\**", "bar*");
+  }
 }