Ensuring Accurate Product Discovery: A Deep Dive into ESHOPMAN Search Facets and `min_score`

Ensuring Accurate Product Discovery: A Deep Dive into ESHOPMAN Search Facets and `min_score`

At Move My Store, we know that precise product discovery is vital for ESHOPMAN merchants leveraging HubSpot CMS for their headless commerce storefronts. The ESHOPMAN community recently addressed a critical technical challenge concerning search facet accuracy, especially with typo-tolerant searches and minimum relevance scores. This insight details the problem, its root cause, and a powerful community-driven solution to ensure a consistent customer experience.

The Challenge: Discrepancies in ESHOPMAN Search Facets

Customers expect search facets to accurately reflect the products displayed. However, a specific scenario emerged within ESHOPMAN's native PostgreSQL search service (version 2.21.2 or similar) where facet counts diverged from actual search results. This occurred when keyword searches used both typo_tolerance: true and a min_score (e.g., 0.5).

For example, a typo-tolerant search like "lavendl" (for "lavendel") might return 24 relevant plant products. Yet, facets could misleadingly offer options like "Verpakking: Bigbag 0,5 m³" – an option belonging to soil products, not plants. Applying such a facet would yield zero results, frustrating the customer. In another instance, 79 out of 92 facet counts for "buxsu" incorrectly suggested products that wouldn't appear if filtered. The core issue: main search results respected min_score, but facet counts were generated from a broader match predicate, ignoring the min_score threshold for relevance.

Understanding the Root Cause: A Technical Deep Dive

The discrepancy was traced to how ESHOPMAN's Node.js/TypeScript search service processes queries:

• The function executing the main query and determining total hits (executeQuery) correctly applied the score >= ? condition for min_score to both product hits and the overall count.
• However, the function building the facet scope (buildFacetScope) constructed its WHERE clause from keyword fragments and other filters, critically omitting the min_score condition. This allowed less relevant products (below min_score but above typo tolerance threshold) to inflate facet counts, even though they were too irrelevant for the main results.

The ESHOPMAN Community Solution: A Targeted Fix

The ESHOPMAN community devised a precise solution to align facet counts with main search results. The fix involves modifying the buildFacetScope logic within the ESHOPMAN search service to include the min_score condition for keyword searches. This ensures consistency across the search experience.

Here's the conceptual code adjustment within the ESHOPMAN search service's Node.js/TypeScript codebase:

const fragments = useKeyword ? this.keywordFragments({ query, catalog }) : undefined
const matchSql = fragments?.matchSql
// ... existing logic ...
const minScore = query.search_options?.min_score
if (fragments?.q && !useVector && minScore !== undefined) {
  conditions.push(`${fragments.rankSql(params)} >= ?`)
  params.push(minScore)
}

This modification ensures that if a keyword query is present, it's not a vector search, and a min_score is defined, then this minimum score is also incorporated into the conditions for building facet counts. This critical addition guarantees facets accurately reflect products meeting the main search's relevance criteria.

Impact and Best Practices for ESHOPMAN Developers

Implementing this fix significantly enhances the ESHOPMAN storefront experience:

• Accurate Product Discovery: Eliminates misleading facet options, leading to a more intuitive search journey.
• Improved User Experience: Reduces frustration and builds confidence in search results.
• Data Consistency: Facet counts now accurately describe the actual result set, aligning with min_score expectations.

While this condition adds a minor performance overhead (approx. 590 ms vs. 560 ms for a batch of typo searches on a 10,000-product catalog), the benefits of accurate search far outweigh this minimal cost. For ESHOPMAN developers managing custom search logic or extending core services, applying such fixes is a best practice to maintain the integrity and performance of headless commerce applications deployed via HubSpot CMS.

This community insight highlights the power of collaborative development within the ESHOPMAN ecosystem, continuously refining and enhancing the platform's capabilities for merchants globally.