Skip to main content
algolia-migration-deep-dive Migrate to Algolia from Elasticsearch, Typesense, or Meilisearch.
Covers data migration, query translation, replaceAllObjects zero-downtime swap,
and strangler fig traffic shifting.
Trigger: "migrate to algolia", "switch to algolia", "algolia migration",
"elasticsearch to algolia", "replace search engine", "algolia replatform".
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/jeremylongshore/claude-code-plugins-plus-skills --skill algolia-migration-deep-diveThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository Implement user sign-up and sign-in flows with Clerk.
Use when building authentication UI, customizing sign-in experience,
or implementing OAuth social login.
Trigger with phrases like "clerk sign-in", "clerk sign-up",
"clerk login flow", "clerk OAuth", "clerk social login".
Implement session management and middleware with Clerk.
Use when managing user sessions, configuring route protection,
or implementing token refresh and custom JWT templates.
Trigger with phrases like "clerk session", "clerk middleware",
"clerk route protection", "clerk token", "clerk JWT".
Configure enterprise SSO, role-based access control, and organization management.
Use when implementing SSO integration, configuring role-based permissions,
or setting up organization-level controls.
Trigger with phrases like "clerk SSO", "clerk RBAC",
"clerk enterprise", "clerk roles", "clerk permissions", "clerk organizations".
Related occupations SOC
Based on SOC occupation classification
name algolia-migration-deep-dive description Migrate to Algolia from Elasticsearch, Typesense, or Meilisearch.
Covers data migration, query translation, replaceAllObjects zero-downtime swap,
and strangler fig traffic shifting.
Trigger: "migrate to algolia", "switch to algolia", "algolia migration",
"elasticsearch to algolia", "replace search engine", "algolia replatform".
allowed-tools Read, Write, Edit, Bash(npm:*), Bash(node:*), Bash(curl:*) version 1.6.0 license MIT author Jeremy Longshore <jeremy@intentsolutions.io> tags ["saas","search","algolia"] compatibility Designed for Claude Code
Algolia Migration Deep Dive
Overview
Comprehensive guide for migrating from another search engine (Elasticsearch, Typesense, Meilisearch, or custom) to Algolia. Uses the strangler fig pattern: run old and new in parallel, gradually shift traffic, then cut over.
Migration Planning
From Difficulty Notes Duration Elasticsearch Medium query syntax differs significantly 2-4 weeks Typesense Low similar hosted model 1-2 weeks Meilisearch Low similar API concepts 1-2 weeks Custom SQL LIKE Low major upgrade 1-2 weeks Solr Medium config-heavy to API-driven 2-4 weeks
Instructions
Step 1: Assess Current Implementation
grep -rn "elasticsearch\|elastic\|typesense\|meilisearch\|\.search(" \
--include="*.ts" --include="*.tsx" --include="*.js" src/ | wc -l
grep -rn "aggregations\|facets\|filters\|sort\|highlight\|suggest" \
--include="*.ts" --include="*.tsx" src/
interface MigrationAssessment {
currentEngine : string ;
recordCount : number ;
indexCount : number ;
features : {
fullTextSearch : boolean ;
faceting : boolean ;
filtering : boolean
geoSearch
boolean
synonyms
boolean
customRanking
boolean
analytics
boolean
abTesting
boolean
recommendations
boolean
integrationPoints
string
queryPatterns
string
Step 2: Create the Adapter Layer
interface SearchResult <T> {
hits : T[];
totalHits : number ;
totalPages : number ;
currentPage : number ;
facets ?: Record <string , Record <string , number >>;
processingTimeMs : number ;
}
interface SearchAdapter {
search<T>(params : {
index : string ;
query : string ;
filters ?: string ;
facets ?: string [];
page ?: number ;
hitsPerPage ?: number ;
}): Promise <SearchResult <T>>;
index (params : { index : string ; records : Record <string , any >[] }): Promise <void >;
delete (params : { index : string ; ids : string [] }): Promise <void >;
}
Step 3: Implement the Algolia Adapter
import { algoliasearch, ApiError } from 'algoliasearch' ;
export class AlgoliaAdapter implements SearchAdapter {
private client;
constructor (appId : string , apiKey : string this .client = algoliasearch (appId, apiKey);
}
async search<T>(params : {
index : string ;
query : string ;
filters ?: string ;
facets ?: string [];
page ?: number ;
hitsPerPage ?: number ;
}): Promise <SearchResult <T>> {
const result = await this .client .searchSingleIndex <T>({
indexName : params.index ,
searchParams : {
query : params.query ,
filters : params.filters ,
facets : params.facets || ['*' ],
page : params.page || 0 ,
hitsPerPage : params.hitsPerPage || 20 ,
},
});
return {
hits : result.hits ,
totalHits : result.nbHits ,
totalPages : result.nbPages ,
currentPage : result.page ,
facets : result.facets ,
processingTimeMs : result.processingTimeMS ,
};
}
async index (params : { index: string ; records: Record<string , any >[] }const { taskID } = await this .client .saveObjects ({
indexName : params.index ,
objects : params.records .map (r =>objectID : r.id || r.objectID ,
...r,
})),
});
await this .client .waitForTask ({ indexName : params.index , taskID });
}
async delete (params : { index: string ; ids: string [] }const { taskID } = await this .client .deleteObjects ({
indexName : params.index ,
objectIDs : params.ids ,
});
await this .client .waitForTask ({ indexName : params.index , taskID });
}
}
Step 4: Query Translation Guide
await client.searchSingleIndex ({ indexName : 'products' , searchParams : { query : 'laptop' } });
await client.searchSingleIndex ({
indexName : 'products' ,
searchParams : { query : '' , filters : 'category:electronics' },
});
await client.searchSingleIndex ({
indexName : 'products' ,
searchParams : { query : '' , numericFilters : ['price >= 50' , 'price <= 200' ] },
});
await client.searchSingleIndex ({
indexName : 'products' ,
searchParams : { query : '' , facets : ['category' ] },
});
await client.searchSingleIndex ({ indexName : 'products_price_asc' , searchParams : { query : '' } });
Step 5: Data Migration
async function migrateData (sourceAdapter : SearchAdapter , targetIndex : string const client = algoliasearch (process.env .ALGOLIA_APP_ID !, process.env .ALGOLIA_ADMIN_KEY !);
console .log (`Starting migration to ${targetIndex} ...` );
const allRecords : Record <string , any >[] = [];
let page = 0 ;
let hasMore = true ;
while (hasMore) {
const result = await sourceAdapter.search ({
index : 'products' ,
query : '' ,
page,
hitsPerPage : 1000 ,
});
allRecords.push (...result.hits .map (transformRecord));
hasMore = page < result.totalPages - 1 ;
page++;
console .log (`Exported ${allRecords.length} records...` );
}
const { taskID } = await client.replaceAllObjects ({
indexName : targetIndex,
objects : allRecords,
batchSize : 1000 ,
});
await client.waitForTask ({ indexName : targetIndex, taskID });
console .log (`Migration complete: ${allRecords.length} records in ${targetIndex} ` );
}
function transformRecord (record : any Record <string , any > {
return {
objectID : record.id || record._id ,
...record,
_id : undefined ,
_source : undefined ,
_score : undefined ,
};
}
Step 6: Traffic Shifting (Strangler Fig)
function getSearchAdapter (SearchAdapter {
const algoliaPercent = parseInt (process.env .ALGOLIA_TRAFFIC_PERCENT || '0' );
if (Math .random () * 100 < algoliaPercent) {
return new AlgoliaAdapter (process.env .ALGOLIA_APP_ID !, process.env .ALGOLIA_ADMIN_KEY !);
}
return new ElasticsearchAdapter (process.env .ES_URL !);
}
Step 7: Validation
async function validateMigration (queries : string []const old = new ElasticsearchAdapter (process.env .ES_URL !);
const algolia = new AlgoliaAdapter (process.env .ALGOLIA_APP_ID !, process.env .ALGOLIA_ADMIN_KEY !);
for (const query of queries) {
const oldResult = await old.search ({ index : 'products' , query });
const algoliaResult = await algolia.search ({ index : 'products' , query });
const oldIds = new Set (oldResult.hits .map ((h : any h.objectID || h.id ));
const algoliaIds = new Set (algoliaResult.hits .map ((h : any h.objectID ));
const overlap = [...algoliaIds].filter (id =>has (id)).length ;
const overlapPct = (overlap / Math .max (oldIds.size , 1 ) * 100 ).toFixed (0 );
console .log (`"${query} ": old=${oldResult.totalHits} , algolia=${algoliaResult.totalHits} , overlap=${overlapPct} %` );
}
}
Rollback Plan
export ALGOLIA_TRAFFIC_PERCENT=0
Error Handling Issue Cause Solution Result mismatch Different ranking algorithms Tune customRanking and searchableAttributes Missing records Transform dropped fields Add logging to transform, validate counts Higher latency Cold Algolia index Search a few times to warm cache, then benchmark Filter syntax errors Elasticsearch query DSL ≠ Algolia filters Use translation guide above
Resources
Next Steps Migration complete. See algolia-prod-checklist for go-live preparation.
