AACsearch
Migration Guides

Migrating from Algolia

Step-by-step guide to migrate your search from Algolia to AACsearch Engine — index migration, API key porting, and widget replacement.

Migrating from Algolia

This guide walks you through migrating your search infrastructure from Algolia to AACsearch Engine. The process is designed for minimal downtime and can be completed in a few hours for most setups.

Migration overview

StepWhat you doDuration
1Export your Algolia index~5 minutes
2Create an AACsearch index~5 minutes
3Import data~10 minutes
4Configure settings (facets, synonyms, ranking)~15 minutes
5Update API keys~10 minutes
6Update your frontend~30 minutes
7Switch DNS / endpoints~5 minutes

Step 1: Export your Algolia index

Use the Algolia CLI or API to export your index data:

# Install Algolia CLI
npm install -g algolia-cli

# Export index to JSON
algolia export \
  --app-id YOUR_ALGOLIA_APP_ID \
  --api-key YOUR_ADMIN_API_KEY \
  --index-name your_index_name \
  --output ./algolia-export.json

Alternatively, use the Algolia API directly:

curl "https://YOUR_APP_ID.algolia.net/1/indexes/YOUR_INDEX_NAME/browse" \
  -H "X-Algolia-API-Key: YOUR_ADMIN_API_KEY" \
  -H "X-Algolia-Application-Id: YOUR_APP_ID" \
  | jq '.hits' > algolia-export.json

Step 2: Create an AACsearch index

In the AACsearch dashboard or via API:

curl -X POST "https://app.aacsearch.com/api/projects/YOUR_PROJECT_ID/indexes" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "your_index",
    "displayName": "Your Index",
    "fields": [
      {"name": "objectID", "type": "string"},
      {"name": "title", "type": "string"},
      {"name": "description", "type": "string"},
      {"name": "price", "type": "float", "sort": true},
      {"name": "category", "type": "string", "facet": true},
      {"name": "brand", "type": "string", "facet": true},
      {"name": "tags", "type": "string[]", "facet": true}
    ],
    "defaultSortingField": "price"
  }'

Field mapping tip: Map objectID → id or external_id. AACsearch uses id as the primary key for upserts and deletes. If your Algolia records use objectID, include an id field in your export or map it during import.

Step 3: Import data

# Transform objectID to id
cat algolia-export.json | jq '[.[] | {id: .objectID, title, description, price, category, brand, tags}]' > import-data.json

# Batch import
curl -X POST "https://app.aacsearch.com/api/indexes/YOUR_INDEX_ID/documents:batch" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d @import-data.json

Step 4: Configure settings

Facets

Map your Algolia attributesForFaceting to AACsearch facet: true fields. AACsearch supports the same facet types:

AlgoliaAACsearchNotes
searchable(attribute)type: "string", facet: trueFilter-only facet
filterOnly(attribute)type: "string", facet: true, filterOnly: trueNo facet count returned
Hierarchicaltype: "string[]"Use array fields for hierarchy

Synonyms

Export Algolia synonyms and import them to AACsearch:

# Export Algolia synonyms
curl "https://YOUR_APP_ID.algolia.net/1/indexes/YOUR_INDEX_NAME/synonyms" \
  -H "X-Algolia-API-Key: YOUR_ADMIN_API_KEY" \
  -H "X-Algolia-Application-Id: YOUR_APP_ID" \
  | jq '.hits' > algolia-synonyms.json

# Convert to AACsearch format (one-way synonyms)
cat algolia-synonyms.json | jq '[.[] | select(.type == "synonym") | {root: .word, synonyms: (.synonyms // [])}]' > aacsearch-synonyms.json

# Import
curl -X PUT "https://app.aacsearch.com/api/indexes/YOUR_INDEX_ID/synonyms" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d @aacsearch-synonyms.json

Ranking

AACsearch's default ranking (Typo → Proximity → TextMatch → Custom) is comparable to Algolia's default ranking strategy. To replicate custom ranking:

curl -X PATCH "https://app.aacsearch.com/api/indexes/YOUR_INDEX_ID" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ranking": {
      "textMatchWeight": 3,
      "proximityWeight": 2,
      "typoWeight": 1,
      "fieldWeights": {"title": 5, "description": 2}
    }
  }'

Step 5: Update API keys

Create new API keys in the AACsearch dashboard:

  • Admin key (aa_admin_*) — full CRUD access, for backend services
  • Search key (ss_search_*) — search-only access, safe for browser use
  • Scoped tokens (ss_scoped_*) — restricted to specific index and filters

Replace your Algolia search-only API key with an AACsearch ss_search_* key in your frontend.

Step 6: Update your frontend

Replace the InstantSearch client

Before (Algolia):

<script src="https://cdn.jsdelivr.net/npm/algoliasearch@4/dist/algoliasearch-lite.umd.js"></script>
<script>
	const searchClient = algoliasearch("APP_ID", "SEARCH_KEY");
	// ...
</script>

After (AACsearch Engine):

<script src="https://cdn.aacsearch.com/widget/v1/widget.js"></script>
<script>
	const search = new AacsearchWidget.Search({
		baseUrl: "https://app.aacsearch.com",
		apiKey: "ss_search_YOUR_KEY",
		indexSlug: "your_index",
	});
</script>

Query translation reference

AlgoliaAACsearch
index.search(query, { filters })client.search({ q: query, filterBy: filters })
index.search(query, { facetFilters })client.search({ q: query, filterBy: filters, facetBy: attributes })
index.search(query, { hitsPerPage })client.search({ q: query, perPage: n })
index.search(query, { page })client.search({ q: query, page: n })
index.search(query, { attributesToRetrieve })— all fields returned by default; use includeFields to limit
index.search(query, { sort })client.search({ q: query, sortBy: "field:asc" })
index.searchForFacetValues(...)client.search({ q: query, facetBy: "field", maxFacetValues: n })

Step 7: Switch DNS / endpoints

Once you've verified everything works:

  1. Update your backend services to point to https://app.aacsearch.com (or your EU/RU node)
  2. Update your frontend widget to use the AACsearch endpoint
  3. Keep your Algolia index as a backup during the transition period
  4. Verify search results match expectations
  5. Decommission Algolia (or keep as cold standby)

Rollback plan

If something goes wrong during migration:

  1. Revert your frontend to the Algolia client
  2. Keep both indexes in sync during the transition
  3. Re-run the import if data is incomplete

API equivalence reference

FeatureAlgoliaAACsearch
Searchindex.search()POST /api/v1/indexes/:slug/search
Multi-searchmultipleQueries()POST /api/v1/multi-search
FacetingattributesForFacetingField facet: true in schema
SynonymssaveSynonym()PUT /api/indexes/:id/synonyms
Curations (Rules)saveRule()PUT /api/indexes/:id/curations
Typo tolerancetypoTolerancetypoTolerance in index config
AnalyticsgetAnalytics()GET /api/projects/:id/analytics
API keysapiKey / securedApiKeyAdmin/Search/Scoped token model

Need help?

From database search (SQL LIKE / FTS)

Migrating from `LIKE %query%`, MySQL fulltext, PostgreSQL `tsvector`, or any other database-native search to AACsearch.

Migrating from Elasticsearch

Step-by-step guide to migrate your search from Elasticsearch to AACsearch Engine — index mapping, reindexing, and query translation.

On this page

Migrating from AlgoliaMigration overviewStep 1: Export your Algolia indexStep 2: Create an AACsearch indexStep 3: Import dataStep 4: Configure settingsFacetsSynonymsRankingStep 5: Update API keysStep 6: Update your frontendReplace the InstantSearch clientQuery translation referenceStep 7: Switch DNS / endpointsRollback planAPI equivalence referenceNeed help?