ESHOPMAN Admin Global Search Issue with Custom Indexes

Understanding the ESHOPMAN Admin Global Search Behavior with Custom Indexes

The ESHOPMAN platform offers robust storefront management capabilities, deeply integrated with HubSpot. A key feature for merchants and administrators is the ESHOPMAN Admin Dashboard's global search, designed to quickly locate various entities like products, orders, customers, and regions. However, a recent community insight has highlighted a critical behavior change when custom search indexes are introduced into an ESHOPMAN project.

The Challenge: Incomplete "All" Search Results

A bug report from the ESHOPMAN community detailed an unexpected issue: as soon as even one custom search index is defined within an ESHOPMAN project (for example, a product index), the "All" search functionality in the Admin Dashboard no longer returns comprehensive results. Instead, it exclusively searches and displays results from the entities that have been explicitly indexed. This means crucial non-indexed entities such as orders, customers, regions, categories, and product variants silently disappear from the global "All" search results, even though they remain searchable within their specific entity sections.

This behavior stems from the internal logic of the ESHOPMAN Admin API's search endpoint (GET /admin/search). When no specific entity parameter is provided (which is the case for the "All" search in the dashboard), the system's logic for determining the scope of the search becomes narrowed. If any custom index is registered, the search mechanism incorrectly defaults to searching only those registered indexes, bypassing the default graph fallback that would otherwise cover all non-indexed entities.

Illustrative Example of a Custom Product Index

To understand how this might occur, consider a scenario where an ESHOPMAN developer defines a custom product index to enhance product search capabilities. This is typically done by creating a definition similar to the following within your ESHOPMAN project structure:

// src/search/product.ts
import { defineSearchIndex, graphSeed, search } from "@eshopman/framework/utils" // ESHOPMAN-specific path

export default defineSearchIndex({
  name: "product",
  entity: "product",
  fields: search.define({
    id: search.keyword().filterable(),
    title: search.text().searchable({ weight: 3 }),
  }),
  seed: graphSeed({ fields: ["id", "title"] }),
})

After defining such an index and running the necessary database migrations (e.g., npx eshopman db:migrate), the global search behavior changes. For instance, a query like q=Deutsch that previously returned results across regions, shipping profiles, and products, might now only show product-related results (or none if the query doesn't match indexed products).

Expected vs. Actual Behavior

Expected Behavior: When no specific entity is requested, the ESHOPMAN Admin global search should cover all default entities (orders, customers, regions, etc., via the graph fallback) plus any custom indexed entities (via the ESHOPMAN Search Module). Defining a custom index should enhance results for that entity, not diminish the overall search scope.
Actual Behavior: The "All" search in the ESHOPMAN Admin Dashboard returns results exclusively from the indexed entities, silently omitting all non-indexed entities from the global search scope.

The ESHOPMAN Community and Core Team Response

The ESHOPMAN community swiftly identified this as a regression, confirming its presence in ESHOPMAN versions 2.21.2 and above. The root cause was traced to the internal ESHOPMAN Admin API search route logic, where the entity list was being built solely from registered search indexes when no specific entity was provided. The correct approach, as identified by the community and affirmed by the ESHOPMAN core team, is to merge the platform's default admin search entities with any custom registered indexes. This ensures that all entities remain searchable globally, with indexed entities benefiting from the enhanced search module and others falling back to the default graph search.

A community-contributed fix has been proposed, and the ESHOPMAN core team is actively reviewing and working on integrating a solution to restore the comprehensive global search functionality. While a direct automated fix was not immediately feasible, the issue has been escalated to ensure a robust resolution.

What This Means for ESHOPMAN Users and Developers

For ESHOPMAN merchants and administrators, if you have implemented custom search indexes, be aware that your "All" global search results might be incomplete. To find non-indexed entities like orders or customers, you may need to navigate to their specific sections or explicitly search within those categories until the fix is deployed. For ESHOPMAN developers, this insight highlights a crucial aspect of working with custom search modules and the Admin API, emphasizing the importance of understanding how index registration impacts core platform functionalities. The resolution will ensure a more intuitive and efficient experience for managing your storefront within HubSpot.

Stay tuned to ESHOPMAN updates for the official release of the fix, which will restore the full power of the Admin global search for all entities, indexed and non-indexed alike.

ESHOPMAN Admin Global Search Bug: Custom Indexes Impact 'All' Results