Skip to main content
The latest major version of the algoliasearch package is version 5. This page helps you upgrade from version 4 and explains the breaking changes you need to address. Algolia generates the version 5 clients from OpenAPI specifications, which provides consistent behavior across all languages and up-to-date API coverage. The main architectural change is the removal of the initIndex pattern: all methods are now on the client instance directly, with indexName as a parameter. For the full list of changes, see the JavaScript changelog.

​
Update your dependencies

Update the algoliasearch package to version 5: 
npm install algoliasearch@5
If you’re using a search-only build (lite client), the package name stays the same. Only the import path changes (see Update imports).

​
Update imports

The import style changed from a default export to a named export.
JavaScript
// version 4
import algoliasearch from "algoliasearch";

// version 5
import { algoliasearch } from "algoliasearch";
If you’re using the lite client (search only), the import also changed:
JavaScript
// version 4
import algoliasearch from "algoliasearch/lite";

// version 5
import { liteClient as algoliasearch } from "algoliasearch/lite";
Version 5 also includes dedicated packages for each API. If you only need to access methods from a specific API, you can install and import them separately:
JavaScript
// Search API
import { searchClient } from "@algolia/client-search";
// Recommend API
import { recommendClient } from "@algolia/recommend";
// A/B testing API
import { abtestingClient } from "@algolia/client-abtesting";
// Analytics API
import { analyticsClient } from "@algolia/client-analytics";
// Personalization API
import { personalizationClient } from "@algolia/client-personalization";
// Query Suggestions API
import { querySuggestionsClient } from "@algolia/client-query-suggestions";

​
Update client initialization

Client creation is unchanged. The constructor still accepts your application ID and API key:
JavaScript
// version 4
const client = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

// version 5
const client = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");
The other major change concerns what follows initialization: initIndex no longer exists.

​
Remove initIndex

This is the most significant change when upgrading. Version 4 relied on an index object with methods called on it. In version 5, all methods belong to the client instance, with indexName as a parameter.
JavaScript
// version 4
const client = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");
const index = client.initIndex("ALGOLIA_INDEX_NAME");
const results = index.search("QUERY");

// version 5
const client = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");
const results = await client.searchSingleIndex({
  indexName: "ALGOLIA_INDEX_NAME",
  searchParams: { query: "QUERY" },
});
If you have many files to update, search your codebase for initIndex or .initIndex( to find every place that needs changing.

​
Update search calls

​
Search a single index

The index.search() method is now client.searchSingleIndex(). Pass the index name and search parameters as an object:
JavaScript
// version 4
const index = client.initIndex("ALGOLIA_INDEX_NAME");
const { hits } = await index.search("QUERY", {
  facetFilters: ["category:Book"],
});

// version 5
const { hits } = await client.searchSingleIndex({
  indexName: "ALGOLIA_INDEX_NAME",
  searchParams: {
    query: "QUERY",
    facetFilters: ["category:Book"],
  },
});

​
Search multiple indices

The client.multipleQueries() method is now client.search(). Each request in the array requires an indexName:
JavaScript
// version 4
const { results } = await client.multipleQueries([
  { indexName: "INDEX_1", query: "QUERY" },
  { indexName: "INDEX_2", query: "QUERY" },
]);

// In version 4, you could also use:
// const { results } = await client.search([...]);
// which is equivalent to multipleQueries.

// version 5
const { results } = await client.search({
  requests: [
    { indexName: "INDEX_1", query: "QUERY" },
    { indexName: "INDEX_2", query: "QUERY" },
  ],
});

​
Search for facet values

The index.searchForFacetValues() method becomes client.searchForFacetValues() with an indexName parameter:
JavaScript
// version 4
const index = client.initIndex("ALGOLIA_INDEX_NAME");
const results = await index.searchForFacetValues("category", "book");

// version 5
const results = await client.searchForFacetValues({
  indexName: "ALGOLIA_INDEX_NAME",
  facetName: "category",
  searchForFacetValuesRequest: { facetQuery: "book" },
});

​
Update indexing operations

In version 5, indexing methods are on the client instead of the index object, with indexName as a parameter.

​
Add or replace records

JavaScript
// version 4
const index = client.initIndex("ALGOLIA_INDEX_NAME");
await index.saveObject({ objectID: "1", name: "Record" });
await index.saveObjects([{ objectID: "1", name: "Record" }]);

// version 5
const { taskID } = await client.saveObject({
  indexName: "ALGOLIA_INDEX_NAME",
  body: { objectID: "1", name: "Record" },
});
// saveObjects works the same way:
// (note: `objects` instead of `body` for the batch version)
const { taskID } = await client.saveObjects({
  indexName: "ALGOLIA_INDEX_NAME",
  objects: [{ objectID: "1", name: "Record" }],
});

​
Partially update records

JavaScript
// version 4
const index = client.initIndex("ALGOLIA_INDEX_NAME");
await index.partialUpdateObject({ objectID: "1", name: "Updated" });

// version 5
await client.partialUpdateObject({
  indexName: "ALGOLIA_INDEX_NAME",
  objectID: "1",
  attributesToUpdate: { name: "Updated" },
});

​
Delete records

JavaScript
// version 4
const index = client.initIndex("ALGOLIA_INDEX_NAME");
await index.deleteObject("1");

// version 5
await client.deleteObject({
  indexName: "ALGOLIA_INDEX_NAME",
  objectID: "1",
});

​
Update settings, synonyms, and rules

​
Get and set settings

JavaScript
// version 4
const index = client.initIndex("ALGOLIA_INDEX_NAME");
const settings = await index.getSettings();
await index.setSettings({ searchableAttributes: ["title", "author"] });

// version 5
const settings = await client.getSettings({
  indexName: "ALGOLIA_INDEX_NAME",
});
await client.setSettings({
  indexName: "ALGOLIA_INDEX_NAME",
  indexSettings: { searchableAttributes: ["title", "author"] },
});

​
Save synonyms and rules

JavaScript
// version 4
const index = client.initIndex("ALGOLIA_INDEX_NAME");
await index.saveSynonyms([{ objectID: "1", type: "synonym", synonyms: ["car", "auto"] }]);
await index.saveRules([{ objectID: "1", conditions: [{ anchoring: "contains", pattern: "shoes" }], consequence: { params: { query: "sneakers" } } }]);

// version 5
await client.saveSynonyms({
  indexName: "ALGOLIA_INDEX_NAME",
  synonymHit: [{ objectID: "1", type: "synonym", synonyms: ["car", "auto"] }],
});
await client.saveRules({
  indexName: "ALGOLIA_INDEX_NAME",
  rules: [{ objectID: "1", conditions: [{ anchoring: "contains", pattern: "shoes" }], consequence: { params: { query: "sneakers" } } }],
});
In version 4, index.replaceAllRules() and index.replaceAllSynonyms() replaced all rules or synonyms. In version 5, use client.saveRules() or client.saveSynonyms() with the clearExistingRules or clearExistingSynonyms parameter set to true.

​
Update index management

The copyIndex, moveIndex, copyRules, copySynonyms, and copySettings methods are all replaced by a single operationIndex method.

​
Copy an index

JavaScript
// version 4
await client.copyIndex("SOURCE_INDEX_NAME", "DESTINATION_INDEX_NAME");

// version 5
await client.operationIndex({
  indexName: "SOURCE_INDEX_NAME",
  operationIndexParams: { operation: "copy", destination: "DESTINATION_INDEX_NAME" },
});

​
Move (rename) an index

JavaScript
// version 4
await client.moveIndex("SOURCE_INDEX_NAME", "DESTINATION_INDEX_NAME");

// version 5
await client.operationIndex({
  indexName: "SOURCE_INDEX_NAME",
  operationIndexParams: { operation: "move", destination: "DESTINATION_INDEX_NAME" },
});

​
Copy only rules or settings

In version 5, use the scope parameter to limit the operation to specific data:
JavaScript
// version 5 -- copy only rules and settings from one index to another
await client.operationIndex({
  indexName: "SOURCE_INDEX_NAME",
  operationIndexParams: {
    operation: "copy",
    destination: "DESTINATION_INDEX_NAME",
    scope: ["rules", "settings"],
  },
});

​
Update task handling

Version 4 supported chaining .wait() on operations. Version 5 replaces this pattern with dedicated wait helpers.
JavaScript
// version 4
const index = client.initIndex("ALGOLIA_INDEX_NAME");
await index.saveObjects(records).wait();

// version 5
const { taskID } = await client.saveObjects({
  indexName: "ALGOLIA_INDEX_NAME",
  objects: records,
});
await client.waitForTask({ indexName: "ALGOLIA_INDEX_NAME", taskID });
Version 5 includes three wait helpers:

​
Method changes reference

The following tables list all method names that changed between version 4 and version 5.

​
Search API client

Version 4 (legacy)Version 5 (current)
client.addApiKey→client.addApiKey
client.addApiKey.wait→client.waitForApiKey
client.clearDictionaryEntries→client.batchDictionaryEntries
client.copyIndex→client.operationIndex
client.copyRules→client.operationIndex
client.copySynonyms→client.operationIndex
client.deleteApiKey→client.deleteApiKey
client.deleteDictionaryEntries→client.batchDictionaryEntries
client.generateSecuredApiKey→client.generateSecuredApiKey
client.getApiKey→client.getApiKey
client.getSecuredApiKeyRemainingValidity→client.getSecuredApiKeyRemainingValidity
client.listApiKeys→client.listApiKeys
client.listIndices→client.listIndices
client.moveIndex→client.operationIndex
client.multipleBatch→client.multipleBatch
client.multipleQueries→client.search
client.replaceDictionaryEntries→client.batchDictionaryEntries
client.restoreApiKey→client.restoreApiKey
client.saveDictionaryEntries→client.batchDictionaryEntries
client.updateApiKey→client.updateApiKey
index.batch→client.batch
index.browseObjects→client.browseObjects
index.browseRules→client.browseRules
index.browseSynonyms→client.browseSynonyms
index.clearObjects→client.clearObjects
index.clearRules→client.clearRules
index.clearSynonyms→client.clearSynonyms
index.copySettings→client.operationIndex
index.delete→client.deleteIndex
index.deleteBy→client.deleteBy
index.deleteObject→client.deleteObject
index.deleteObjects→client.deleteObjects
index.deleteRule→client.deleteRule
index.deleteSynonym→client.deleteSynonym
index.findObject→client.searchSingleIndex
index.getObject→client.getObject
index.getObjects→client.getObjects
index.getRule→client.getRule
index.getSettings→client.getSettings
index.getSynonym→client.getSynonym
index.getTask→client.getTask
index.partialUpdateObject→client.partialUpdateObject
index.partialUpdateObjects→client.partialUpdateObjects
index.replaceAllObjects→client.replaceAllObjects
index.replaceAllRules→client.saveRules
index.replaceAllSynonyms→client.saveSynonyms
index.saveObject→client.saveObject
index.saveObjects→client.saveObjects
index.saveRule→client.saveRule
index.saveRules→client.saveRules
index.saveSynonym→client.saveSynonym
index.saveSynonyms→client.saveSynonyms
index.search→client.searchSingleIndex
index.searchForFacetValues→client.searchForFacetValues
index.searchRules→client.searchRules
index.searchSynonyms→client.searchSynonyms
index.setSettings→client.setSettings
index.{operation}.wait→client.waitForTask

​
Recommend API client

Version 4 (legacy)Version 5 (current)
client.getFrequentlyBoughtTogether→client.getRecommendations
client.getLookingSimilar→client.getRecommendations
client.getRecommendations→client.getRecommendations
client.getRelatedProducts→client.getRecommendations
client.getTrendingFacets→client.getRecommendations
client.getTrendingItems→client.getRecommendations
Last modified on March 2, 2026