Upgrade the JavaScript API client to version 4

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.

Command line

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.

Command line

npm uninstall @types/algoliasearch

Import `algoliasearch` using ES modules

Potential impact: 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: 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: 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: 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: 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: 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: 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: 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. 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: 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. Consider using deleteBy instead.

The `ttAdapter` method

Potential impact: low The ttAdapter method is no longer available. If you want to use this feature, 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.

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

​Recommendation renamed to Personalization (4.10.2)

​Upgrade from version 3 to version 4

​Import algoliasearch using ES modules

​Internet Explorer

​Asynchronous methods and callbacks

​Compatibility with the Algolia search helper and InstantSearch

​AngularJS, jQuery, and React Native builds

​The search client

​The timeout parameter

​The protocol parameter

​The hosts parameter

​The _useCache parameter

​The clearCache method

​The destroy method

​The setRequestTimeout, setTimeouts, and getTimeouts methods

​The setExtraHeader, getExtraHeader, and unsetExtraHeader methods

​The setUserToken method

​The updateApiKey method

​The addUserKeyWithValidity method

​The assignUserID method

​The assignUserIDs method

​The getUserID method

​The removeUserID method

​The searchUserIDs method

​The generateSecuredApiKey method

​The enableRateLimitForward and disableRateLimitForward methods

​Renamed methods

​The search index

​The search method

​The searchForFacetValues method

​The getObject, and getObjects methods

​The addObject and addObjects methods

​The partialUpdateObject and partialUpdateObjects methods

​The browse and browseFrom methods

​The deleteByQuery method

​The ttAdapter method

​Renamed methods

​The usage of gzip

Upgrade from version 4.x to the latest version 4

Recommendation renamed to Personalization (4.10.2)

Upgrade from version 3 to version 4

Import `algoliasearch` using ES modules

Internet Explorer

Asynchronous methods and callbacks

Compatibility with the Algolia search helper and InstantSearch

AngularJS, jQuery, and React Native builds

The search client

The `timeout` parameter

The `protocol` parameter

The `hosts` parameter

The `_useCache` parameter

The `clearCache` method

The `destroy` method

The `setRequestTimeout`, `setTimeouts`, and `getTimeouts` methods

The `setExtraHeader`, `getExtraHeader`, and `unsetExtraHeader` methods

The `setUserToken` method

The `updateApiKey` method

The `addUserKeyWithValidity` method

The `assignUserID` method

The `assignUserIDs` method

The `getUserID` method

The `removeUserID` method

The `searchUserIDs` method

The `generateSecuredApiKey` method

The `enableRateLimitForward` and `disableRateLimitForward` methods

Renamed methods

The search index

The `search` method

The `searchForFacetValues` method

The `getObject`, and `getObjects` methods

The `addObject` and `addObjects` methods

The `partialUpdateObject` and `partialUpdateObjects` methods

The `browse` and `browseFrom` methods

The `deleteByQuery` method

The `ttAdapter` method

Renamed methods

The usage of `gzip`