Skip to main content
This page documents an earlier version of the API client. For the latest version, see Upgrade.
The JavaScript API client follows semantic versioning.

​
Upgrade from version 4.x to the latest version 4

​
Recommendation renamed to Personalization (4.10.2)

To avoid confusion with the Algolia Recommend product, the existing “recommendation” client and methods have been renamed to personalization.
  • @algolia/client-recommendation → @algolia/client-personalization
  • initRecommendation() → initPersonalization()
  • initRecommendation().getPersonalizationStrategy → initPersonalization().getPersonalizationStrategy
  • initRecommendation().setPersonalizationStrategy → initPersonalization().setPersonalizationStrategy

​
Upgrade from version 3 to version 4

This document lists every known breaking change. Not all these changes may affect your application, since some of these breaking changes happen in obscure parts of the client.
The amount of changes in this new version is significant. You should thoroughly test your application once the migration is over.
To get started, update algoliasearch to ^4.0.0. 
npm install algoliasearch@"^4.0.0"
The client now natively supports TypeScript. If you’re using it in a TypeScript project, you no longer need the @types/algoliasearch package. 
npm uninstall @types/algoliasearch

​
Import algoliasearch using ES modules

Potential impact: very high Importing the algoliasearch function with the wildcard (*) is no longer possible. You must import algoliasearch from the default export.
JavaScript
// v3
import * as algoliasearch from "algoliasearch/lite";
import * as algoliasearch from "algoliasearch";

// v4
import algoliasearch from "algoliasearch/lite";
import algoliasearch from "algoliasearch";

​
Internet Explorer

Potential impact: very high If you’re using algoliasearch in the browser, keep in mind that the version 4 doesn’t support Internet Explorer below version 11. You also need to use polyfills for older browsers that don’t support Promise, Object.entries, and Object.assign.

​
Asynchronous methods and callbacks

Potential impact: very high In the v3, all asynchronous methods took a callback function. In the v4, you can no longer pass a callback. All asynchronous methods are now exclusively Promise-based:
JavaScript
// v3
index.search("query string", (err, { hits } = {}) => {
  if (err) throw err;

  console.log(hits);
});

// v4
index.search("query string").then(({ hits }) => {
  console.log(hits);
});
The preceding example applies to all asynchronous methods that used to take a callback.

​
Compatibility with the Algolia search helper and InstantSearch

Potential impact: very high If you’re using any of the projects in the list below, you may need to update them to the specified versions. All tests on version 4 apply to these versions. Other versions may not work.
  • algoliasearch-helper-js: >= 2.28.1
  • algoliasearch-helper-js: >= 3.1.0
  • instantsearch.js: >= 4.2.0
  • react-instantsearch: >= 6.3.0
  • vue-instantsearch: >= 2.7.0
You also need to add polyfills for: Promise, Object.entries, and Object.assign. Angular InstantSearch isn’t compatible with algoliasearch version 4. If you’re using Angular InstantSearch, keep using algoliasearch version 3.

​
AngularJS, jQuery, and React Native builds

Potential impact: medium The following builds are no longer available:
  • dist/algoliasearch.angular.js
  • dist/algoliasearch.jquery.js
  • algoliasearch.reactnative.js
Use the dist/algoliasearch.umd.js build directly.

​
The search client

The following sections present the migration guide for the search client itself. The client is the object that the algoliasearch function returns.
JavaScript
const client = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

​
The timeout parameter

Potential impact: low The timeout parameter is no longer available, here is the alternative:
JavaScript
// v3
const client = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", {
  timeout: 2,
});

// v4
const client = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", {
  timeouts: {
    connect: 1,
    read: 2, // The value of the former `timeout` parameter
    write: 30,
  },
});

​
The protocol parameter

Potential impact: very low The parameter is no longer available, here is the alternative:
JavaScript
// v3
const client = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", {
  protocol: "http",
});

// v4
import { CallEnum } from "@algolia/transporter";

const client = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", {
  hosts: [
    {
      protocol: "http", // or 'https'
      url: "domain.com",
      accept: CallEnum.Any, // CallEnum.Read or CallEnum.Write
    },
  ],
});

​
The hosts parameter

Potential impact: very low The parameter has changed, here is the alternative:
JavaScript
// v3
const client = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", {
  hosts: { read: ["domain.com"] },
});

// v4
import { CallEnum } from "@algolia/transporter";

const client = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", {
  hosts: [
    {
      protocol: "https", // or 'http'
      url: "domain.com",
      accept: CallEnum.Read, // CallEnum.Any or CallEnum.Write
    },
  ],
});

​
The _useCache parameter

Potential impact: low The parameter is no longer available, here is the alternative:
JavaScript
// v3
const client = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", {
  _useCache: false,
});

// v4
import { createNullCache } from "@algolia/cache-common";

const client = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", {
  responsesCache: createNullCache(),
});

​
The clearCache method

Potential impact: very low The clearCache method is now asynchronous. Make sure to adapt your code to wait on the promise resolution if you have dependencies.
JavaScript
// v3
client.clearCache();

// v4
client.clearCache().then(() => {
  // ...
});

​
The destroy method

Potential impact: low The destroy method is now asynchronous.
JavaScript
// v3
client.destroy();

// v4
client.destroy().then(() => {
  // ...
});

​
The setRequestTimeout, setTimeouts, and getTimeouts methods

Potential impact: low The setRequestTimeout, setTimeouts, and getTimeouts methods are no longer available. Here is the alternative:
JavaScript
// v4
const client = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", {
  timeouts: {
    connect: 1,
    read: 2,
    write: 30,
  },
});

​
The setExtraHeader, getExtraHeader, and unsetExtraHeader methods

Potential impact: medium The setExtraHeader, getExtraHeader, and unsetExtraHeader methods are no longer available.
JavaScript
// v3
client.setExtraHeader("key", "value");
client.getExtraHeader("key");
client.unsetExtraHeader("key");

// v4

// For every request
const client = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", {
  headers: {
    key: "value",
  },
});

// For for a single request
index
  .search("query", {
    headers: {
      key: "value",
    },
  })
  .then(({ hits }) => {
    console.log(hits);
  });

​
The setUserToken method

Potential impact: very low The method is no longer available, here is the alternative:
JavaScript
// v3
client.setUserToken("userToken");

// v4
const client = algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", {
  headers: {
    "x-algolia-usertoken": "userToken",
  },
});

// or
index
  .search("query", {
    headers: {
      "x-algolia-usertoken": "value",
    },
  })
  .then(({ hits }) => {
    console.log(hits);
  });

​
The updateApiKey method

Potential impact: low The updateApiKey method signature has changed.
JavaScript
// v3
client.updateApiKey("key", ["search"]);

// v4
client.updateApiKey("key", {
  acl: ["search"],
  // All remaining key updates below
});

​
The addUserKeyWithValidity method

Potential impact: low The addUserKeyWithValidity is removed. Please use addApiKey instead.

​
The assignUserID method

Potential impact: low The assignUserID method signature has changed.
JavaScript
// v3
client.assignUserID({
  userID: "myUserID1",
  cluster: "c1-test",
});

// v4
client.assignUserID("myUserID1", "c1-test");

​
The assignUserIDs method

Potential impact: low The assignUserIDs method signature has changed.
JavaScript
// v3
client.assignUserIDs({
  userIDs: ["myUserID1", "myUserID2", "myUserID3"],
  cluster: "c1-test",
});

// v4
client.assignUserIDs(["myUserID1", "myUserID2", "myUserID3"], "c1-test");

​
The getUserID method

Potential impact: low The getUserID method signature has changed.
JavaScript
// v3
client.getUserID({ userID: "myUserID1" });

// v4
client.getUserID("myUserID1");

​
The removeUserID method

Potential impact: low The removeUserID method signature has changed.
JavaScript
// v3
client.removeUserID({ userID: "myUserID1" });

// v4
client.removeUserID("myUserID1");

​
The searchUserIDs method

Potential impact: low The searchUserIDs method signature has changed.
JavaScript
// v3
client.searchUserIDs({ query: "query" });

// v4
client.searchUserIDs("query", {
  // Any other optional parameter
});

​
The generateSecuredApiKey method

Potential impact: low The generateSecuredApiKey method signature has changed.
JavaScript
// v3
client.generateSecuredApiKey({ apiKey: "MyApiKey" });

// v4
client.generateSecuredApiKey("MyApiKey", {
  // Any other optional parameter
});

​
The enableRateLimitForward and disableRateLimitForward methods

Potential impact: low Both enableRateLimitForward and disableRateLimitForward methods are no longer available. You can now add the X-Forwarded-For and X-Forwarded-For headers this way:
JavaScript
algoliasearch("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", {
  headers: {
    "X-Forwarded-For": "userIP",
    "X-Forwarded-For": "rateLimitApiKey",
  },
});

​
Renamed methods

Potential impact: medium The following methods don’t contain breaking changes, but either their name has changed, or they have been moved.
  • listIndexes → listIndices
  • deleteIndex → initIndex('indexName').delete()
  • batch → multipleBatch
  • sendQueriesBatch → search
  • getTopUserID → getTopUserIDs
  • setPersonalizationStrategy → initRecommendation().setPersonalizationStrategy
  • getPersonalizationStrategy → initRecommendation().getPersonalizationStrategy

​
The search index

The following sections present the migration guide for the search index, which is the object returned by the client.initIndex method.
JavaScript
const index = client.initIndex();

​
The search method

Potential impact: very high The search method signature has changed.
JavaScript
// v3
index.search({
  query: "query",
  hitsPerPage: 50,
});

// v4
index.search("query", {
  hitsPerPage: 50,
  // Any other parameter
});

​
The searchForFacetValues method

Potential impact: high The searchForFacetValues method signature has changed.
JavaScript
// v3
index.searchForFacetValues({
  facetName: "category",
  facetQuery: "phone",
  filters: "brand:apple",
});

// v4
index.searchForFacetValues("category", "phone", {
  // Any optional param
  filters: "brand:apple",
});

​
The getObject, and getObjects methods

Potential impact: low Both getObject and getObjects are no longer available on the lite build. Therefore, you need to include the full build to work with those methods. In addition, the signature has changed.
JavaScript
// v3
import algoliasearch from "algoliasearch/lite";

// ...

index.getObject("objectID", ["name"]);
index.getObjects(["objectID"], ["name"]);

// v4
import algoliasearch from "algoliasearch";

// ...

index.getObject("objectID", {
  attributesToRetrieve: ["name"],
});

index.getObjects(["objectID"], {
  attributesToRetrieve: ["name"],
});

​
The addObject and addObjects methods

Both the addObject and addObjects methods no longer exist, and are replaced with the autoGenerateObjectIDIfNotExist parameter in RequestOptions on the saveObject and saveObjects methods. Potential impact: medium
JavaScript
// v3
index.addObject({ objectID: "1", name: "star wars" });
index.addObjects([{ objectID: "1", name: "star wars" }]);

// v4
index.saveObject(
  { objectID: "1", name: "star wars" },
  { autoGenerateObjectIDIfNotExist: true },
);
index.saveObjects([{ objectID: "1", name: "star wars" }], {
  autoGenerateObjectIDIfNotExist: true,
});

​
The partialUpdateObject and partialUpdateObjects methods

In both partialUpdateObject and partialUpdateObjects, the createIfNotExists parameter should now be provided in RequestOptions. Potential impact: low
JavaScript
// v3
index.partialUpdateObject({ objectID: "1", name: "star wars" }, true);
index.partialUpdateObjects([{ objectID: "1", name: "star wars" }], true);

// v4
index.partialUpdateObject(
  { objectID: "1", name: "star wars" },
  { createIfNotExists: true },
);
index.partialUpdateObjects([{ objectID: "1", name: "star wars" }], {
  createIfNotExists: true,
});

​
The browse and browseFrom methods

Potential impact: low The browseFrom method has been removed, and the browse method is no longer available on lite builds. If you need to use browse, you need to use the full build. In addition, the signature has changed.
JavaScript
// v3
import algoliasearch from "algoliasearch/lite";

// ...

const browser = index.browseAll();
let hits = [];

browser.on("result", (content) => {
  hits = hits.concat(content.hits);
});

// v4
import algoliasearch from "algoliasearch";

// ...

let hits = [];

index
  .browseObjects({
    batch: (batch) => (hits = hits.concat(batch)),
  })
  .then(() => console.log(hits));

​
The deleteByQuery method

Potential impact: low The method deleteByQuery has been removed. Please consider using deleteBy instead.

​
The ttAdapter method

Potential impact: very low The ttAdapter method is no longer available. If you want to use this feature, please keep using v3.

​
Renamed methods

Potential impact: medium The following methods don’t contain breaking changes, but either their name has changed, or they have been moved.
  • clearIndex → clearObjects
  • batchSynonyms → saveSynonyms
  • batchRules → saveRules
  • listApiKeys → client.listApiKeys
  • addApiKey → client.addApiKey
  • updateApiKey → client.updateApiKey
  • deleteApiKey → client.deleteApiKey
  • getApiKey → client.getApiKey

​
The usage of gzip

Potential impact: low The previous version of the CommonJS build accepted gzip content from the Algolia API. This feature isn’t available on version 4.
⌘I