FSST LIKE: _ single-byte wildcard for prefix/suffix patterns

Extend the LikeKind parser and the KMP byte-table / suffix byte-table
construction to treat `_` (byte 0x5F) as the SQL single-byte wildcard.
Anchored shapes — `prefix%` and `%suffix` — gain wildcard support;
each `_` position transitions on every byte instead of one literal.

Unanchored shapes (`%contains%`, `%seg1%seg2%`) are still rejected
when any `_` appears: KMP's failure function with wildcards is
unsound (treats `_` as symmetrically compatible with any pattern
byte, producing false positives at the DFA level). A correct
unanchored wildcard matcher needs NFA subset construction; tracked
as a follow-up.

Changes:
- `dfa/mod.rs`: add `WILDCARD = b'_'`, `pattern_eq`,
  `pattern_matches_byte`. Update `kmp_byte_transitions` to fill the
  row (any byte advances) at wildcard positions; `kmp_failure_table`
  uses wildcard-aware pattern equality.
- `dfa/prefix.rs::build_prefix_byte_table`: fill the row at wildcard
  positions.
- `dfa/suffix.rs::build_suffix_byte_table`: same, for the
  backward-scanned suffix.
- `dfa/mod.rs::LikeKind::parse`: accept `_` in `Prefix` and `Suffix`
  variants; still reject in `Contains` / `MultiContains`.
- `needle_bytes_absent_from_all_symbols` skips wildcard positions
  when computing the literal-byte symbol overlap; the escape-only
  memmem fast path is gated on `needle_is_literal`.

Adds 6 wildcard tests covering prefix, suffix, multi-wildcard,
leading-wildcard, symbol-interaction, and the deliberate
contains-rejection. All 163 existing + new tests pass.

Signed-off-by: Claude <noreply@anthropic.com>

Author: claude

encodings/fsst/src/dfa/flat_contains.rs

@@ -104,6 +104,7 @@ impl FlatContainsDfa {
         // `all_bytes` whose length matches the encoded needle. Disabled
         // for L < 2 (no possible win over the existing scan path).
         let escape_only_pattern = (needle.len() >= 2
+            && super::needle_is_literal(needle)
             && needle_bytes_absent_from_all_symbols(symbols, symbol_lengths, needle))
         .then(|| build_escape_only_encoded_pattern(needle));
 

encodings/fsst/src/dfa/folded_contains.rs

@@ -328,12 +328,13 @@ impl FoldedContainsDfa {
         });
 
         // Escape-only fast path: when no symbol's expansion contains any
-        // needle byte, the only DFA-accepting compressed sequence is the
-        // 2L-byte pattern `[ESCAPE, needle[0], …, ESCAPE, needle[L-1]]`.
-        // Only enable for L >= 2 — at L = 1 the encoded pattern is
-        // identical to the existing escape_pair 2-byte memmem, so taking
-        // a separate path would just add a redundant branch.
+        // needle byte AND the needle has no `_` wildcards, the only
+        // DFA-accepting compressed sequence is the 2L-byte pattern
+        // `[ESCAPE, needle[0], …, ESCAPE, needle[L-1]]`. With wildcards
+        // present the encoded pattern is no longer unique and the
+        // memmem prefilter is disabled.
         let escape_only_pattern = (needle.len() >= 2
+            && super::needle_is_literal(needle)
             && needle_bytes_absent_from_all_symbols(symbols, symbol_lengths, needle))
         .then(|| build_escape_only_encoded_pattern(needle));
 

encodings/fsst/src/dfa/mod.rs

@@ -327,29 +327,37 @@ enum LikeKind<'a> {
 
 impl<'a> LikeKind<'a> {
     fn parse(pattern: &'a [u8]) -> Option<Self> {
-        // `prefix%` (including just `%` where prefix is empty)
+        // `prefix%` (including just `%` where prefix is empty).
+        // `_` in the prefix is the single-byte wildcard (anchored from
+        // the row start, no KMP fallback ambiguity).
         if let Some(prefix) = pattern.strip_suffix(b"%")
             && !prefix.contains(&b'%')
-            && !prefix.contains(&b'_')
         {
             return Some(LikeKind::Prefix(prefix));
         }
 
-        // `%suffix` (no trailing %)
+        // `%suffix` (no trailing %); `_` allowed in suffix (anchored
+        // from the row end, scanned right-to-left, also wildcard-safe).
         if let Some(suffix) = pattern.strip_prefix(b"%")
             && !suffix.contains(&b'%')
-            && !suffix.contains(&b'_')
         {
             return Some(LikeKind::Suffix(suffix));
         }
 
-        // `%needle%`
+        // `%needle%`. We reject `_` in unanchored contains for now —
+        // the symmetric KMP failure function over-approximates when
+        // wildcards appear in the matched portion, producing false
+        // positives. A correct unanchored wildcard matcher needs NFA
+        // subset construction (or per-position sliding-window match);
+        // tracked as a follow-up.
         let inner = pattern.strip_prefix(b"%")?.strip_suffix(b"%")?;
         if !inner.contains(&b'%') && !inner.contains(&b'_') {
             return Some(LikeKind::Contains(inner));
         }
 
-        // `%seg1%seg2%...%segN%`
+        // `%seg1%seg2%...%segN%`. Same wildcard limitation: any
+        // segment containing `_` falls through to the
+        // decompression-based fallback.
         let segments: Vec<&[u8]> = inner
             .split(|&b| b == b'%')
             .filter(|s| !s.is_empty())
@@ -413,23 +421,30 @@ where
 // DFA construction helpers
 // ---------------------------------------------------------------------------
 
-/// Returns `true` iff no byte of `needle` appears in any symbol's expansion.
+/// Returns `true` iff no literal byte of `needle` appears in any symbol's
+/// expansion. Wildcard (`_`) positions are skipped — they're allowed to
+/// match symbol bytes and don't constrain the prefilter.
 ///
-/// When this holds, every needle byte in the decompressed stream must come
-/// from an `ESCAPE` pair, so the only compressed sequence that reaches the
-/// contains DFA's accept state from state 0 is exactly
+/// When this holds AND the needle has no wildcards, every needle byte in
+/// the decompressed stream must come from an `ESCAPE` pair, so the only
+/// compressed sequence that reaches the contains DFA's accept state
+/// from state 0 is exactly
 /// `[ESCAPE, needle[0], ESCAPE, needle[1], …, ESCAPE, needle[L-1]]`. The
 /// contains scan can then prefilter with a single `memmem` for that 2L-byte
-/// pattern, which is dramatically more selective than the 2-byte
-/// `(ESCAPE, needle[0])` anchor that the bucketed Teddy pair scan would
-/// otherwise use.
+/// pattern. For needles WITH wildcards, the same condition implies each
+/// literal byte must come from an escape pair, but wildcard bytes can
+/// come from anywhere — the encoded pattern is no longer unique, so
+/// the memmem prefilter is disabled.
 pub(super) fn needle_bytes_absent_from_all_symbols(
     symbols: &[Symbol],
     symbol_lengths: &[u8],
     needle: &[u8],
 ) -> bool {
     let mut needle_byte_present = [false; 256];
     for &b in needle {
+        if b == WILDCARD {
+            continue;
+        }
         needle_byte_present[usize::from(b)] = true;
     }
     debug_assert!(symbol_lengths.len() >= symbols.len());
@@ -447,7 +462,8 @@ pub(super) fn needle_bytes_absent_from_all_symbols(
 
 /// Build the compressed pattern `[ESCAPE, needle[0], ESCAPE, needle[1], …,
 /// ESCAPE, needle[L-1]]`. Only meaningful when
-/// [`needle_bytes_absent_from_all_symbols`] is true.
+/// [`needle_bytes_absent_from_all_symbols`] is true AND the needle is
+/// wildcard-free.
 pub(super) fn build_escape_only_encoded_pattern(needle: &[u8]) -> Vec<u8> {
     let mut out = Vec::with_capacity(needle.len() * 2);
     for &b in needle {
@@ -457,6 +473,12 @@ pub(super) fn build_escape_only_encoded_pattern(needle: &[u8]) -> Vec<u8> {
     out
 }
 
+/// `true` iff the needle has no `_` wildcard bytes.
+#[inline]
+pub(super) fn needle_is_literal(needle: &[u8]) -> bool {
+    !needle.contains(&WILDCARD)
+}
+
 /// Builds the per-symbol transition table for FSST symbols.
 ///
 /// For each `(state, symbol_code)` pair, simulates feeding the symbol's bytes
@@ -581,20 +603,44 @@ fn build_fused_table(
 // KMP helpers
 // ---------------------------------------------------------------------------
 
+/// The wildcard byte in a LIKE needle. SQL `_` (`0x5F`) is interpreted
+/// as "match any single byte" by [`kmp_byte_transitions`] and
+/// [`kmp_failure_table`]. Without SQL `ESCAPE` support, every `_`
+/// in the parsed needle is a wildcard; a literal `_` cannot be
+/// expressed.
+pub(super) const WILDCARD: u8 = b'_';
+
+/// Pattern-position byte equality with wildcard semantics. Returns
+/// `true` if `a` or `b` is the [`WILDCARD`] byte, or both bytes are
+/// equal.
+#[inline]
+fn pattern_eq(a: u8, b: u8) -> bool {
+    a == WILDCARD || b == WILDCARD || a == b
+}
+
+/// Concrete-input byte match against a needle position. The pattern
+/// position `p` is one of the needle bytes (possibly the wildcard);
+/// the input byte `b` is always concrete (never a wildcard).
+#[inline]
+fn pattern_matches_byte(p: u8, b: u8) -> bool {
+    p == WILDCARD || p == b
+}
+
 /// Build the `(state × byte) → state` KMP transition table.
 ///
 /// ## Construction
 ///
 /// Uses the standard recurrence — for each non-accept state `s`:
-///   - On byte == `needle[s]`: transition to `s + 1`.
+///   - On byte == `needle[s]` (or `needle[s]` is the wildcard): transition to `s + 1`.
 ///   - On any other byte: transition to whatever the *failure* row
 ///     would give for the same byte, i.e. `table[failure[s-1] * 256 + b]`
 ///     for `s > 0`, and `0` for `s = 0`.
 ///
+/// When `needle[s]` is the [`WILDCARD`] byte (`_`), every input byte
+/// advances to `s + 1` regardless of the failure row's content.
+///
 /// This is one 256-byte memcpy + a single override per state, instead
-/// of running the KMP fallback loop at every cell. For an N=6 needle
-/// that's 6 × 256 = 1536 bytes copied + 6 overrides vs ~3500 iterative
-/// fallback steps previously — about 3× faster.
+/// of running the KMP fallback loop at every cell.
 fn kmp_byte_transitions(needle: &[u8]) -> Vec<u8> {
     let n_states = u8::try_from(needle.len() + 1)
         .vortex_expect("kmp_byte_transitions: must have needle.len() ≤ 255");
@@ -603,12 +649,16 @@ fn kmp_byte_transitions(needle: &[u8]) -> Vec<u8> {
 
     let mut table = vec![0u8; usize::from(n_states) * 256];
 
-    // State 0: only `needle[0]` advances.
-    if !needle.is_empty() {
-        table[usize::from(needle[0])] = 1;
+    // State 0: either `needle[0]` (literal) or every byte (wildcard) advances.
+    if let Some(&first) = needle.first() {
+        if first == WILDCARD {
+            table[0..256].fill(1);
+        } else {
+            table[usize::from(first)] = 1;
+        }
     }
 
-    // States 1..accept: each row is the failure-row plus one advance entry.
+    // States 1..accept: each row is the failure-row plus the advance entry.
     for state in 1..accept {
         let s = usize::from(state);
         let fail_row = usize::from(failure[s - 1]) * 256;
@@ -617,14 +667,18 @@ fn kmp_byte_transitions(needle: &[u8]) -> Vec<u8> {
         // the KMP fallback eventually lands at the same place the
         // failure-state would land on that byte.
         table.copy_within(fail_row..fail_row + 256, state_row);
-        // Override the one entry that advances.
-        table[state_row + usize::from(needle[s])] = state + 1;
+        // Override the advancing entries.
+        if needle[s] == WILDCARD {
+            // Wildcard at position s: every byte advances.
+            table[state_row..state_row + 256].fill(state + 1);
+        } else {
+            table[state_row + usize::from(needle[s])] = state + 1;
+        }
     }
 
     // Accept state: sticky — every byte stays at accept.
     if usize::from(accept) < usize::from(n_states) {
         let accept_row = usize::from(accept) * 256;
-        // SAFETY-ish: in-bounds writes to a pre-zeroed Vec.
         table[accept_row..accept_row + 256].fill(accept);
     }
 
@@ -635,10 +689,10 @@ fn kmp_failure_table(needle: &[u8]) -> Vec<u8> {
     let mut failure = vec![0u8; needle.len()];
     let mut k = 0u8;
     for i in 1..needle.len() {
-        while k > 0 && needle[usize::from(k)] != needle[i] {
+        while k > 0 && !pattern_eq(needle[usize::from(k)], needle[i]) {
             k = failure[usize::from(k) - 1];
         }
-        if needle[usize::from(k)] == needle[i] {
+        if pattern_eq(needle[usize::from(k)], needle[i]) {
             k += 1;
         }
         failure[i] = k;

encodings/fsst/src/dfa/multi_contains.rs

@@ -419,7 +419,9 @@ fn compute_escape_only_anchor(
         return None;
     }
     let longest = segments.iter().max_by_key(|s| s.len())?;
-    if longest.len() < 2 {
+    if longest.len() < 2 || !super::needle_is_literal(longest) {
+        // The encoded pattern is only well-defined when the longest
+        // (anchor) segment is wildcard-free.
         return None;
     }
     // Union of every segment's bytes is what must be absent from symbols.

encodings/fsst/src/dfa/prefix.rs

@@ -237,14 +237,20 @@ fn build_prefix_byte_table(prefix: &[u8], accept_state: u8, fail_state: u8) -> V
                 table[s * 256 + byte] = accept_state;
             }
         } else if state != fail_state {
-            // Only the correct next byte advances; everything else fails.
-            let next_byte = prefix[s];
             let next_state = if s + 1 >= prefix.len() {
                 accept_state
             } else {
                 state + 1
             };
-            table[s * 256 + usize::from(next_byte)] = next_state;
+            if prefix[s] == super::WILDCARD {
+                // Wildcard: every byte advances.
+                for byte in 0..256 {
+                    table[s * 256 + byte] = next_state;
+                }
+            } else {
+                // Only the literal byte advances; everything else fails.
+                table[s * 256 + usize::from(prefix[s])] = next_state;
+            }
         }
     }
     table

encodings/fsst/src/dfa/suffix.rs

@@ -209,14 +209,21 @@ fn build_suffix_byte_table(suffix: &[u8], accept_state: u8, fail_state: u8) -> V
             }
         } else if state != fail_state {
             // State s: confirmed s bytes from the right. Next byte must be
-            // suffix[suf_len - 1 - s] to advance.
+            // suffix[suf_len - 1 - s] to advance — or any byte if that
+            // pattern position is the `_` wildcard.
             let expected = suffix[suf_len - 1 - s];
             let next_state = if s + 1 >= suf_len {
                 accept_state
             } else {
                 state + 1
             };
-            table[s * 256 + usize::from(expected)] = next_state;
+            if expected == super::WILDCARD {
+                for byte in 0..256 {
+                    table[s * 256 + byte] = next_state;
+                }
+            } else {
+                table[s * 256 + usize::from(expected)] = next_state;
+            }
         }
         // fail_state stays fail for all bytes (default)
     }