The generated API clients are a work in progress, you can also find our stable clients on the Algolia documentation.

Skip to main content

Migration guide

warning

The amount of changes in this new version is significant. If you were using a version older than v4, please also read this migration guide.

You should thoroughly test your application before deploying to production.

This document lists every known breaking change, not all of them may affect your application.

Common breaking changes​

The changes below are effective on all of the API clients.

initIndex​

Methods previously available at the initIndex level are now available at the root level of the API client.

The indexName parameter is now required when calling those methods.

import { searchClient } from '@algolia/client-search';

const client = searchClient('YOUR_APP_ID', 'YOUR_API_KEY');
const response = await client.search({
  requests: [
    {
      indexName: '<YOUR_INDEX_NAME>',
      query: '<YOUR_QUERY>',
      hitsPerPage: 50,
    },
  ],
});

// use typed response
console.log(response);

A/B testing client​

The A/B testing methods were previously available under the Analytics client, we’ve decided to make a client out of it to split concerns.

The Abtesting client now hosts all of the A/B testing related methods.

import { abtestingClient } from '@algolia/client-abtesting';

const client = abtestingClient(

const response = await client.getABTest({ id: 42 });

// use typed response
console.log(response);

wait​

The chainable wait method that was available on a few methods has been replaced with an helper called waitForTask.

You can now optionally configure how the wait logic behaves by passing the taskID returned when calling the Algolia API.

Read more in our dedicated guide

import { searchClient } from '@algolia/client-search';

const client = searchClient('YOUR_APP_ID', 'YOUR_API_KEY');

const response = await client.saveObject({
  indexName: '<YOUR_INDEX_NAME>',
  body: { objectID: 'id', test: 'val' },
});

// use typed response
console.log(response);

await client.waitForTask({ indexName: '<YOUR_INDEX_NAME>', taskID: response.taskID });

moveIndex/copyIndex​

The operationIndex allows you to either copy or move a source index to a destination index within the same Algolia application.

You can also decide what scope of the source index should be copied, read more in our dedicated guide.

This method can be used as a replacement for the copyRules, copySynonyms, and copySettings method when using the associated scope.

import { searchClient } from '@algolia/client-search';

const client = searchClient('YOUR_APP_ID', 'YOUR_API_KEY');

const response = await client.operationIndex({
  indexName: '<SOURCE_INDEX_NAME>',
  operationIndexParams: {
    operation: 'move',
    destination: '<DESTINATION_INDEX_NAME>',
    scope: ['rules', 'settings'],
  },
});

// use typed response
console.log(response);

await client.waitForTask({ indexName: '<SOURCE_INDEX_NAME>', taskID: response.taskID });

saveObjects​

The saveObjects method has been removed, you can leverage the already existing batch method instead.

Read more in our dedicated guide or the API reference.

import { searchClient } from '@algolia/client-search';

const client = searchClient('YOUR_APP_ID', 'YOUR_API_KEY');

const response = await client.batch({
  indexName: '<YOUR_INDEX_NAME>',
  batchWriteParams: {
    requests: [
      { action: 'addObject', body: { key: 'bar', foo: '1' } },
      { action: 'addObject', body: { key: 'baz', foo: '2' } },
    ],
  },
});

// use typed response
console.log(response);

await client.waitForTask({ indexName: '<YOUR_INDEX_NAME>', taskID: response.taskID });

browseObjects/browseRules/browseSynonyms​

The browseObjects/browseRules/browseSynonyms signature have changed to match the general usage of the API clients.

// browse records
const records: Record<string, any> = [];

await client.browseObjects({
  // all base `browse` options are forwarded to the `browse` method
  indexName: '<YOUR_INDEX_NAME>',

  // the aggregator to execute right after the API call has been resolved
  aggregator: (response) => records.push(...response.hits),
});

console.log(records, records.length);

// browse rules
const rules: Record<string, any> = [];

await client.browseRules({
  // all base `searchRules` options are forwarded to the `searchRules` method
  indexName: '<YOUR_INDEX_NAME>',

  // the aggregator to execute right after the API call has been resolved
  aggregator: (response) => rules.push(...response.hits),
});

console.log(rules, rules.length);

// browse synonyms
const synonyms: Record<string, any> = [];

await client.browseSynonyms({
  // all base `searchSynonyms` options are forwarded to the `searchSynonyms` method
  indexName: '<YOUR_INDEX_NAME>',

  // the aggregator to execute right after the API call has been resolved
  aggregator: (response) => synonyms.push(...response.hits),
});

console.log(synonyms, synonyms.length);

Client’s specific breaking changes​

You can find specific client breaking changes in their own section: