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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Update search providers docs
Damian Legawieca3b11f82f4e9
diff --git a/docs/developer/core-concepts/search-filtering.mdx b/docs/developer/core-concepts/search-filtering.mdxindex 8e3fb268fe..8422d0c0f5 100644--- a/docs/developer/core-concepts/search-filtering.mdx+++ b/docs/developer/core-concepts/search-filtering.mdx@@ -245,11 +245,11 @@ Spree.search_provider = 'Spree::SearchProvider::Meilisearch'No client-side or API changes are needed — the same `q[search]`, filter params, and sort options work with any provider.-See [Search Providers](/developer/customization/search-providers) for architecture details and how to build custom providers.+See [Build a Custom Search Provider](/developer/how-to/custom-search-provider) for architecture details and how to build custom providers.## Related Documentation- [Products](/developer/core-concepts/products) — Product catalog and listing- [Querying](/api-reference/store-api/querying) — API filtering, sorting, and pagination reference-- [Search Providers](/developer/customization/search-providers) — Architecture and custom providers+- [Build a Custom Search Provider](/developer/how-to/custom-search-provider) — Step-by-step guide- [Meilisearch Integration](/integrations/search/meilisearch) — Setup guidediff --git a/docs/developer/customization/search-providers.mdx b/docs/developer/customization/search-providers.mdxdeleted file mode 100644index f0548a0a90..0000000000--- a/docs/developer/customization/search-providers.mdx+++ /dev/null@@ -1,179 +0,0 @@-----title: Search Providers-description: "Replace the default database search with Meilisearch, Elasticsearch, or a custom search engine"------## Overview--Spree uses a pluggable search provider architecture. The search provider handles product search, filtering, sorting, and faceted navigation. By default, Spree uses SQL-based search (ILIKE queries via Ransack). You can replace it with an external search engine like [Meilisearch](/integrations/search/meilisearch) for typo tolerance, relevance ranking, and faster faceted search.--## Architecture--```-Store API Request- │- ├─ AR Scope (security + visibility)- │ store.products.active(currency).accessible_by(ability)- │- └─ Search Provider (search + filter + facets)- ├─ Database (default): ILIKE + Ransack + FiltersAggregator- └─ Meilisearch: one API call for search + filter + facets-```--The controller builds a base ActiveRecord scope for **security and visibility** (store scoping, active products, authorization), then delegates **everything else** to the search provider — text search, structured filtering, sorting, pagination, and facet aggregation.--## Configuration--Set the search provider in `config/initializers/spree.rb`:--```ruby-# Default — SQL-based search (no external dependencies)-Spree.search_provider = 'Spree::SearchProvider::Database'--# Meilisearch — recommended for production-Spree.search_provider = 'Spree::SearchProvider::Meilisearch'-```--## Built-in Providers--### Database (default)--`Spree::SearchProvider::Database` wraps the existing Ransack + ILIKE search. No external dependencies. Suitable for development and small catalogs (< 10,000 products).--- Text search: ILIKE on product name + variant SKU-- Filtering: Ransack query params (price, options, categories, stock)-- Facets: `FiltersAggregator` with per-option-value counts-- Sorting: Ransack + custom scopes (price, best_selling)--### Meilisearch--`Spree::SearchProvider::Meilisearch` uses [Meilisearch](https://www.meilisearch.com/) for search, filtering, and faceting in a single API call. Recommended for production. See the [Meilisearch integration guide](/integrations/search/meilisearch) for setup instructions.--## Building a Custom Search Provider--Create a class that inherits from `Spree::SearchProvider::Base` and implements `search_and_filter`:--```ruby-# app/models/my_app/search_provider/typesense.rb-module MyApp- module SearchProvider- class Typesense < Spree::SearchProvider::Base- def search_and_filter(scope:, query: nil, filters: {}, sort: nil, page: 1, limit: 25)- # 1. Query your search engine- results = typesense_client.collections['products'].documents.search({- q: query || '*',- query_by: 'name,description,sku',- filter_by: build_filters(filters),- sort_by: build_sort(sort),- page: page,- per_page: limit,- facet_by: 'category_ids,in_stock,price'- })-- # 2. Get product IDs from search results- ids = results['hits'].map { |h| h['document']['id'] }-- # 3. Intersect with AR scope for security/visibility- products = ids.any? ? scope.where(id: ids).in_order_of(:id, ids) : scope.none-- # 4. Return a SearchResult- Spree::SearchProvider::SearchResult.new(- products: products,- filters: build_facet_response(results['facet_counts']),- sort_options: %w[price -price name -name -available_on],- total_count: results['found']- )- end-- # Index a product (called via background job on product save)- def index(product)- document = Spree::SearchProvider::ProductPresenter.new(product, store).call- typesense_client.collections['products'].documents.upsert(document)- end-- def remove(product)- remove_by_id(product.id)- end-- def remove_by_id(product_id)- typesense_client.collections['products'].documents[product_id].delete- end-- def reindex(scope = nil)- scope ||= store.products- scope.find_in_batches(batch_size: 500) do |batch|- documents = batch.map { |p| Spree::SearchProvider::ProductPresenter.new(p, store).call }- typesense_client.collections['products'].documents.import(documents, action: 'upsert')- end- end- end- end-end-```--Then register it:--```ruby-# config/initializers/spree.rb-Spree.search_provider = 'MyApp::SearchProvider::Typesense'-```--### Provider Contract--| Method | Required | Description |-|--------|----------|-------------|-| `search_and_filter(scope:, query:, filters:, sort:, page:, limit:)` | Yes | Search, filter, sort, paginate, and return facets. Must return a `SearchResult`. |-| `index(product)` | No | Index a single product. Called via background job on create/update. No-op for database provider. |-| `remove(product)` | No | Remove a product from the index. Called via background job on destroy. |-| `remove_by_id(product_id)` | No | Remove by ID (product may already be deleted). |-| `reindex(scope)` | No | Bulk reindex. Called via `rake spree:search:reindex`. |--### SearchResult--`search_and_filter` must return a `Spree::SearchProvider::SearchResult`:--```ruby-Spree::SearchProvider::SearchResult.new(- products: ar_relation, # ActiveRecord::Relation — paginated products- filters: [...], # Array of filter hashes (facets)- sort_options: [...], # Array of sort option strings- total_count: 150 # Integer — total matching products (before pagination)-)-```--### ProductPresenter--Use `Spree::SearchProvider::ProductPresenter` to serialize products for indexing. It handles multi-currency prices, translations, option values, categories (with prefixed IDs), and stock status:--```ruby-presenter = Spree::SearchProvider::ProductPresenter.new(product, store)-document = presenter.call-# => {-# id: 42, prefixed_id: "prod_abc", name: "Blue Shirt", slug: "blue-shirt",-# status: "active", sku: "SHIRT-001", in_stock: true,-# category_ids: ["ctg_abc", "ctg_def"], category_names: ["Clothing", "Shirts"],-# option_values: ["Small", "Medium", "Large", "Blue", "Red"],-# price_USD: 29.99, price_EUR: 27.50, compare_at_price_USD: 39.99,-# name_en: "Blue Shirt", name_fr: "Chemise Bleue", ...-# }-```--### Indexing Lifecycle--Products include the `Spree::SearchIndexable` concern which provides:--- **Automatic indexing** — background jobs enqueue on `after_commit` (create/update/destroy). Jobs are skipped for the Database provider.-- **Manual indexing** — `product.add_to_search_index` (synchronous, inline)-- **Manual removal** — `product.remove_from_search_index` (synchronous, inline)-- **Preview** — `product.search_presentation` returns the hash that would be indexed-- **Bulk reindex** — `rake spree:search:reindex`--### Important: Prefixed IDs--Always use prefixed IDs (e.g., `ctg_abc`, `prod_xyz`) when indexing association references. Never use raw database IDs — Spree supports UUID primary keys.--## Related Documentation--- [Search & Filtering](/developer/core-concepts/search-filtering) — Store API search and filtering reference-- [Meilisearch Integration](/integrations/search/meilisearch) — Setup guide for Meilisearch-- [Dependencies](/developer/customization/dependencies) — How to swap Spree servicesdiff --git a/docs/developer/how-to/custom-search-provider.mdx b/docs/developer/how-to/custom-search-provider.mdxnew file mode 100644index 0000000000..5c46a6cdce--- /dev/null+++ b/docs/developer/how-to/custom-search-provider.mdx@@ -0,0 +1,236 @@+---+title: Build a Custom Search Provider+description: Step-by-step guide to building a custom search provider for Spree, integrating external search engines like Typesense, Algolia, or Elasticsearch.+---++## Overview++This guide walks you through building a custom search provider for Spree. By the end, you'll have a fully functional search integration that:++- Powers product search, filtering, sorting, and faceted navigation+- Handles multi-locale and multi-currency indexing automatically+- Integrates with the Store API without any frontend changes+- Supports background indexing and bulk reindex++Before starting, make sure you understand [how search and filtering works in Spree](/developer/core-concepts/search-filtering).++<Info>+Spree ships with a built-in [Meilisearch provider](/integrations/search/meilisearch). If Meilisearch fits your needs, you don't need to build a custom provider — just configure it.+</Info>++## Architecture++```+Store API Request (locale=de, currency=EUR)+ │+ ├─ AR Scope (security + visibility)+ │ store.products.active(currency).accessible_by(ability)+ │+ └─ Search Provider (search + filter + facets)+ ├─ Database (default): ILIKE + Ransack + FiltersAggregator+ ├─ Meilisearch (built-in): one API call with locale/currency filtering+ └─ Your Provider: implements the same interface+```++The controller builds a base ActiveRecord scope for **security and visibility**, then delegates **everything else** to your search provider.++## Step 1: Create the Provider Class++Create a class that inherits from `Spree::SearchProvider::Base` and implements `search_and_filter`:++```ruby app/models/my_app/search_provider/typesense.rb+module MyApp+ module SearchProvider+ class Typesense < Spree::SearchProvider::Base+ # Enable background indexing jobs+ def self.indexing_required?+ true+ end++ def initialize(store)+ super+ require 'typesense'+ rescue LoadError+ raise LoadError, "Add `gem 'typesense'` to your Gemfile"+ end+ end+ end+end+```++`indexing_required?` returning `true` tells the `SearchIndexable` concern to enqueue background jobs when products are created, updated, or destroyed.++## Step 2: Implement `search_and_filter`++This is the core method. It receives a base AR scope (already filtered for security) and must return a `SearchResult`:++```ruby app/models/my_app/search_provider/typesense.rb+def search_and_filter(scope:, query: nil, filters: {}, sort: nil, page: 1, limit: 25)+ page = [page.to_i, 1].max+ limit = limit.to_i.clamp(1, 100)++ # 1. Query your search engine with locale/currency filtering+ results = client.collections[index_name].documents.search({+ q: query || '*',+ query_by: 'name,description,sku,option_values,category_names,tags',+ filter_by: build_filters(filters),+ sort_by: build_sort(sort),+ page: page,+ per_page: limit,+ facet_by: 'in_stock,price,category_ids,option_value_ids'+ })++ # 2. Extract product IDs (documents have composite IDs, extract product_id)+ product_ids = results['hits'].map { |h| h['document']['product_id'] }.uniq+ raw_ids = product_ids.filter_map { |pid| Spree::Product.decode_prefixed_id(pid) }++ # 3. Intersect with AR scope (safety net for authorization)+ products = raw_ids.any? ? scope.where(id: raw_ids).reorder(nil) : scope.none++ # 4. Build Pagy for pagination metadata+ require 'pagy'+ pagy = Pagy::Offset.new(count: results['found'], page: page, limit: limit)++ # 5. Return a SearchResult+ Spree::SearchProvider::SearchResult.new(+ products: products,+ filters: build_facet_response(results['facet_counts']),+ sort_options: %w[price -price name -name best_selling -available_on].map { |id| { id: id } },+ default_sort: 'manual',+ total_count: results['found'],+ pagy: pagy+ )+end+```++<Warning>+Always filter by `locale`, `currency`, `store_ids`, `status='active'`, and `discontinue_on` in your search engine — not just in the AR scope. This ensures pagination counts are accurate. The AR scope is a safety net, not the primary filter.+</Warning>++## Step 3: Implement Indexing++Products are indexed as **one document per market × locale** combination. The `ProductPresenter` handles this automatically:++```ruby app/models/my_app/search_provider/typesense.rb+def index(product)+ documents = Spree::SearchProvider::ProductPresenter.new(product, store).call+ documents.each do |doc|+ client.collections[index_name].documents.upsert(doc)+ end+end++def remove(product)+ remove_by_id(product.prefixed_id)+end++def remove_by_id(prefixed_id)+ # Delete all locale/currency variants of this product+ client.collections[index_name].documents.delete(+ filter_by: "product_id:=#{prefixed_id}"+ )+end+```++The `ProductPresenter` returns an array of documents. For a store with US (USD/English) and EU (EUR/German+French) markets, one product produces 3 documents — each with flat `name`, `price`, `locale`, `currency` fields.++## Step 4: Implement Bulk Reindex++Use `ProductPresenter::REQUIRED_PRELOADS` to avoid N+1 queries:++```ruby app/models/my_app/search_provider/typesense.rb+def reindex(scope = nil)+ scope ||= store.products+ ensure_index_settings!++ scope.reorder(id: :asc)+ .preload(*Spree::SearchProvider::ProductPresenter::REQUIRED_PRELOADS)+ .find_in_batches(batch_size: 500) do |batch|+ documents = batch.flat_map { |p| Spree::SearchProvider::ProductPresenter.new(p, store).call }+ index_batch(documents)+ end+end++def index_batch(documents)+ client.collections[index_name].documents.import(documents, action: 'upsert')+end++def ensure_index_settings!+ # Create/update your collection schema here+end+```++<Info>+Use `flat_map` (not `map`) because `ProductPresenter#call` returns an array of documents per product.+</Info>++## Step 5: Register the Provider++```ruby config/initializers/spree.rb+Spree.search_provider = 'MyApp::SearchProvider::Typesense'+```++Then reindex:++```bash+rake spree:search:reindex+```++## Provider Contract Reference++| Method | Required | Description |+|--------|----------|-------------|+| `search_and_filter(scope:, query:, filters:, sort:, page:, limit:)` | Yes | Search, filter, sort, paginate, and return facets. Must return a `SearchResult`. |+| `self.indexing_required?` | Yes | Return `true` to enable background indexing jobs. |+| `index(product)` | Yes | Index a single product. `ProductPresenter#call` returns an array of documents. |+| `remove(product)` | Yes | Remove all locale/currency variants from the index. |+| `remove_by_id(prefixed_id)` | Yes | Remove by prefixed product ID (product may already be deleted). |+| `reindex(scope)` | Yes | Bulk reindex with `ensure_index_settings!` + batch indexing. |+| `index_batch(documents)` | Yes | Index a batch of pre-serialized documents. |+| `ensure_index_settings!` | No | Configure index schema. Called by `reindex` and rake task. |++### SearchResult++```ruby+Spree::SearchProvider::SearchResult.new(+ products: ar_relation, # ActiveRecord::Relation+ filters: [...], # Array of facet hashes+ sort_options: [{ id: 'price' }, ...], # Array of sort option objects+ default_sort: 'manual', # Default sort string+ total_count: 150, # Total before pagination+ pagy: pagy_object # Pagy::Offset or Pagy::Meilisearch+)+```++### ProductPresenter++```ruby+documents = Spree::SearchProvider::ProductPresenter.new(product, store).call+# => [+# { prefixed_id: "prod_abc_en_USD", product_id: "prod_abc", locale: "en",+# currency: "USD", name: "Blue Shirt", price: 29.99, ... },+# { prefixed_id: "prod_abc_de_EUR", product_id: "prod_abc", locale: "de",+# currency: "EUR", name: "Blaues Hemd", price: 27.50, ... }+# ]+```++### Indexing Lifecycle++The `Spree::SearchIndexable` concern on Product provides:++| Method | Description |+|--------|-------------|+| `product.add_to_search_index` | Index synchronously (inline) |+| `product.remove_from_search_index` | Remove synchronously (inline) |+| `product.search_presentation` | Preview the documents that would be indexed |+| `rake spree:search:reindex` | Bulk reindex all products |++Background jobs (`IndexJob`, `RemoveJob`) fire on `after_commit` when `indexing_required?` is `true`.++### Important: Prefixed IDs++Always use prefixed IDs (`ctg_abc`, `prod_xyz`, `optval_abc`) when indexing. Never use raw database IDs — Spree supports UUID primary keys.++## Related Documentation++- [Search & Filtering](/developer/core-concepts/search-filtering) — Store API search reference+- [Meilisearch Integration](/integrations/search/meilisearch) — Built-in Meilisearch provider setupdiff --git a/docs/docs.json b/docs/docs.jsonindex 002684fa4c..296759066d 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -275,6 +275,11 @@"group": "Reports","icon": "chart-bar","pages": ["developer/how-to/custom-report"]+ },+ {+ "group": "Search",+ "icon": "search",+ "pages": ["developer/how-to/custom-search-provider"]}]},diff --git a/docs/integrations/search/meilisearch.mdx b/docs/integrations/search/meilisearch.mdxindex d013ce54db..93cb6f0632 100644--- a/docs/integrations/search/meilisearch.mdx+++ b/docs/integrations/search/meilisearch.mdx@@ -12,6 +12,7 @@ description: "Set up Meilisearch for fast, typo-tolerant product search with fac- Need typo tolerance and relevance ranking- Want faceted filtering with adjusted counts- Require sub-second search responses+- Multi-locale / multi-currency storefronts**When the default Database provider is sufficient:**- Development environments@@ -89,14 +90,26 @@ That's it. Your Store API now uses Meilisearch for all product search, filtering### Indexing-Products are automatically indexed in background jobs when they are created, updated, or destroyed. Each product is serialized by `Spree::SearchProvider::ProductPresenter` which includes:+Products are indexed as **one document per market × locale** combination. Each document contains the product's name and description in that locale, the price in that market's currency, and all non-translated fields (categories, options, stock, tags).-- Product name, description, slug, SKU, status-- Prices in **all currencies** (e.g., `price_USD: 29.99`, `price_EUR: 27.50`)-- Translations in **all locales** (e.g., `name_en: "Shirt"`, `name_fr: "Chemise"`)-- Category IDs (prefixed, e.g., `ctg_abc`)-- Option values (e.g., `["Small", "Medium", "Blue", "Red"]`)+For example, a store with a US market (USD, English) and an EU market (EUR, German/French) creates 3 index documents per product:++| Document ID | Name | Price | Locale | Currency |+|---|---|---|---|---|+| `prod_abc_en_USD` | Blue Shirt | 29.99 | en | USD |+| `prod_abc_de_EUR` | Blaues Hemd | 27.50 | de | EUR |+| `prod_abc_fr_EUR` | Chemise Bleue | 27.50 | fr | EUR |++Products are **only indexed for markets where they have a price**. If a product has no EUR price, no EUR documents are created.++Translations use **Mobility with fallback** — if a product has no German translation, the default locale (English) is used.++Each document includes:+- Translated name, description, slug+- Price and compare-at price in the market's currency+- Category IDs, option type/value IDs (all prefixed)- Stock status, tags, timestamps+- Store IDs, locale, currency (for filtering)Preview what gets indexed:@@ -104,7 +117,7 @@ Preview what gets indexed:# Rails consoleproduct = Spree::Product.firstproduct.search_presentation-# => { id: 1, prefixed_id: "prod_abc", name: "Blue Shirt", price_USD: 29.99, ... }+# Returns an array of documents — one per market × locale```### Search Flow@@ -113,12 +126,13 @@ product.search_presentationGET /api/v3/store/products?q[search]=shirt&q[price_gte]=20&sort=price```-1. Controller builds AR scope: store.products.active('USD').accessible_by(ability)-2. Provider sends one Meilisearch API call: search + filters + facets + sort + pagination-3. Provider intersects Meilisearch IDs with AR scope (enforces visibility/authorization)-4. Returns products + facets + total count+1. Controller builds AR scope for security: `store.products.active(currency).accessible_by(ability)`+2. Meilisearch provider adds base filters: `locale='en' AND currency='USD' AND status='active' AND store_ids='{id}' AND not_discontinued`+3. Provider sends **one Meilisearch API call**: search + user filters + facets + sort + pagination+4. Provider intersects Meilisearch product IDs with AR scope (safety net)+5. Returns products + facets with adjusted counts + pagination-The AR scope ensures that draft products, products from other stores, and unauthorized products are never returned — even if they exist in the Meilisearch index.+The base filters ensure Meilisearch only returns products visible in the current locale and currency. The AR scope is a safety net — it should not filter out any additional products.### Index Name@@ -155,7 +169,7 @@ product.search_presentation| Environment Variable | Default | Description ||---|---|---|| `MEILISEARCH_URL` | `http://localhost:7700` | Meilisearch server URL |-| `MEILISEARCH_API_KEY` | `nil` | Master or admin API key |+| `MEILISEARCH_API_KEY` | `nil` | Meilisearch master key. Not needed for local development — only required when Meilisearch is started with `MEILI_MASTER_KEY`. |The index is automatically configured with the correct filterable, sortable, and searchable attributes when you run `rake spree:search:reindex`.@@ -163,18 +177,34 @@ The index is automatically configured with the correct filterable, sortable, andThe Meilisearch provider automatically configures these filterable attributes:-- `status` — product status (active, draft, archived)+- `product_id` — prefixed product ID (for bulk deletion of locale/currency variants)+- `status` — product status (always filtered to `active` for Store API)- `in_stock` — boolean stock availability+- `store_ids` — which stores the product belongs to+- `locale` — document locale (filtered per request)+- `currency` — document currency (filtered per request)+- `discontinue_on` — Unix timestamp for discontinuation filtering+- `price` — price in the document's currency- `category_ids` — prefixed category IDs- `tags` — product tags-- `option_values` — option value presentations (Size, Color, etc.)-- `price_{CURRENCY}` — price per currency (e.g., `price_USD`, `price_EUR`)+- `option_value_ids` — prefixed option value IDs## Sortable Attributes-- `price_{CURRENCY}` — sort by price in any currency+- `name` — sort alphabetically (locale-aware via per-locale documents)+- `price` — sort by price (currency-aware via per-currency documents)- `created_at` — sort by creation date- `available_on` — sort by availability date+- `units_sold_count` — sort by best selling++## Searchable Attributes++- `name` — product name (in document locale)+- `description` — product description (in document locale)+- `sku` — variant SKU+- `option_values` — option value presentations (e.g., "Red", "Small")+- `category_names` — category names+- `tags` — product tags## Store API Compatibility@@ -192,21 +222,14 @@ const products = await client.products.list({})```+Locale and currency are automatically resolved from request headers (`x-spree-locale`, `x-spree-currency`) — no need to pass them as filter params.+## Production Recommendations### Separate search and admin keysMeilisearch supports [tenant tokens](https://www.meilisearch.com/docs/learn/security/tenant_tokens) for fine-grained access control. Use an admin key for indexing and a search key for queries.-### Monitor index size--Check your index stats:--```ruby-provider = Spree::SearchProvider::Meilisearch.new(Spree::Store.default)-# Access the underlying client if needed for monitoring-```-### Meilisearch CloudFor production deployments, consider [Meilisearch Cloud](https://www.meilisearch.com/cloud) for managed hosting, automatic scaling, and monitoring.@@ -214,4 +237,4 @@ For production deployments, consider [Meilisearch Cloud](https://www.meilisearch## Related Documentation- [Search & Filtering](/developer/core-concepts/search-filtering) — Store API search reference-- [Search Providers](/developer/customization/search-providers) — Architecture and custom providers+- [Search Providers](/developer/how-to/custom-search-provider) — Architecture and custom providers