Understanding Algolia’s Ranking Formula

Algolia’s ranking formula determines which records appear first when multiple products match a shopper’s query. For WooCommerce stores, understanding this formula is essential when merchandising products, debugging unexpected results, and explaining search behavior to clients.

Ranking is a sequence of tie-breakers

Algolia does not normally calculate one simple weighted score for every product. Instead, it evaluates ranking criteria in order. A record that performs better on an earlier criterion ranks ahead of another record, even if the second record performs better on a later criterion.

The default ranking order is:

Typo: Records matching the query with fewer typos rank higher.
Geo: Records closer to the relevant location rank higher when geo-search is configured.
Words: Records matching more query words rank higher.
Filters: Records matching more filter conditions can rank higher in applicable searches.
Proximity: Query words appearing closer together rank higher.
Attribute: Matches in more important searchable attributes rank higher.
Exact: More exact matches rank higher.
Custom: Your configured business rules break remaining ties.

The precise behavior can vary with settings such as searchableAttributes, query rules, optional filters, personalization, replicas, and distinct settings. Treat the ranking formula as the core textual ranking process rather than the only mechanism affecting the final result.

Why custom ranking is not a replacement for relevance

A common WooCommerce request is to “sort products by best sellers” or “put products with the highest margin first.” Agencies often implement this by adding a custom ranking rule such as desc(sales_count). That is useful, but custom ranking is evaluated after the earlier textual criteria.

For example, if the query is running shoes, a product that matches both words, has a strong attribute match, and is exact may remain above a high-selling product that only weakly matches the query. This protects search relevance from being overwhelmed by business metrics.

Custom ranking is most effective when several records are already similarly relevant. It should usually refine a search result, not force unrelated products to the top.

Example custom ranking for a WooCommerce catalog

A product index might use a configuration like this:

{
  "searchableAttributes": [
    "unordered(name)",
    "unordered(categories)",
    "unordered(description)",
    "sku"
  ],
  "customRanking": [
    "desc(is_in_stock)",
    "desc(sales_count)",
    "desc(rating_average)",
    "asc(price)"
  ]
}

In this example, the custom criteria are evaluated in the order shown. Stock status is considered before sales count, sales count before rating, and rating before price. If two products remain tied after the first custom criterion, Algolia evaluates the next one.

Use numeric fields for numeric comparisons. Do not send formatted values such as "$1,299.00" when the field will be used for sorting or ranking. Send a numeric value such as 1299 instead.

How searchable attribute order affects ranking

The attribute criterion depends heavily on the order of searchableAttributes. If product name appears before description, a match in the name generally has more ranking importance than the same match in the description.

{
  "searchableAttributes": [
    "name",
    "categories",
    "brand",
    "short_description",
    "description",
    "sku"
  ]
}

For many WooCommerce catalogs, product name and category should receive more relevance than long descriptions. SKUs may need to be searchable for support teams and technical buyers, but placing SKU too prominently can produce surprising results for ordinary shoppers.

The unordered() modifier can reduce the importance of word position within an attribute. This is useful when the order of words in a product title should not strongly influence results. Test this carefully for catalogs where phrase order carries meaning.

Typo tolerance and product data quality

Typo ranking helps shoppers find products when they misspell a query, but it can also expose poor catalog data. Product names with inconsistent spelling, unnecessary abbreviations, or duplicated keywords make relevance harder to predict.

When debugging a result, compare an exact query with a misspelled query. If the result changes substantially, inspect typo tolerance, synonyms, and the indexed values before changing custom ranking. A high sales count should not automatically compensate for a product name that does not match the shopper’s intent.

Words, proximity, and exact matches

The words criterion rewards records matching more of the query. The proximity criterion considers how close query terms are to one another. The exact criterion can favor records containing exact matches, depending on the searchable fields and query structure.

Consider the query waterproof hiking jacket. A product titled “Waterproof Hiking Jacket” should generally perform better than a product whose description separately mentions “hiking,” “jacket,” and “waterproof” many paragraphs apart. If a client expects otherwise, inspect the indexed text and searchable attribute configuration rather than immediately adding a popularity rule.

Practical debugging with ranking information

When investigating an unexpected result, enable ranking information for a controlled test request. Algolia can return ranking details that help identify whether a record won because of typo count, matched words, proximity, attribute relevance, exact matching, or custom ranking.

Keep this diagnostic information out of normal production responses unless it is required by the application. Use it in a staging tool or an authenticated internal debugging workflow, and compare several records rather than inspecting only the first hit.

When to use replicas instead of custom ranking

Use a replica when the store needs a clearly different sort experience, such as:

Featured products
Lowest price
Highest price
Best-selling products
Newest products
Highest-rated products

A replica can preserve the same searchable content while using a different ranking configuration. This is usually cleaner than trying to make one ranking formula serve relevance, price sorting, popularity sorting, and merchandising at the same time.

For example, the primary index can prioritize textual relevance, while a virtual replica can use a price-oriented ranking. The frontend can let shoppers switch between these experiences without changing the underlying product data.

WooCommerce implementation checklist

Index clean product names, categories, brands, SKUs, and descriptions.
Keep stock, sales, rating, and price fields in typed numeric or boolean formats.
Order searchableAttributes according to business relevance, not database column order.
Use custom ranking to resolve relevant-product ties rather than to force unrelated products upward.
Use replicas for shopper-selected sort orders.
Test common queries, misspellings, brand searches, SKU searches, and multi-word category searches.
Review results separately for in-stock, out-of-stock, variable, and discounted products.
Document every ranking change so merchandising and development teams understand its effect.

A reliable way to tune the formula

Start with a representative query set from the store’s analytics and support tickets. Record the expected top results, then change one setting at a time. Compare the primary index with any replicas and test both exact product searches and broad category queries.

For agencies, the most maintainable approach is to separate concerns: searchable attributes define what relevance means, the ranking criteria resolve textual differences, custom ranking expresses modest business preferences, and replicas provide alternate sort modes. This structure makes search behavior easier to explain, test, and maintain as the WooCommerce catalog changes.

Table of contents :