Skip to main content

​
Overview

Meilisearch is a fast, open-source search engine that provides typo tolerance, relevance ranking, faceted filtering, and sub-50ms search responses. Spree includes a built-in Meilisearch search provider that replaces the default SQL-based search. When to use Meilisearch:
  • Catalogs with 1,000+ products
  • 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
  • Small catalogs (< 1,000 products)
  • Simple search requirements

​
Setup

​
1. Install Meilisearch

For local development, Meilisearch runs without authentication by default — no API key is needed. For production, set a master key (minimum 16 bytes) via MEILI_MASTER_KEY when starting Meilisearch. Use this master key as your MEILISEARCH_API_KEY.

​
2. Add the gem to your Gemfile

​
3. Configure environment variables

​
4. Set the search provider

​
5. Index your products

That’s it. Your Store API now uses Meilisearch for all product search, filtering, and faceted navigation.

​
How It Works

​
Indexing

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). For example, a store with a US market (USD, English) and an EU market (EUR, German/French) creates 3 index documents per product: 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:

​
Search Flow

  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 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

Each store gets its own Meilisearch index: {store_code}_products. For a store with code "my-store", the index name is my_store_products.

​
Manual Operations

​
Reindex all products

​
Index a single product

​
Remove a product from the index

​
Preview indexed data

​
Configuration

The index is automatically configured with the correct filterable, sortable, and searchable attributes when you run rake spree:search:reindex.

​
Filterable Attributes

The Meilisearch provider automatically configures these filterable attributes:
  • 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_value_ids — prefixed option value IDs

​
Sortable Attributes

  • 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

The Meilisearch provider is fully compatible with the existing Store API. No client-side changes are needed:
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 keys

Meilisearch supports tenant tokens for fine-grained access control. Use an admin key for indexing and a search key for queries.

​
Meilisearch Cloud

For production deployments, consider Meilisearch Cloud for managed hosting, automatic scaling, and monitoring.