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

danger

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.

js
import { algoliasearch } from 'algoliasearch';
const client = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>');
const searchResults2 = await client.search({
  requests: [
    {
      indexName: '<YOUR_INDEX_NAME>',
      query: '<YOUR_QUERY>',
      attributesToRetrieve: ['firstname', 'lastname'],
      hitsPerPage: 50,
    },
  ],
});
js
import { algoliasearch } from 'algoliasearch';
const client = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>');
const searchResults2 = await client.search({
  requests: [
    {
      indexName: '<YOUR_INDEX_NAME>',
      query: '<YOUR_QUERY>',
      attributesToRetrieve: ['firstname', 'lastname'],
      hitsPerPage: 50,
    },
  ],
});

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.

Usage with the algoliasearch client

js
import { algoliasearch } from 'algoliasearch';
- const analyticsClient = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>').initAnalytics();
+ const abtestingClient = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>').initAbtesting();
const abTest = await abtestingClient.getABTest({
  id: 42,
});
js
import { algoliasearch } from 'algoliasearch';
- const analyticsClient = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>').initAnalytics();
+ const abtestingClient = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>').initAbtesting();
const abTest = await abtestingClient.getABTest({
  id: 42,
});

Usage with the client-abtesting client

js
import { abtestingClient } from '@algolia/client-abtesting';
const client = abtestingClient('<YOUR_APP_ID>', '<YOUR_API_KEY>');
const abTest = await abtestingClient.getABTest({
  id: 42,
});
js
import { abtestingClient } from '@algolia/client-abtesting';
const client = abtestingClient('<YOUR_APP_ID>', '<YOUR_API_KEY>');
const abTest = await abtestingClient.getABTest({
  id: 42,
});

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

js
import { algoliasearch } from 'algoliasearch';
const client = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>');
const { taskID } = await client.saveObject({
  indexName: '<YOUR_INDEX_NAME>',
  body: {
    title: 'My Algolia Object',
  },
});
// Poll the task status with defaults values
await client.waitForTask({ indexName: '<YOUR_INDEX_NAME>', taskID });
js
import { algoliasearch } from 'algoliasearch';
const client = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>');
const { taskID } = await client.saveObject({
  indexName: '<YOUR_INDEX_NAME>',
  body: {
    title: 'My Algolia Object',
  },
});
// Poll the task status with defaults values
await client.waitForTask({ indexName: '<YOUR_INDEX_NAME>', 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.

js
import { algoliasearch } from 'algoliasearch';
const client = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>');
const { taskID } = await client.operationIndex({
  indexName: '<SOURCE_INDEX_NAME>',
  operationIndexParams: {
    // Enum for either `copy` or `move`
    operation: 'copy', // 'move'
    destination: '<DESTINATION_INDEX_NAME>',
  },
});
// Poll the task status until it's done
await client.waitForTask({ indexName: '<SOURCE_INDEX_NAME>', taskID });
js
import { algoliasearch } from 'algoliasearch';
const client = algoliasearch('<YOUR_APP_ID>', '<YOUR_API_KEY>');
const { taskID } = await client.operationIndex({
  indexName: '<SOURCE_INDEX_NAME>',
  operationIndexParams: {
    // Enum for either `copy` or `move`
    operation: 'copy', // 'move'
    destination: '<DESTINATION_INDEX_NAME>',
  },
});
// Poll the task status until it's done
await client.waitForTask({ indexName: '<SOURCE_INDEX_NAME>', 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.

js
// The records retrieved by any of your data sources
const recordsFromDataSource = [
  { name: 'Tom Cruise' },
  { name: 'Scarlett Johansson' },
];
// Here we construct the request to be sent to Algolia with the `batch` method
const requests: BatchRequest[] = recordsFromDataSource.map((record) => {
  return {
    // `batch` allows you to do many Algolia operations, but here we want to index our record.
    action: 'addObject',
    body: record,
  };
});
await client.batch({
  indexName: '<YOUR_INDEX_NAME>',
  batchWriteParams: {
    requests,
  },
});
js
// The records retrieved by any of your data sources
const recordsFromDataSource = [
  { name: 'Tom Cruise' },
  { name: 'Scarlett Johansson' },
];
// Here we construct the request to be sent to Algolia with the `batch` method
const requests: BatchRequest[] = recordsFromDataSource.map((record) => {
  return {
    // `batch` allows you to do many Algolia operations, but here we want to index our record.
    action: 'addObject',
    body: record,
  };
});
await client.batch({
  indexName: '<YOUR_INDEX_NAME>',
  batchWriteParams: {
    requests,
  },
});

browseObjects/browseRules/browseSynonyms​

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

js
// 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);
js
// 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: