feat: Activate pg_trgm fuzzy search fallback and autocomplete suggest

- Add fuzzy fallback in search(): when tsvector FTS returns 0 results,
  automatically retry using pg_trgm similarity matching (content_text % ?)
  against the existing idx_mq_doc_trgm GIN trigram index
- Add translateFuzzyQuery() and buildFuzzyScoreExpr() to ElasticQueryTranslator
- Propagate cleanedSearchText through QueryResult → TranslatedQuery for fallback use
- Add suggest() method using word_similarity() for typeahead/autocomplete on
  any document field (uses the <% operator with GIN trigram index)
- Highlight fuzzy results using regexp_replace when ts_headline is not available
- 6 new unit tests for fuzzy query translation and cleanedSearchText propagation
- Configurable similarity threshold (default 0.2 for fuzzy fallback)

Author: pandor4u

framework/src/main/groovy/org/moqui/impl/context/ElasticQueryTranslator.groovy

@@ -74,6 +74,8 @@ class ElasticQueryTranslator {
         boolean trackTotal = true
         /** Fields to highlight, keyed by field name */
         Map<String, Map> highlightFields = [:]
+        /** The cleaned search text for use in fuzzy fallback */
+        String cleanedSearchText = null
     }
 
     /**
@@ -114,6 +116,7 @@ class ElasticQueryTranslator {
             tq.params = qr.params
             tq.tsqueryExpr = qr.tsqueryExpr
             tq.tsqueryParams = qr.tsqueryParams
+            tq.cleanedSearchText = qr.cleanedSearchText
         }
 
         return tq
@@ -127,6 +130,10 @@ class ElasticQueryTranslator {
         String tsqueryExpr = null
         /** Bind parameters specifically for tsqueryExpr (separate from WHERE clause params) */
         List<Object> tsqueryParams = []
+        /** If true, this query was a fuzzy/similarity query that should use pg_trgm scoring */
+        boolean isFuzzy = false
+        /** The original cleaned search text (for fuzzy fallback) */
+        String cleanedSearchText = null
     }
 
     static QueryResult translateQuery(Map queryMap) {
@@ -181,6 +188,7 @@ class ElasticQueryTranslator {
         qr.tsqueryParams = [cleanedQuery]
         qr.params = [cleanedQuery]
         qr.clause = "content_tsv @@ websearch_to_tsquery('english', ?)"
+        qr.cleanedSearchText = cleanedQuery
         return qr
     }
 
@@ -693,4 +701,35 @@ class ElasticQueryTranslator {
     static String buildHighlightExpr(String fieldJsonPath, String tsqueryExpr) {
         return "ts_headline('english', coalesce(${fieldJsonPath}, ''), ${tsqueryExpr}, 'StartSel=<em>,StopSel=</em>,MaxWords=35,MinWords=15,ShortWord=3,HighlightAll=false,MaxFragments=3,FragmentDelimiter= ... ')"
     }
+
+    // ============================================================
+    // pg_trgm Fuzzy Search Support
+    // ============================================================
+
+    /**
+     * Build a fuzzy search WHERE clause using pg_trgm's similarity operator (%).
+     * Falls back to trigram similarity when tsvector full-text search returns zero results.
+     * @param searchText The cleaned search text to match against
+     * @param threshold The minimum similarity threshold (0.0 to 1.0, default 0.3)
+     * @return A QueryResult with the pg_trgm similarity clause
+     */
+    static QueryResult translateFuzzyQuery(String searchText, double threshold = 0.3) {
+        QueryResult qr = new QueryResult()
+        if (!searchText || searchText.trim().isEmpty()) return qr
+
+        String text = searchText.trim()
+        qr.clause = "content_text % ?"
+        qr.params = [text]
+        qr.isFuzzy = true
+        qr.cleanedSearchText = text
+        return qr
+    }
+
+    /**
+     * Build the SQL for a fuzzy search score expression using pg_trgm similarity().
+     * Returns a value between 0.0 and 1.0; higher = more similar.
+     */
+    static String buildFuzzyScoreExpr() {
+        return "similarity(content_text, ?)"
+    }
 }

framework/src/main/groovy/org/moqui/impl/context/PostgresElasticClient.groovy

@@ -876,6 +876,13 @@ class PostgresElasticClient implements ElasticFacade.ElasticClient {
                     hits.add(hit)
                 }
 
+                // Fuzzy fallback: if tsvector search returned 0 results and we have a search text,
+                // retry using pg_trgm similarity matching (handles typos, misspellings)
+                if (hits.isEmpty() && tq.cleanedSearchText && tq.tsqueryExpr) {
+                    Map fuzzyResult = searchFuzzyFallback(indexNames, tq, useDbHighlights)
+                    if (fuzzyResult != null) return fuzzyResult
+                }
+
                 return [hits: [total: [value: totalCount, relation: "eq"], hits: hits],
                         _shards: [total: 1, successful: 1, failed: 0]]
             } finally { rs.close() }
@@ -1102,6 +1109,164 @@ class PostgresElasticClient implements ElasticFacade.ElasticClient {
         return (List<Map>) ((Map) result.get("hits")).get("hits")
     }
 
+    // ============================================================
+    // Fuzzy Search Fallback (pg_trgm)
+    // ============================================================
+
+    /**
+     * Fuzzy fallback search using pg_trgm similarity when tsvector FTS returns zero results.
+     * Uses the existing GIN trigram index (idx_mq_doc_trgm) on content_text.
+     * Returns null if fuzzy search also finds nothing.
+     */
+    private Map searchFuzzyFallback(List<String> indexNames, ElasticQueryTranslator.TranslatedQuery tq, boolean useDbHighlights) {
+        String searchText = tq.cleanedSearchText
+        if (!searchText) return null
+
+        String idxPlaceholders = indexNames.collect { "?" }.join(", ")
+
+        // Set the pg_trgm similarity threshold for this query (lower = more results)
+        Connection conn = getConnection()
+        PreparedStatement threshPs = conn.prepareStatement("SELECT set_limit(0.2)")
+        try { threshPs.executeQuery().close() } catch (Exception e) {
+            // set_limit may not exist in newer PG (use pg_trgm.similarity_threshold GUC instead)
+            try {
+                PreparedStatement gucPs = conn.prepareStatement("SET pg_trgm.similarity_threshold = 0.2")
+                gucPs.execute()
+                gucPs.close()
+            } catch (Exception e2) { logger.trace("Could not set pg_trgm threshold: ${e2.message}") }
+        } finally { threshPs.close() }
+
+        String fuzzyScoreExpr = ElasticQueryTranslator.buildFuzzyScoreExpr()
+
+        // Build highlight columns for fuzzy results (use ILIKE-based highlighting since we don't have a tsquery)
+        String hlSelect = ""
+        List<String> hlFieldNames = []
+        if (useDbHighlights && tq.highlightFields) {
+            List<String> hlExprs = []
+            for (String hlField in tq.highlightFields.keySet()) {
+                String jsonPath = ElasticQueryTranslator.fieldToJsonPath("document", hlField)
+                // For fuzzy matches, use a simple regexp_replace highlight since ts_headline requires a tsquery
+                hlExprs.add("regexp_replace(coalesce(${jsonPath}, ''), '(' || ? || ')', '<em>\\1</em>', 'gi') AS hl_${hlFieldNames.size()}".toString())
+                hlFieldNames.add(hlField)
+            }
+            if (hlExprs) hlSelect = ", " + hlExprs.join(", ")
+        }
+
+        String sql = """
+            SELECT doc_id, index_name, doc_type, document, ${fuzzyScoreExpr} AS _score${hlSelect}
+            FROM moqui_document
+            WHERE index_name IN (${idxPlaceholders}) AND content_text % ?
+            ORDER BY _score DESC
+            LIMIT ? OFFSET ?
+        """.trim()
+
+        // Parameters: fuzzyScoreExpr(?=searchText), hlParams, indexNames, similarity(?=searchText), limit, offset
+        List<Object> allParams = []
+        allParams.add(searchText)  // for similarity() score expression
+        // highlight params (search text for each highlight field's regexp_replace)
+        for (int h = 0; h < hlFieldNames.size(); h++) {
+            allParams.add(escapeRegex(searchText))
+        }
+        allParams.addAll(indexNames)
+        allParams.add(searchText)  // for the WHERE content_text % ?
+        allParams.add(tq.sizeLimit)
+        allParams.add(tq.fromOffset)
+
+        PreparedStatement ps = conn.prepareStatement(sql)
+        try {
+            for (int i = 0; i < allParams.size(); i++) setParam(ps, i + 1, allParams[i])
+            ResultSet rs = ps.executeQuery()
+            try {
+                List<Map> hits = []
+                while (rs.next()) {
+                    String docJson = rs.getString("document")
+                    Map source = docJson ? (Map) jsonToObject(docJson) : [:]
+                    double score = rs.getDouble("_score")
+
+                    Map hit = [_index: unprefixIndexName(rs.getString("index_name")),
+                               _id: rs.getString("doc_id"),
+                               _type: rs.getString("doc_type"),
+                               _score: score, _source: source] as Map
+
+                    if (hlFieldNames) {
+                        Map<String, List<String>> highlights = [:]
+                        for (int h = 0; h < hlFieldNames.size(); h++) {
+                            String hlResult = rs.getString("hl_${h}")
+                            if (hlResult) highlights.put(hlFieldNames[h], [hlResult])
+                        }
+                        if (highlights) hit.put("highlight", highlights)
+                    }
+
+                    hits.add(hit)
+                }
+                if (hits.isEmpty()) return null
+
+                logger.info("Fuzzy fallback matched ${hits.size()} documents for query '${searchText}'")
+                return [hits: [total: [value: (long) hits.size(), relation: "eq"], hits: hits],
+                        _shards: [total: 1, successful: 1, failed: 0]]
+            } finally { rs.close() }
+        } finally { ps.close() }
+    }
+
+    /**
+     * Suggest completions for a partial search term using pg_trgm word_similarity().
+     * Searches against document field values for typeahead/autocomplete.
+     * @param index Index name (or null for all indexes)
+     * @param field Document field to suggest from (e.g. "productName", "description")
+     * @param prefix The partial text to complete
+     * @param maxResults Maximum number of suggestions to return
+     * @return A list of suggestion maps with [text: String, score: double]
+     */
+    List<Map> suggest(String index, String field, String prefix, int maxResults = 10) {
+        if (!prefix || prefix.trim().isEmpty()) return []
+        ElasticQueryTranslator.sanitizeFieldName(field)
+        String cleanPrefix = prefix.trim()
+
+        List<String> indexNames = resolveIndexNames(index)
+        if (indexNames.isEmpty()) return []
+
+        String idxPlaceholders = indexNames.collect { "?" }.join(", ")
+        String jsonPath = ElasticQueryTranslator.fieldToJsonPath("document", field)
+
+        String sql = """
+            SELECT DISTINCT ${jsonPath} AS val, word_similarity(?, ${jsonPath}) AS score
+            FROM moqui_document
+            WHERE index_name IN (${idxPlaceholders})
+              AND ${jsonPath} IS NOT NULL
+              AND ${jsonPath} <> ''
+              AND ? <% ${jsonPath}
+            ORDER BY score DESC
+            LIMIT ?
+        """.trim()
+
+        List<Object> allParams = []
+        allParams.add(cleanPrefix)  // for word_similarity()
+        allParams.addAll(indexNames)
+        allParams.add(cleanPrefix)  // for <% operator
+        allParams.add(maxResults)
+
+        Connection conn = getConnection()
+        PreparedStatement ps = conn.prepareStatement(sql)
+        try {
+            for (int i = 0; i < allParams.size(); i++) setParam(ps, i + 1, allParams[i])
+            ResultSet rs = ps.executeQuery()
+            try {
+                List<Map> suggestions = []
+                while (rs.next()) {
+                    String text = rs.getString("val")
+                    double score = rs.getDouble("score")
+                    if (text) suggestions.add([text: text, score: score])
+                }
+                return suggestions
+            } finally { rs.close() }
+        } finally { ps.close() }
+    }
+
+    /** Escape special regex characters in a string for use in regexp_replace */
+    private static String escapeRegex(String text) {
+        return text.replaceAll(/([.\\+*?\[^\]$(){}=!<>|:\-])/, '\\\\$1')
+    }
+
     @Override
     Map validateQuery(String index, Map queryMap, boolean explain) {
         try {

framework/src/test/groovy/PostgresSearchTranslatorTests.groovy

@@ -476,4 +476,57 @@ class PostgresSearchTranslatorTests {
         Assertions.assertTrue(tq.whereClause.contains("AND"))
         Assertions.assertTrue(tq.highlightFields.containsKey("productName"))
     }
+
+    // ============================================================
+    // pg_trgm Fuzzy Search Tests
+    // ============================================================
+
+    @Test
+    @DisplayName("translateFuzzyQuery returns pg_trgm similarity clause")
+    void fuzzyQuery_returnsSimilarityClause() {
+        def qr = ElasticQueryTranslator.translateFuzzyQuery("databse")
+        Assertions.assertEquals("content_text % ?", qr.clause)
+        Assertions.assertEquals(["databse"], qr.params)
+        Assertions.assertTrue(qr.isFuzzy)
+        Assertions.assertEquals("databse", qr.cleanedSearchText)
+    }
+
+    @Test
+    @DisplayName("translateFuzzyQuery handles empty input")
+    void fuzzyQuery_emptyInput() {
+        def qr = ElasticQueryTranslator.translateFuzzyQuery("")
+        Assertions.assertEquals("TRUE", qr.clause)
+        Assertions.assertFalse(qr.isFuzzy)
+    }
+
+    @Test
+    @DisplayName("translateFuzzyQuery handles null input")
+    void fuzzyQuery_nullInput() {
+        def qr = ElasticQueryTranslator.translateFuzzyQuery(null)
+        Assertions.assertEquals("TRUE", qr.clause)
+        Assertions.assertFalse(qr.isFuzzy)
+    }
+
+    @Test
+    @DisplayName("buildFuzzyScoreExpr returns similarity expression")
+    void fuzzyScoreExpr_returnsSimilarityFunc() {
+        String expr = ElasticQueryTranslator.buildFuzzyScoreExpr()
+        Assertions.assertEquals("similarity(content_text, ?)", expr)
+    }
+
+    @Test
+    @DisplayName("query_string populates cleanedSearchText in QueryResult")
+    void queryString_populatesCleanedSearchText() {
+        def qr = ElasticQueryTranslator.translateQuery([query_string: [query: "database optimization"]])
+        Assertions.assertNotNull(qr.cleanedSearchText)
+        Assertions.assertEquals("database optimization", qr.cleanedSearchText)
+    }
+
+    @Test
+    @DisplayName("query_string cleanedSearchText propagates to TranslatedQuery")
+    void searchMap_cleanedSearchTextPropagated() {
+        Map searchMap = [query: [query_string: [query: "search terms"]]]
+        TranslatedQuery tq = ElasticQueryTranslator.translateSearchMap(searchMap)
+        Assertions.assertEquals("search terms", tq.cleanedSearchText)
+    }
 }

run-moqui.sh

@@ -0,0 +1,17 @@
+#!/bin/zsh
+# Moqui Framework launcher optimized for Apple M1 Max (ARM64)
+
+export JAVA_HOME=$(/usr/libexec/java_home -v 21)
+
+# M1 Max optimized JVM flags:
+#  - ZGC: low-latency garbage collector, excellent on ARM64
+#  - 4GB heap (M1 Max has plenty of RAM, adjust as needed)
+#  - UseTransparentHugePages not available on macOS, using large pages where possible
+#  - Parallel GC threads tuned for M1 Max (10 cores)
+exec "$JAVA_HOME/bin/java" \
+  -XX:+UseZGC \
+  -Xms1g -Xmx4g \
+  -XX:+AlwaysPreTouch \
+  -XX:ParallelGCThreads=8 \
+  -Dfile.encoding=UTF-8 \
+  -jar moqui.war