Migrating from Algolia to Headband

Why migrate?

Four reasons we hear over and over:

1. 01

   One engine per retrieval job

   Algolia runs every workload through one engine. With Headband, catalog search can run on Meilisearch, autocomplete on Typesense, very large corpora on Elasticsearch, a search box that takes both short and long queries on Visor, and RAG or agent tool-calls on vector-tuned indexes, all with the same API, dashboard and client code. Each retrieval job gets the engine that wins it instead of one engine forced on all of them.

2. 02

   Pricing escalation

   Algolia's PAYG model is fine until you're successful, at which point your search bill grows faster than your revenue.

3. 03

   Vendor lock-in

   Algolia's API is proprietary. Once your client code is shaped around it, leaving is a project, not a switch.

4. 04

   Data sovereignty

   Your search index is a copy of your data sitting on someone else's infrastructure. Bring your own engine and the index stays in your own cluster, under your own security controls: a compliance win for some teams, and one less copy to worry about for everyone else.

Move your records first

1. Export the index from Algolia as JSON. Each record keeps its objectID.
2. Create a Headband index with objectID as its primary key, and send the records with an admin key from your machine or a server. A request body can be at most 4 MiB, so a real export goes in several requests. The import script in the docs splits the file, waits out rate limits and checks each batch.
3. Set your fields again. Searchable attributes, attributes for faceting (filterable on Headband), custom ranking, replicas (sorts), synonyms and rules do not carry over. Set them in the dashboard's Tune tab or with the settings API, as your engine takes them.
4. Leave out fields the public should not see. A search key can read every field you index.

Then swap the front end, in 3 steps

npm i @headband/react

Side-by-side: SearchBox + Hits

import algoliasearch from 'algoliasearch/lite';
import {
  InstantSearch, SearchBox, Hits
} from 'react-instantsearch';

const searchClient = algoliasearch(
  'APP_ID', 'SEARCH_KEY'
);

function App() {
  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="products"
    >
      <SearchBox />
      <Hits hitComponent={Hit} />
    </InstantSearch>
  );
}

import {
  headband,
  HeadbandProvider,
  SearchBox,
  Hits
} from '@headband/react';

const searchClient = headband(
  'https://headband.dev',
  'hb_src_YOUR_SEARCH_KEY'
);

function App() {
  return (
    <HeadbandProvider
      client={searchClient}
      index="products"
    >
      <SearchBox />
      <Hits hitComponent={Hit} />
    </HeadbandProvider>
  );
}

The Hit component can stay small, but wrapper wiring and some refinement props should be reviewed against the Headband React docs.

Feature mapping

What doesn't migrate yet

Being honest: Algolia has spent ten years building features that aren't a weekend port.

• AI Personalization

  Algolia's user-event-driven re-ranking is genuinely better than anything we ship today. On the roadmap, not shipping this quarter.

• Geo search

  Not exposed through the Headband API on any engine yet.

• Query Suggestions

  Basic version on the roadmap.

• Recommend / related items

  You can build one today with your own vectors and hybrid search on Elasticsearch or Meilisearch. A built-in version is on the roadmap.

If any of these are critical to your business right now, stay on Algolia for those features and migrate the rest. Headband is happy to be one of several layers in your stack.

Cost comparison

For a representative mid-size catalog (~500k records under 2 GB of JSON, ~2M monthly search operations):

The point isn't that we're always cheaper; for small workloads Algolia's free tier is fine. The point is the shape of the bill: Starter is $12 a month with 250,000 searches included, and past what a plan includes, searches cost between $0.01 and $0.03 per 1,000, less on bigger plans.

Next steps

• Try the Engine Shootout to feel the difference between the four engines on the same query.
• Install @headband/react and follow the getting started guide.
• Run an A/B test: assign variants and record outcomes with hosted experiments.