Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Add Meilisearch manual (position) sort for category/collection PLPs

Łukasz Adamczyk940a40244303
diff --git a/docs/plans/6.0-replace-taxons-with-categories.md b/docs/plans/6.0-replace-taxons-with-categories.md
index a5d438e154..730289c855 100644
--- a/docs/plans/6.0-replace-taxons-with-categories.md
+++ b/docs/plans/6.0-replace-taxons-with-categories.md
@@ -50,7 +50,7 @@ Much of the **Category** half has already shipped (5.5–5.6). What exists today
**No longer true:** default taxonomies ("Categories", "Brands", "Collections") and automatic taxons ("On Sale", "New Arrivals") are **no longer auto-created per store** — `Store#ensure_default_taxonomies_are_created` / `ensure_default_automatic_taxons` were deprecated (2026-03-10) and removed in 5.5 (PR #14020, 2026-05-11). New stores get no taxonomies; categories are created on demand. The `taxonomy_*_name` locale keys remain (only `brand_taxon` still reads `taxonomy_brands_name`).
-**Known gap — "manual" sort in the v3 Store API (Meilisearch only).** "Manual" sort means ordering products by their hand-set position *within the grouping* (`ProductCategory.position` / `ProductCollection.position`). The **DB provider now implements it** (shipped): `SearchProvider::Database` infers the grouping from the applied `in_category`/`in_collection` filter, defaults a grouping page's blank sort to `manual`, and orders by `ProductCollection.position` (flat, for collections) or `MIN(ProductCategory.position)` collapsed per product (subtree, for categories) — reusing the join the filter already made, no extra query. The **Meilisearch provider still does not**: it indexes no position and can't natively sort by a per-grouping (many-valued) join position, so on MS-backed stores a category page's default sort and a `sort_order: 'manual'` collection PLP don't reflect the merchant's hand-ordering. The remaining fix is Meilisearch-only and must be **native** (no DB fallback) — see Open Questions.
+**"Manual" (position) sort in the v3 Store API — implemented for both providers.** "Manual" sort orders products by their hand-set position *within the grouping* (`ProductCategory.position` / `ProductCollection.position`). The **DB provider** infers the grouping from the applied `in_category`/`in_collection` filter, defaults a grouping page's blank sort to `manual`, and orders by `ProductCollection.position` (flat, for collections) or `MIN(ProductCategory.position)` collapsed per product (subtree, for categories) — reusing the join the filter already made. The **Meilisearch provider** reaches the same result natively via **single index + `distinct`**: `ProductPresenter` emits per-grouping membership docs (shared scalar `grouping_id` + `position`), a manual grouping page filters `grouping_id` and sorts `position:asc`, and `distinctAttribute = product_id` collapses the duplicates on non-grouping queries (facet counts/totals accurate on MS ≥ 1.40). See Open Questions (resolved).
## Remaining for 6.0
@@ -442,7 +442,7 @@ The **Store** response is the customer-facing subset — `id`, `name`, `slug`/`p
Products in a collection are served by a **dedicated endpoint**, not a filter on `/products`. This follows the Shopify Storefront GraphQL model (`collection { products }`) where the collection is the path context and filters/sort layer on top. (Most REST APIs — WooCommerce, Medusa, commercetools, BigCommerce — use a `?collection_id=` filter instead; we deliberately choose the nested style for cleaner requests and to apply the collection's own default sort automatically. `in_collection` is still kept as a Ransack scope for composite queries.)
- `GET /api/v3/store/collections/:id/products` — a thin controller that resolves the collection and **delegates to the same search-provider flow** as `/products` (query, Ransack filters, pagination, serializer). `def scope` stays the **base visibility scope** (`available` + `accessible_by`) — it is **not** pre-scoped to the collection. Instead the controller injects `in_collection: collection.prefixed_id` into the filters, and each provider applies it: the DB provider via the `in_collection` Ransack scope, Meilisearch via the `collection_ids` filter. Collection scoping has to be a provider filter (not an AR pre-scope) because Meilisearch does its own filtering/counting/pagination and treats the AR scope only as a post-search visibility guard. No logic duplication.
-- **Sort precedence.** Effective sort = the request's `sort` param if present, otherwise the collection's `sort_order`. Position ordering (`ProductCollection.position`) applies **only when the effective sort is `manual`**; any dynamic sort — whether from the collection's own default or a shopper override — dismisses it. Because the listing runs through the provider (for the `in_collection` filter, pagination, and faceting), manual sort is implemented *in* the provider, not by bypassing it with a direct AR query. The **DB provider ships this** (orders by `ProductCollection.position`); the **Meilisearch provider does not yet** (Open Question #1). On MS-backed stores a `sort_order: 'manual'` collection falls back to default order until the native solution lands; all dynamic sorts work on both providers.
+- **Sort precedence.** Effective sort = the request's `sort` param if present, otherwise the collection's `sort_order`. Position ordering (`ProductCollection.position`) applies **only when the effective sort is `manual`**; any dynamic sort — whether from the collection's own default or a shopper override — dismisses it. Because the listing runs through the provider (for the `in_collection` filter, pagination, and faceting), manual sort is implemented *in* the provider, not by bypassing it with a direct AR query. **Both providers implement it** — the DB provider orders by `ProductCollection.position`; the Meilisearch provider queries per-grouping membership docs (single index + `distinct`) sorted by `position:asc`. All dynamic sorts work on both.
- **Facets/sort metadata** reuse the existing `GET /api/v3/store/products/filters` with a new **`collection_id`** param (parallel to `category_id`): it resolves the collection, scopes `in_collection`, and passes **only the collection's `sort_order`** to `FiltersAggregator` — via a `sort_order:` string param, **not** the `Collection` object (the aggregator stays decoupled from the model). No child facet (collections are flat).
- **Model:** `Spree::Product.in_collection` scope (flat join to `spree_product_collections`, no descendants), whitelisted as a ransackable scope. (No `in_collections` plural — the collection surface is single-collection; add it only if a real multi-collection filter appears.)
- **Meilisearch:** index `collection_ids` (flat, no ancestors) on the product document, add it to `filterable_attributes` / `facet_attributes`, and handle `in_collection` in `build_filter_condition`. Kept fresh by `RegenerateProducts` (touches products + `enqueue_search_index`).
@@ -534,7 +534,7 @@ end
**Not in scope of this phase (or plan):**
- **Dashboard Collection UI** — all dashboard work lives in `6.0-admin-spa.md` (the Category admin UI is already there; Collection is added to its resource list).
-- **Manual sort** — the **DB provider is shipped** (position ordering for both category and collection groupings); the **Meilisearch provider is still pending** a native solution (Open Question #1). On MS-backed stores a `sort_order: 'manual'` collection falls back to default order until it lands; all dynamic sorts work on both.
+- **Manual sort** — implemented for **both providers**: DB (position ordering for category + collection groupings) and Meilisearch (single index + `distinct` over per-grouping membership docs). All dynamic sorts work on both. (Was Open Question #1, now resolved.)
- **`CollectionRules::AvailableOn`'s channel-aware reimplementation** — the model, its interim (legacy-column) `apply`, and the scheduled refresh (`RegenerateTimeBasedJob` + `time_based_collection_rules`) all ship in this phase; only rewriting `apply` against `ProductPublication#published_at` is **Migration Phase 5**, a dependency on `6.0-channels-catalogs-b2b.md`.
### Phase 2: Table renames (Taxon → Category)
@@ -699,15 +699,11 @@ Gated on the channels plan finishing the `available_on` → `ProductPublication#
> - *Collection product listing* — a dedicated `GET /collections/:id/products` (base visibility scope + an injected `in_collection` filter, delegating to the shared search flow; default sort from the collection's `sort_order`), with facets via the existing `/products/filters` + a new `collection_id` param. See API → Collection product listing.
> - *Automatic collection scheduling* — a `RegenerateTimeBasedJob` scoped to a `time_based_collection_rules` registry, scheduled by the host app (the `ExpireJob` pattern). Ships in Phase 1 with `AvailableOn` as its one registered rule (interim legacy-column implementation; channel-aware reimplementation in Phase 5). See Design Details → Automatic collection regeneration.
> - *Collection nesting* — collections stay **flat**; hierarchy lives in Category (matches Shopify and keeps the Category/Collection split clean).
-> - *"Manual" sort in the v3 Store API — DB provider* — **shipped.** `SearchProvider::Database` infers the grouping from the applied `in_category`/`in_collection` filter (`manual_sort_grouping`), defaults a grouping page's blank sort to `manual`, and orders by `ProductCollection.position` (flat) for collections or `MIN(ProductCategory.position)` grouped per product (subtree collapse) for categories — reusing the join the filter already made, so no extra query. The Meilisearch half stays open (Question #1).
+> - *"Manual" (position) sort in the v3 Store API* — **resolved for both providers.**
+> - **DB provider (shipped):** `SearchProvider::Database` infers the grouping from the applied `in_category`/`in_collection` filter (`manual_sort_grouping`), defaults a grouping page's blank sort to `manual`, and orders by `ProductCollection.position` (flat) for collections or `MIN(ProductCategory.position)` grouped per product (subtree collapse) for categories — reusing the join the filter already made, so no extra query.
+> - **Meilisearch provider — single index + `distinct`** (Algolia's "duplicate records" recipe). `ProductPresenter` emits, alongside each base doc, one **membership doc** per grouping (each collection + each category ancestor-or-self) carrying a shared scalar `grouping_id` + `position`; a manual grouping page filters `grouping_id` and sorts `position:asc`, while an index-level `distinctAttribute = product_id` collapses the duplicates on shop-all/search/non-manual queries. Facet counts + totals stay accurate under `distinct` (verified on MS ≥ 1.40, incl. 1.42.1 and 1.49.0). *Rejected alternatives:* a two-index "membership index B" (extra index + dual-write; deferred as premature optimization — the escape hatch if the `distinct` tax hurts) and per-grouping nested sortable attributes (unbounded sortable list + reindex-per-grouping anti-pattern).
-1. **"Manual" sort in the v3 Store API — Meilisearch provider (needs a native solution).** The DB provider ships manual/position sort (see Resolved above); the Meilisearch provider does **not**, and it must reach DB-provider parity — manual order composing with facet filters and text search. **A DB fallback is explicitly ruled out** — an MS-backed store must not route its hot listing path back through the database. The core tension: position is a *per-grouping* value (a product has a different position in each collection, and a subtree-MIN per category), while Meilisearch can only sort on attributes it has been told are sortable. Two native approaches keep the sort/filter/search composition inside Meilisearch; they trade a second index against an anti-pattern on the existing one:
-
- - **Option 1 — Denormalized "membership" index (best practice).** Add a **second** MS index, one document per (product × grouping × locale × currency), carrying `grouping_id` + a scalar `position` + the full filterable/searchable payload. A grouping page runs one native query against index B (`filter grouping_id = X` + facets + text query, `sort position:asc`, native pagination); index A (products) stays untouched and serves shop-all/search. **Pros:** clean scalar sort, no anti-patterns, scales to any number of groupings, index A unchanged. **Cons:** a second index ~5–8× the product index (membership × ancestor depth × locale × currency) plus dual-write sync on every product/membership change.
-
- - **Option 2 — Nested position map + registered sortable attributes (single index, anti-pattern).** Keep only the current product index; add a nested object to each product document — `group_positions: { <grouping_id> => position }` (collections: the flat position; categories: the precomputed subtree-MIN) — and **register each grouping's path** (`group_positions.<grouping_id>`) as a sortable attribute, so a grouping page sorts by `group_positions.<grouping_id>:asc` natively (an object with scalar leaves, not an array, so it avoids the array-sort global-min/max trap). **Pros:** one index, tiny added payload, no second-index dual-write. **Cons:** it is the documented Meilisearch **anti-pattern** — sortable/filterable attributes are meant to be a small *static* set, not one-per-entity. The sortable-attributes list grows with the number of collections + categories; every grouping create/delete requires an index **settings update**, which forces a **reindex** and is slow; there are practical limits on how many sortable attributes an index can carry. Viable only for stores with a small, stable set of groupings.
-
- **Leaning toward Option 1** for correctness and scalability despite the second-index cost. Either way, **not yet implemented** — the detailed Option 1 design (schema, sync matrix, presenter, verification) is tracked separately and deferred; the interim behavior is that MS-backed `sort_order: 'manual'` groupings fall back to default order.
+_No open questions remain — all resolved above._
## References
diff --git a/spree/api/app/controllers/spree/api/v3/admin/categories/products_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/categories/products_controller.rb
index b67949d46e..93aaf9374b 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/categories/products_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/categories/products_controller.rb
@@ -40,6 +40,9 @@ module Spree
return render_invalid_position if position.nil?
classification_for(@product).insert_at(position + 1)
+ # insert_at shifts sibling positions, so refresh every product in the
+ # category (manual sort reads position from the search index).
+ @category.products.find_each(&:enqueue_search_index)
head :no_content
end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/collections/products_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/collections/products_controller.rb
index 397122985b..ba8da1d160 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/collections/products_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/collections/products_controller.rb
@@ -40,6 +40,9 @@ module Spree
return render_invalid_position if position.nil?
product_collection_for(@product).insert_at(position + 1)
+ # insert_at shifts sibling positions, so refresh every product in the
+ # collection (manual sort reads position from the search index).
+ @parent_collection.products.find_each(&:enqueue_search_index)
head :no_content
end
diff --git a/spree/core/app/models/spree/category.rb b/spree/core/app/models/spree/category.rb
index 122fad15a3..4f96b7c1ee 100644
--- a/spree/core/app/models/spree/category.rb
+++ b/spree/core/app/models/spree/category.rb
@@ -94,6 +94,9 @@ module Spree
# Capture the old parent before the move; recompute both chains after.
before_move :capture_parent_before_move
after_move :recalculate_products_count_after_move
+ # A move changes the subtree's ancestor set (indexed category_ids) and its
+ # per-grouping positions, so refresh the moved subtree's products in search.
+ after_move :reindex_products_after_move
# Destroying a category drops its subtree's products from every ancestor's
# inclusive count. Recompute the ancestors here (while the doomed subtree's
# rows still exist) excluding that subtree, since the ProductCategory destroy
@@ -381,6 +384,20 @@ module Spree
saved_changes.key?(:name) || saved_changes.key?(:permalink)
end
+ # Refresh the moved subtree's products in the search index (their ancestor
+ # category_ids + per-grouping positions changed). Guarded so DB-provider stores
+ # (no indexing) skip the query entirely; enqueue_search_index self-guards too.
+ def reindex_products_after_move
+ return unless Spree.search_provider.constantize.indexing_required?
+
+ Spree::Product.joins(:product_categories).
+ where(Spree::ProductCategory.table_name => { category_id: self_and_descendants.select(:id) }).
+ distinct.
+ find_each(&:enqueue_search_index)
+ rescue NameError
+ nil
+ end
+
def sync_taxonomy_name
return unless taxonomy.present?
return unless saved_changes.key?(:name) && root?
diff --git a/spree/core/app/models/spree/search_provider/meilisearch.rb b/spree/core/app/models/spree/search_provider/meilisearch.rb
index 4c0832a947..fc60029eab 100644
--- a/spree/core/app/models/spree/search_provider/meilisearch.rb
+++ b/spree/core/app/models/spree/search_provider/meilisearch.rb
@@ -21,6 +21,9 @@ module Spree
page = [page.to_i, 1].max
limit = limit.to_i.clamp(1, 100)
+ filters = normalize_filters(filters)
+ sort, filters = resolve_manual_sort(sort, filters)
+
ms_result, _ = execute_search(query: query, filters: filters, sort: sort, page: page, limit: limit)
return empty_result(scope, page, limit) unless ms_result
@@ -40,7 +43,7 @@ module Spree
SearchResult.new(
products: products,
- total_count: ms_result['estimatedTotalHits'] || 0,
+ total_count: ms_result['totalHits'] || 0,
pagy: pagy
)
end
@@ -64,13 +67,16 @@ module Spree
filters: build_facet_response(facet_distribution),
sort_options: available_sort_options.map { |id| { id: id } },
default_sort: default_sort,
- total_count: ms_result['estimatedTotalHits'] || 0
+ total_count: ms_result['totalHits'] || 0
)
end
def index(product)
ensure_index_settings_once!
documents = presenter_class.new(product, store).call
+ # Delete first: membership docs use grouping-specific ids, so a product
+ # that left a grouping would otherwise leave an orphaned stale doc.
+ remove_by_id(product.prefixed_id)
client.index(index_name).add_documents(documents, 'id')
end
@@ -93,9 +99,14 @@ module Spree
end
def reindex(scope = nil)
+ full_reindex = scope.nil?
scope ||= store.products
ensure_index_settings!
+ # On a full reindex, clear first so stale docs (e.g. membership docs for
+ # removed groupings) don't linger; a scoped reindex keeps upsert semantics.
+ client.index(index_name).delete_all_documents if full_reindex
+
indexed = 0
scope.reorder(id: :asc)
.preload_associations_lazily
@@ -123,6 +134,7 @@ module Spree
tasks << index.update_filterable_attributes(filterable_attributes)
tasks << index.update_sortable_attributes(sortable_attributes)
tasks << index.update_searchable_attributes(searchable_attributes)
+ tasks << index.update_distinct_attribute(distinct_attribute)
tasks.each { |task| task&.await }
@index_settings_configured = true
end
@@ -138,6 +150,32 @@ module Spree
private
+ # Normalize incoming filters to a plain, string-keyed Hash.
+ def normalize_filters(filters)
+ filters = filters.to_unsafe_h if filters.respond_to?(:to_unsafe_h)
+ (filters || {}).stringify_keys
+ end
+
+ # Manual/position sort. When a single grouping is being viewed (in_collection
+ # or in_category) and the effective sort is 'manual' — either requested, or
+ # the grouping-page default (blank ⇒ manual) — query the per-grouping
+ # membership docs: swap the membership filter for `grouping_id` and sort by
+ # the scalar `position`. Without a grouping, 'manual' has nothing to order by,
+ # so it falls back to Meilisearch default ranking.
+ def resolve_manual_sort(sort, filters)
+ grouping_id = filters['in_collection'] || filters['in_category']
+ grouping_id = nil unless valid_prefixed_id?(grouping_id)
+ sort = 'manual' if sort.blank? && grouping_id
+
+ if sort == 'manual' && grouping_id
+ filters = filters.except('in_collection', 'in_category').merge('grouping_id' => grouping_id)
+ elsif sort == 'manual'
+ sort = nil
+ end
+
+ [sort, filters]
+ end
+
# Execute a Meilisearch query. Returns [ms_result, facet_distribution].
# facet_distribution is empty when return_facets is false. Returns nil on API error.
def execute_search(query:, filters:, sort:, page:, limit:, return_facets: false)
@@ -151,12 +189,16 @@ module Spree
option_conditions = build_grouped_option_conditions(grouped_options)
all_conditions = base_conditions + option_conditions
+ # Page-based (exhaustive) pagination — REQUIRED so `distinct` collapses
+ # totalHits and facetDistribution to per-product counts. The offset/limit
+ # ("estimatedTotalHits") mode does NOT apply distinct to the count or
+ # facets, which over-counts the duplicated per-grouping membership docs.
search_params = {
filter: all_conditions,
facets: return_facets ? facet_attributes : nil,
sort: build_sort(sort),
- offset: (page - 1) * limit,
- limit: limit
+ page: page,
+ hitsPerPage: limit
}.compact
Rails.logger.debug { "[Meilisearch] index=#{index_name} query=#{query.inspect} #{search_params.compact.inspect}" }
@@ -168,7 +210,7 @@ module Spree
option_type_ids_ordered = grouped_options.keys
option_type_ids_ordered.each do |option_type_id|
without_this = build_grouped_option_conditions(grouped_options.except(option_type_id))
- queries << { indexUid: index_name, q: query.to_s, filter: base_conditions + without_this, facets: ['option_value_ids'], limit: 0 }
+ queries << { indexUid: index_name, q: query.to_s, filter: base_conditions + without_this, facets: ['option_value_ids'], page: 1, hitsPerPage: 0 }
end
results = client.multi_search(queries)
@@ -194,7 +236,7 @@ module Spree
return nil
end
- Rails.logger.debug { "[Meilisearch] #{ms_result['estimatedTotalHits']} hits in #{ms_result['processingTimeMs']}ms" }
+ Rails.logger.debug { "[Meilisearch] #{ms_result['totalHits']} hits in #{ms_result['processingTimeMs']}ms" }
[ms_result, facet_distribution]
end
@@ -247,19 +289,28 @@ module Spree
end
def filterable_attributes
- %w[product_id status in_stock preorder store_ids channel_ids locale currency available_on discontinue_on price category_ids collection_ids tags option_value_ids]
+ %w[product_id status in_stock preorder store_ids channel_ids locale currency available_on discontinue_on price category_ids collection_ids grouping_id tags option_value_ids]
end
def sortable_attributes
- %w[name price created_at available_on units_sold_count]
+ %w[name price created_at available_on units_sold_count position]
end
def facet_attributes
filterable_attributes
end
+ # Collapses the per-grouping membership docs to one row per product on
+ # non-grouping queries (shop-all, search, non-manual sorts). Facet counts
+ # and totals honor distinct on Meilisearch >= 1.40.
+ def distinct_attribute
+ 'product_id'
+ end
+
+ # Sourced from Spree::Collection::SORT_ORDERS (matching FiltersAggregator) so
+ # both providers advertise identical options — including 'manual'.
def available_sort_options
- %w[price -price name -name -available_on available_on best_selling]
+ Spree::Collection::SORT_ORDERS.map { |sort_order| to_api_sort(sort_order) }
end
# Converts internal sort format ('price asc') to API format ('price', '-price').
@@ -341,6 +392,8 @@ module Spree
parts.length > 1 ? "(#{parts.join(' OR ')})" : parts.first
when 'in_collection'
"collection_ids = '#{sanitize_prefixed_id(value)}'" if valid_prefixed_id?(value)
+ when 'grouping_id'
+ "grouping_id = '#{sanitize_prefixed_id(value)}'" if valid_prefixed_id?(value)
when 'with_option_value_ids'
# Handled by grouped option conditions in search_and_filter — skip here
nil
@@ -386,6 +439,7 @@ module Spree
# Override in subclasses to add custom sorts — call super for built-in sorts.
def sort_mapping(sort)
case sort
+ when 'manual' then ['position:asc']
when 'price' then ['price:asc']
when '-price' then ['price:desc']
when 'name' then ['name:asc']
@@ -481,7 +535,7 @@ module Spree
def build_pagy(ms_result, page, limit)
fake_result = Struct.new(:raw_answer).new({
- 'totalHits' => ms_result['estimatedTotalHits'] || 0,
+ 'totalHits' => ms_result['totalHits'] || 0,
'hitsPerPage' => limit,
'page' => page
})
diff --git a/spree/core/app/presenters/spree/search_provider/product_presenter.rb b/spree/core/app/presenters/spree/search_provider/product_presenter.rb
index 9486c4673e..e93d0bd1a0 100644
--- a/spree/core/app/presenters/spree/search_provider/product_presenter.rb
+++ b/spree/core/app/presenters/spree/search_provider/product_presenter.rb
@@ -8,8 +8,12 @@ module Spree
@store = store
end
- # Returns an array of documents — one per market × locale combination.
- # Each document has flat name, description, price fields (no dynamic suffixes).
+ # Returns an array of documents. For each (market × locale) the product is
+ # priced in, one BASE document plus one MEMBERSHIP document per grouping the
+ # product belongs to (each collection + each category ancestor-or-self),
+ # carrying a scalar grouping_id + position so Meilisearch can sort a grouping
+ # page by the merchant's hand-set position. Each document has flat name,
+ # description, price fields (no dynamic suffixes).
def call
documents = []
@@ -18,7 +22,9 @@ module Spree
next unless lowest_price(market.currency)
Mobility.with_locale(locale) do
- documents << build_document(locale, market.currency, default_locale)
+ base = build_document(locale, market.currency, default_locale)
+ documents << base
+ documents.concat(membership_documents(base, locale, market.currency))
end
end
@@ -26,7 +32,9 @@ module Spree
if documents.empty?
fallback_currency = store.default_market&.currency || store.supported_currencies_list.first&.iso_code
if fallback_currency && lowest_price(fallback_currency)
- documents << build_document(default_locale, fallback_currency, default_locale)
+ base = build_document(default_locale, fallback_currency, default_locale)
+ documents << base
+ documents.concat(membership_documents(base, default_locale, fallback_currency))
end
end
@@ -126,6 +134,55 @@ module Spree
}.uniq
end
+ # One membership document per grouping (each collection + each category
+ # ancestor-or-self) the product belongs to: the full base payload plus a
+ # scalar grouping_id and position, with a distinct composite id. A manual-
+ # sorted grouping page filters grouping_id and sorts by position.
+ def membership_documents(base, locale, currency)
+ grouping_positions.map do |grouping_id, position|
+ base.merge(
+ id: "#{product.prefixed_id}__#{grouping_id}_#{locale}_#{currency}",
+ grouping_id: grouping_id,
+ position: position
+ )
+ end
+ end
+
+ # { grouping_prefixed_id => position }, merged across collections (flat) and
+ # categories (subtree-MIN). Prefixes (coll_/ctg_) keep the keys disjoint.
+ def grouping_positions
+ @grouping_positions ||= collection_positions.merge(category_positions)
+ end
+
+ # Flat: one entry per collection with the product's ProductCollection.position.
+ def collection_positions
+ @collection_positions ||= product.product_collections.pluck(:collection_id, :position).each_with_object({}) do |(cid, pos), acc|
+ acc[prefixed_id_for(Spree::Collection, cid)] = pos
+ end
+ end
+
+ # Subtree-MIN: a product under a category AND its descendants contributes its
+ # position to every ancestor-or-self, folded to the minimum — mirrors the DB
+ # provider's MIN(position)/GROUP BY and category_ids_with_ancestors.
+ def category_positions
+ @category_positions ||= begin
+ positions_by_category_id = product.product_categories.pluck(:category_id, :position).to_h
+ product.categories.each_with_object({}) do |category, acc|
+ position = positions_by_category_id[category.id]
+ category.self_and_ancestors.each do |ancestor|
+ key = ancestor.prefixed_id
+ acc[key] = [acc[key], position].compact.min
+ end
+ end
+ end
+ end
+
+ # Encode a raw primary key into a model's prefixed id without loading the
+ # record (mirrors Spree::PrefixedId#prefixed_id).
+ def prefixed_id_for(klass, raw_id)
+ "#{klass._prefix_id_prefix}_#{Spree::PrefixedId::SQIDS.encode([raw_id])}"
+ end
+
def variant_option_value_ids
variant_option_values_data.map(&:prefixed_id).uniq
end
diff --git a/spree/core/spec/models/spree/search_provider/meilisearch_spec.rb b/spree/core/spec/models/spree/search_provider/meilisearch_spec.rb
index 23037447ea..5ec7be4f2b 100644
--- a/spree/core/spec/models/spree/search_provider/meilisearch_spec.rb
+++ b/spree/core/spec/models/spree/search_provider/meilisearch_spec.rb
@@ -17,6 +17,8 @@ module Spree
allow(mock_index).to receive(:update_filterable_attributes)
allow(mock_index).to receive(:update_sortable_attributes)
allow(mock_index).to receive(:update_searchable_attributes)
+ allow(mock_index).to receive(:update_distinct_attribute)
+ allow(mock_index).to receive(:delete_documents)
end
describe '#search_and_filter' do
@@ -26,7 +28,7 @@ module Spree
{ 'product_id' => product_1.prefixed_id },
{ 'product_id' => product_2.prefixed_id }
],
- 'estimatedTotalHits' => 2,
+ 'totalHits' => 2,
'facetDistribution' => {
'in_stock' => { 'true' => 2 },
'price' => { '19.99' => 1, '29.99' => 1 }
@@ -44,7 +46,7 @@ module Spree
end
it 'queries Meilisearch with the search term' do
- expect(mock_index).to receive(:search).with('shirt', hash_including(:limit, :offset))
+ expect(mock_index).to receive(:search).with('shirt', hash_including(:page, :hitsPerPage))
provider.search_and_filter(scope: store.products, query: 'shirt')
end
@@ -63,8 +65,25 @@ module Spree
provider.search_and_filter(scope: store.products, query: 'shirt')
end
+ context 'listing all products (no query, no filters)' do
+ it 'searches an empty query with only system conditions and no facets' do
+ expect(mock_index).to receive(:search).with('', satisfy { |p|
+ p[:filter].include?("status = 'active'") && !p.key?(:facets)
+ }).and_return(ms_response)
+
+ provider.search_and_filter(scope: store.products)
+ end
+
+ it 'returns the products and total' do
+ result = provider.search_and_filter(scope: store.products)
+
+ expect(result.products).to include(product_1, product_2)
+ expect(result.total_count).to eq(2)
+ end
+ end
+
context 'with no results' do
- let(:ms_response) { { 'hits' => [], 'estimatedTotalHits' => 0, 'facetDistribution' => {} } }
+ let(:ms_response) { { 'hits' => [], 'totalHits' => 0, 'facetDistribution' => {} } }
it 'returns empty relation' do
result = provider.search_and_filter(scope: store.products, query: 'nonexistent')
@@ -96,12 +115,14 @@ module Spree
context 'with in_collection filter' do
let(:collection) { create(:collection) }
- it 'passes the collection_ids filter to Meilisearch' do
+ it 'passes the collection_ids filter to Meilisearch (non-manual sort)' do
expect(mock_index).to receive(:search).with(anything, hash_including(
filter: include("collection_ids = '#{collection.prefixed_id}'")
)).and_return(ms_response)
- provider.search_and_filter(scope: store.products, filters: { 'in_collection' => collection.prefixed_id })
+ # A non-manual sort keeps the collection_ids filter; a blank/manual sort
+ # instead routes to the grouping_id membership docs (covered below).
+ provider.search_and_filter(scope: store.products, sort: 'price', filters: { 'in_collection' => collection.prefixed_id })
end
it 'ignores a value that is not a prefixed id' do
@@ -132,15 +153,65 @@ module Spree
end
context 'with pagination' do
- it 'passes offset and limit' do
+ it 'passes page and hitsPerPage (exhaustive mode so distinct counts are exact)' do
expect(mock_index).to receive(:search).with(anything, hash_including(
- offset: 25, limit: 25
+ page: 2, hitsPerPage: 25
)).and_return(ms_response)
provider.search_and_filter(scope: store.products, page: 2, limit: 25)
end
end
+ context 'pagination result (pagy built from totalHits)' do
+ let(:ms_response) do
+ { 'hits' => [{ 'product_id' => product_1.prefixed_id }], 'totalHits' => 50, 'facetDistribution' => {} }
+ end
+
+ it 'builds a pagy spanning all pages with a next page' do
+ result = provider.search_and_filter(scope: store.products, page: 1, limit: 25)
+
+ expect(result.total_count).to eq(50)
+ expect(result.pagy.count).to eq(50)
+ expect(result.pagy.pages).to eq(2)
+ expect(result.pagy.page).to eq(1)
+ expect(result.pagy.next).to eq(2)
+ end
+ end
+
+ context 'with manual (position) sort on a grouping' do
+ it 'queries the grouping_id membership docs sorted by position (collection)' do
+ expect(mock_index).to receive(:search).with(anything, satisfy { |p|
+ p[:filter].include?("grouping_id = 'coll_Manual1'") &&
+ p[:filter].none? { |c| c.to_s.include?('collection_ids') } &&
+ p[:sort] == ['position:asc']
+ }).and_return(ms_response)
+
+ provider.search_and_filter(scope: store.products, sort: 'manual', filters: { 'in_collection' => 'coll_Manual1' })
+ end
+
+ it 'defaults a grouping page with no sort param to manual' do
+ expect(mock_index).to receive(:search).with(anything, satisfy { |p|
+ p[:filter].include?("grouping_id = 'coll_Manual1'") && p[:sort] == ['position:asc']
+ }).and_return(ms_response)
+
+ provider.search_and_filter(scope: store.products, filters: { 'in_collection' => 'coll_Manual1' })
+ end
+
+ it 'works for a category grouping' do
+ expect(mock_index).to receive(:search).with(anything, satisfy { |p|
+ p[:filter].include?("grouping_id = 'ctg_Manual1'") && p[:sort] == ['position:asc']
+ }).and_return(ms_response)
+
+ provider.search_and_filter(scope: store.products, sort: 'manual', filters: { 'in_category' => 'ctg_Manual1' })
+ end
+
+ it 'ignores manual sort without a grouping (falls back to default ranking)' do
+ expect(mock_index).to receive(:search).with(anything, satisfy { |p| p[:sort].nil? }).and_return(ms_response)
+
+ provider.search_and_filter(scope: store.products, sort: 'manual')
+ end
+ end
+
context 'with sort order preservation' do
it 'returns products in the order Meilisearch returned them' do
reversed_response = {
@@ -148,7 +219,7 @@ module Spree
{ 'product_id' => product_2.prefixed_id },
{ 'product_id' => product_1.prefixed_id }
],
- 'estimatedTotalHits' => 2,
+ 'totalHits' => 2,
'facetDistribution' => {}
}
allow(mock_index).to receive(:search).and_return(reversed_response)
@@ -199,7 +270,7 @@ module Spree
let(:ms_response) do
{
'hits' => [],
- 'estimatedTotalHits' => 2,
+ 'totalHits' => 2,
'processingTimeMs' => 1,
'facetDistribution' => {
'in_stock' => { 'true' => 2 },
@@ -251,7 +322,7 @@ module Spree
let(:ms_response) do
{
'hits' => [],
- 'estimatedTotalHits' => 1,
+ 'totalHits' => 1,
'processingTimeMs' => 1,
'facetDistribution' => {
'option_value_ids' => {
@@ -322,6 +393,11 @@ module Spree
expect(result.default_sort).to eq('manual')
end
end
+
+ it 'advertises manual in the sort options (sourced from Collection::SORT_ORDERS)' do
+ result = provider.filters(scope: store.products, query: '')
+ expect(result.sort_options.map { |o| o[:id] }).to include('manual')
+ end
end
describe '#index' do
@@ -340,6 +416,12 @@ module Spree
expect(mock_index).to receive(:add_documents).with(docs, 'id')
provider.index(product_1)
end
+
+ it 'deletes the product existing docs before adding (purges stale membership docs)' do
+ expect(mock_index).to receive(:delete_documents).with(filter: "product_id = '#{product_1.prefixed_id}'").ordered
+ expect(mock_index).to receive(:add_documents).ordered
+ provider.index(product_1)
+ end
end
describe '#remove' do
@@ -376,6 +458,29 @@ module Spree
expect(mock_index).to receive(:add_documents).at_least(:once)
provider.reindex(store.products)
end
+
+ it 'clears the index before a full (unscoped) reindex' do
+ expect(mock_index).to receive(:delete_all_documents)
+ allow(mock_index).to receive(:add_documents)
+ provider.reindex
+ end
+
+ it 'does not clear the index for a scoped reindex' do
+ expect(mock_index).not_to receive(:delete_all_documents)
+ allow(mock_index).to receive(:add_documents)
+ provider.reindex(store.products)
+ end
+ end
+
+ describe '#ensure_index_settings!' do
+ it 'declares grouping_id filterable, position sortable, and product_id distinct' do
+ expect(mock_index).to receive(:update_filterable_attributes).with(include('grouping_id'))
+ expect(mock_index).to receive(:update_sortable_attributes).with(include('position'))
+ expect(mock_index).to receive(:update_distinct_attribute).with('product_id')
+ allow(mock_index).to receive(:update_searchable_attributes)
+
+ provider.ensure_index_settings!
+ end
end
end
end
diff --git a/spree/core/spec/presenters/spree/search_provider/product_presenter_spec.rb b/spree/core/spec/presenters/spree/search_provider/product_presenter_spec.rb
index 4d6331f85c..b43b652364 100644
--- a/spree/core/spec/presenters/spree/search_provider/product_presenter_spec.rb
+++ b/spree/core/spec/presenters/spree/search_provider/product_presenter_spec.rb
@@ -94,6 +94,52 @@ module Spree
end
end
+ context 'membership documents (manual sort)' do
+ let(:collection) { create(:collection, store: store) }
+
+ before { Spree::ProductCollection.create!(collection: collection, product: product, position: 4) }
+
+ it 'emits a collection membership doc carrying position + full base payload' do
+ member = documents.find { |d| d[:grouping_id] == collection.prefixed_id }
+
+ expect(member).to be_present
+ expect(member[:position]).to eq(4)
+ expect(member[:name]).to eq('Test Shirt') # full base payload copied
+ expect(member[:product_id]).to eq(product.prefixed_id)
+ expect(member[:id]).to include(collection.prefixed_id)
+ end
+
+ it 'leaves base docs without a grouping_id/position' do
+ base = documents.reject { |d| d[:grouping_id] }
+
+ expect(base).not_to be_empty
+ base.each { |d| expect(d[:position]).to be_nil }
+ end
+ end
+
+ context 'category membership positions (subtree-MIN)' do
+ let(:taxonomy) { create(:taxonomy, store: store) }
+ let(:parent) { create(:taxon, taxonomy: taxonomy, name: 'Men') }
+ let(:jackets) { create(:taxon, taxonomy: taxonomy, parent: parent, name: 'Jackets') }
+ let(:coats) { create(:taxon, taxonomy: taxonomy, parent: parent, name: 'Coats') }
+ let(:product) { create(:product, name: 'Test Jacket', channels: [store.default_channel], taxons: [jackets, coats]) }
+
+ before do
+ Spree::ProductCategory.where(product: product, category: jackets).update_all(position: 5)
+ Spree::ProductCategory.where(product: product, category: coats).update_all(position: 2)
+ end
+
+ it 'emits a membership doc per ancestor-or-self, folding parent to the subtree minimum' do
+ jackets_doc = documents.find { |d| d[:grouping_id] == jackets.prefixed_id }
+ coats_doc = documents.find { |d| d[:grouping_id] == coats.prefixed_id }
+ parent_doc = documents.find { |d| d[:grouping_id] == parent.prefixed_id }
+
+ expect(jackets_doc[:position]).to eq(5)
+ expect(coats_doc[:position]).to eq(2)
+ expect(parent_doc[:position]).to eq(2) # MIN(5, 2) across the subtree
+ end
+ end
+
context 'with multiple markets' do
let!(:us_market) { create(:market, store: store, name: 'US', currency: 'USD', default_locale: 'en') }
let!(:eu_market) { create(:market, store: store, name: 'EU', currency: 'EUR', default_locale: 'de', supported_locales: 'de,fr') }