Migrating From Algolia Recommend to a Ranking API Step by Step

Migrating from Algolia Recommend to a ranking API is not simply an API replacement.

It changes who owns candidate generation, behavioral data, personalization, business rules, and final ordering.

Algolia Recommend is designed around recommendation use cases such as Related Items, Frequently Bought Together, Trending Items, and personalized recommendations. Its models use catalog data together with behavioral signals such as views, clicks, and conversions, as described in Algolia's AI Recommendations product documentation.

A ranking API solves a narrower problem:

Given this user, this context, and these eligible candidates, what order should they appear in?

If your application already retrieves candidates, moving to a ranking API can give your engineering team more control over retrieval, eligibility, ranking logic, experimentation, and future monetization.

The safest migration follows this sequence:

Inventory → Recover events → Define candidates → Map schemas → Backfill → Dual-write → Shadow → A/B test → Cut over → Keep rollback

When should you move from Algolia Recommend to a ranking API?

Start by separating recommendation from ranking.

A common recommendation architecture has three distinct stages:

candidate generation → scoring → re-ranking

Candidate generation reduces a large corpus to a manageable set. Scoring orders those candidates. Re-ranking then applies additional constraints such as freshness, diversity, or business requirements.

This pattern is reflected in Google's recommendation systems architecture guidance, which distinguishes candidate generation from later scoring and re-ranking stages.

The same separation appears in the well-known YouTube recommendation system research published by Google, where candidate generation and ranking are handled as separate production problems.

For a marketplace, creator platform, job board, or content application, your system may already generate 100 to 500 eligible candidates.

If so, you may not need another system to discover candidates.

You need a system to rank them.

Algolia's own guidance also distinguishes retrieval and recommendation from later reranking, particularly when teams use an external reranking layer after eligibility and retrieval have already been resolved.

Algolia Recommend vs a ranking API

Concern	Algolia Recommend	Ranking API
Candidate generation	Recommend model can generate recommendations	Application supplies candidates
Primary IDs	objectID, userToken	Candidate ID, user ID
Behavioral inputs	Views, clicks, conversions	Application-defined events and features
Personalization	User affinities influence recommendations	User and context directly affect ranking
Eligibility	Filters and query constraints	Usually enforced before ranking
Retrieval	Often tied to indexed content	Owned by application
Final output	Recommended items	Ordered candidate set

The objective of migration is not to recreate Algolia internally.

It is to preserve the useful behavior while creating a clearer boundary between retrieval and ranking.

Step 1: Inventory every Algolia Recommend surface

Do not migrate everything as one system.

List every place where Recommend currently affects the product.

Record:

• Algolia index
• recommendation model
• objectID
• userToken
• event names
• filters
• recommendation count
• personalization settings
• fallback behavior
• downstream rules
• click and conversion tracking

Then classify each use case.

A Frequently Bought Together carousel may genuinely need recommendation-based candidate generation.

A personalized home feed may already have hundreds of candidates available from another system.

The first may remain a recommendation problem.

The second may be a ranking problem.

This distinction prevents you from replacing useful candidate-generation logic unnecessarily.

Step 2: Recover your behavioral event history

Your behavioral dataset is often more valuable than the current model.

Algolia uses interactions between users and objects to train and personalize recommendations, which means the migration must preserve the meaning of views, clicks, conversions, and other user actions.

At minimum, recover:

user_id

object_id

event_type

event_name

timestamp

surface

position

session_id

query_id or recommendation_id

Where possible, use your own analytics warehouse, database, event stream, or raw application logs as the source of truth.

This is especially important because Algolia does not provide a simple native workflow for exporting a complete historical event dataset from one application and recreating it elsewhere. Its support guidance on copying Recommend event data between applications makes that limitation explicit.

Do not design a migration that assumes the vendor can always reconstruct your full behavioral history.

Own the raw events yourself.

Step 3: Preserve user and candidate identity

Avoid changing IDs unnecessarily.

A straightforward mapping might be:

objectID → candidate_id

userToken → user_id

If anonymous sessions are important, preserve them separately from authenticated identities.

Algolia's guidance on userToken and authenticatedUserToken usage recommends keeping user identity consistent across queries and events.

That consistency matters during migration.

If historical interactions belong to user_4812, the new ranking system should not suddenly know that same person as an unrelated identifier unless you maintain a deterministic mapping.

The same principle applies to candidates.

If your old system identifies a listing as:

listing_93882

preserve that identifier unless there is a strong architectural reason to change it.

Step 4: Define candidate generation explicitly

A ranking API needs candidates.

So before replacing Recommend, answer:

Where will the candidate set come from?

Possible sources include:

• Algolia Search
• SQL queries
• vector retrieval
• category matching
• followed creators
• geographic filters
• recently active inventory
• editorial pools
• trending content
• business-specific retrieval systems

This is where many migrations fail.

The team removes the recommendation system and only later realizes the previous vendor was doing more candidate generation than expected.

Document the retrieval contract clearly.

For example:

Input: user + current surface

Retrieval: return up to 300 eligible posts

Ranking: score those 300

Final response: return top 30

That architecture is much easier to reason about and test.

Step 5: Apply hard eligibility before ranking

Do not use ranking scores to enforce hard product constraints.

Remove candidates that should never appear before calling the ranker.

Examples include:

• blocked users
• unavailable products
• deleted content
• geographic restrictions
• privacy restrictions
• age restrictions
• moderation exclusions
• permission rules

This follows the same principle described in Google's recommendation re-ranking guidance, where final ordering can apply diversity, freshness, and other constraints after the core recommendation or scoring stage.

The ranker should answer:

Which eligible candidate is better?

It should not answer:

Is this candidate allowed to appear at all?

That distinction keeps policy logic deterministic.

Step 6: Map Algolia events into ranking signals

Do not turn every positive interaction into a generic engagement event.

Different actions express different levels of intent.

For example:

view → weak signal

click → moderate signal

save → strong signal

purchase → conversion

hide → negative signal

Algolia's own personalization guidance allows behavioral events to receive different weights because actions do not carry equal preference value. That same principle should survive the migration.

Create an explicit event contract before backfilling.

For example:

Existing event	New signal	Meaning
Product Viewed	view	Weak positive
Product Clicked	click	Moderate positive
Added to Cart	high_intent	Strong positive
Purchased	conversion	Outcome
Hidden	negative	Explicit negative

The schema is more important than the exact field names.

What matters is preserving intent.

Step 7: Backfill historical data, then dual-write

Before sending production ranking requests, backfill historical interactions.

Validate:

• total event counts
• unique users
• unique candidates
• timestamp range
• event distribution
• missing identifiers
• duplicated events

Then start dual-writing new events.

If a user clicks a result today, both the existing Algolia pipeline and the replacement ranking pipeline should receive that event during the transition period.

Without dual-write, the systems drift apart.

Algolia continues learning from fresh behavior while the new system evaluates stale history.

That makes any ranking comparison unreliable.

Step 8: Shadow the new ranking API

Do not change what users see immediately.

Send the same production candidate sets to both systems and record the replacement rankings without exposing them to users.

Track:

• top-10 overlap
• position changes
• missing candidates
• candidate counts
• empty responses
• p50 latency
• p95 latency
• p99 latency
• cold-start behavior
• diversity
• business-rule violations

Do not expect identical results.

The purpose of shadow mode is to identify unexplained or harmful differences.

For teams moving toward a candidate-in, ranked-list-out architecture, the Gortex Ranking API is one example of a decision layer that can sit after retrieval while candidate generation remains inside the application's existing stack.

Step 9: Run a controlled A/B test

Shadow testing verifies technical compatibility.

It does not prove that the replacement ranking is better.

Route a small portion of production traffic to the new path.

A reasonable sequence might be:

5% → 10% → 25% → 50% → 100%

Measure actual product outcomes:

• CTR
• conversion
• revenue per session
• watch time
• dwell time
• saves
• applications
• matches
• retention
• negative feedback

This matters because offline ranking similarity does not tell you whether users prefer the new ordering.

Algolia's own personalization guidance recommends validating personalization through experiments rather than assuming that a different ranking strategy automatically improves business outcomes.

The winning system is the one that improves the metric your product actually cares about.

Step 10: Keep rollback available

Do not delete the Algolia path as soon as the new system reaches 100% traffic.

Keep the previous path behind a feature flag until the replacement has survived normal traffic, peak traffic, deployments, and provider failures.

Define rollback conditions before launch.

Examples:

• p99 latency exceeds target
• error rate increases
• candidate counts fall unexpectedly
• conversions decline
• event ingestion breaks
• diversity collapses
• eligibility rules are violated

Your application should also have a vendor-independent fallback.

For example:

ranking API unavailable → cached ranking → freshness/popularity ordering

A ranking failure should reduce personalization quality.

It should not take the feed offline.

When should you stay with Algolia Recommend?

Migration is not automatically the right decision.

Stay with Algolia Recommend if your primary use cases remain:

• Related Products
• Frequently Bought Together
• similar content
• trending items
• ecommerce cross-sell

and Algolia already owns most of your search, catalog, and behavioral infrastructure.

Moving to a dedicated ranking API becomes more compelling when:

• your application already generates candidates
• final ordering is strategically important
• you rank non-product objects
• retrieval and ranking need separate release cycles
• multiple surfaces need the same ranking interface
• you want tighter control over rules and observability

Final takeaway

Migrating from Algolia Recommend to a ranking API is not an endpoint swap.

It is an architectural shift from:

recommendation system generates results

to:

application generates candidates → ranking system decides order

The safest sequence is:

inventory → recover events → preserve identity → define retrieval → enforce eligibility → map signals → backfill → dual-write → shadow → A/B test → gradual cutover → rollback protection

The most important thing you carry through the migration is not the old model.

It is your behavioral history, identity mapping, eligibility rules, candidate-generation logic, and measurement framework.

Preserve those correctly, and replacing the ranking infrastructure becomes a controlled engineering project rather than a risky rewrite of your recommendation system.