Ranking Fields

These fields control how products are ranked and sorted in search results and category listings. They are used by the Ranking Mix feature.

Source Fields

Provide these fields in your import data to enable ranking:

Field	Type	Description	Used For
`soldamount`	float	Number of units sold	Sales-based ranking
`rating`	float	Product rating (e.g., 1-5)	Rating-based ranking
`insert`	date	Product creation date	Newness ranking
`profit_margin`	float	Profit margin percentage	Margin-based ranking
`stock`	integer	Stock quantity	Out-of-stock demotion

Example Import

{
  "id": "product-123",
  "type": "product",
  "title": "Blue T-Shirt",
  "soldamount": 150,
  "rating": 4.5,
  "insert": "2024-01-15",
  "profit_margin": 35.5,
  "stock": 100
}

Normalized Boost Fields

When using the Persistence Layer, source fields are automatically normalized to a 0-1 scale:

Normalized Field	Source	Description
`mak_boost_norm_insert`	`insert`	Newness score (newer = higher)
`mak_boost_norm_sold`	`soldamount`	Sales performance
`mak_boost_norm_rating`	`rating`	Customer rating
`mak_boost_norm_revenue`	`soldamount × price`	Revenue generated
`mak_boost_norm_profit_margin`	`profit_margin`	Profit margin
`mak_boost_norm_basket`	Analytics	Cart additions
`mak_boost_norm_view`	Analytics	Product views

Normalization Formula

normalized = (log(value + 1) - log(min + 1)) / (log(max + 1) - log(min + 1))

This logarithmic normalization ensures:

All values are scaled between 0 and 1
Outliers don't dominate rankings
Relative differences are preserved

Note: Without the Persistence Layer, normalized fields are not automatically calculated. You can provide pre-calculated values or use the source fields directly.

Ranking Mix Configuration

The Ranking Mix in the admin UI maps to these fields:

Admin UI Name	Elasticsearch Field	Source Data
New	`mak_boost_norm_insert`	`insert` date
Sold	`mak_boost_norm_sold`	`soldamount`
Basket	`mak_boost_norm_basket`	Analytics
View	`mak_boost_norm_view`	Analytics
Revenue	`mak_boost_norm_revenue`	Calculated
Rating	`mak_boost_norm_rating`	`rating`
Profit Margin	`mak_boost_norm_profit_margin`	`profit_margin`

Stock-Based Ranking

The stock field has a special use: when "Out of stock at the end" is enabled in the Ranking Mix:

Products with stock = 0 are pushed to the bottom of results
Their search score is multiplied by 0
This applies to both search and category listings

How It Works

Product A: stock = 100, score = 0.8  → Final: 0.8 (top)
Product B: stock = 50,  score = 0.6  → Final: 0.6 (middle)
Product C: stock = 0,   score = 0.9  → Final: 0.0 (bottom)

Group-Specific Stock

Stock can be overridden per customer group:

{
  "id": "product-123",
  "stock": 100,
  "groups": {
    "wholesale": {
      "stock": 1000
    },
    "retail": {
      "stock": 50
    }
  }
}

Machine Learning Boost Fields

Additional boost fields from ML and analytics:

Field Pattern	Description
`mak_boost_{key}`	ML-derived boost value
`mak_boost_category_{id}`	Category-specific boost
`mak_boost_manufacturer_{id}`	Manufacturer-specific boost

These are populated automatically when Machine Learning features are enabled.

Best Practices

Provide source data - Include soldamount, rating, insert, and profit_margin for full ranking capabilities.
Keep stock updated - The stock field directly affects ranking when "out of stock at the end" is enabled.
Use the Persistence Layer - For automatic normalization and consistent boost calculations.
Monitor analytics - basket and view boosts require tracking integration.