Upgrade guides for the API client

Upgrading from 1.20.0 to 2.0.0

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.

Upgrade your algoliasearch dependency to >=2.0,<3.0 using pip:

$
pip install --upgrade 'algoliasearch>=2.0,<3.0'

Then, update your requirements in your setup.py or requirements.txt to: algoliasearch>=2.0,<3.0.

SearchClient

You can initialize the SearchClient as follows:

1
2
3
4
5
- from algoliasearch.client import Client
- client = Client('app_id', 'api_key')

+ from algoliasearch.search_client import SearchClient
+ client = SearchClient.create('app_id', 'api_key')

List of method signature changes

SearchIndex

You can initialize the SearchIndex as follows:

1
2
3
4
5
- from algoliasearch.client import Client
- index = Client('app_id', 'api_key').init_index('name')

+ from algoliasearch.search_client import SearchClient
+ index = SearchClient.create('app_id', 'api_key').init_index('name')

List of method signature changes

AnalyticsClient

You can initialize the AnalyticsClient as follows:

1
2
3
4
5
- from algoliasearch.client import Client
- analytics = Client('app_id', 'api_key').init_analytics()

+ from algoliasearch.analytics_client import AnalyticsClient
+ analytics = AnalyticsClient.create('app_id', 'api_key')

List of method signature changes

InsightsClient

You can initialize the InsightsClient as follows:

1
2
3
4
5
- from algoliasearch.client import Client
- insights = Client('app_id', 'api_key').init_insights()

+ from algoliasearch.insights_client import InsightsClient
+ insights = InsightsClient.create('app_id', 'api_key')

List of method signature changes

Using configuration

You can instantiate all clients with configuration objects. This is useful to change the way a client behaves.

All setters have been removed. If, for instance, you relied on set_extra_headers or set_timeout, you need to change your code to use a configuration object:

1
2
3
4
5
6
7
8
9
10
11
12
# v1
client.timeout = (1, 30)

# v2
from algoliasearch.configs import SearchConfig

config = SearchConfig()
config.read_timeout = 1
config.write_timeout = 30

client = SearchClient.create_with_config(config)

Optional methods parameters and requestOptions

To have the most consistent, predictable, and future-proof method signature, the API client follows three rules:

• All required parameters have a single argument each
• All optional arguments are passed in a request_options dict, as the last argument
• The client never sets any default values

Here are some examples:

1
2
3
4
5
# v1
client.get_logs(0, 100, 'all')

# v2
client.get_logs({'offset': 0, 'length': 100, 'type': 'all'})

1
2
3
4
5
6
7
8
9
10
11
12
forward_to_replicas = True
synonym = {
  'objectID': 'a-unique-identifier',
  'type': 'altCorrection1',
  # ...
}

# v1
index.save_synonym(synonym, 'a-unique-identifier', forward_to_replicas)

# v2
index.save_synonym(synonym, {'forwardToReplicas': forward_to_replicas})

1
2
3
4
5
6
7
object = {'foo': 'bar'}

# v1
index.add_object(object)

# v2
index.save_object(object, {'autoGenerateObjectIDIfNotExist': True})

1
2
3
4
5
6
7
settings = {"searchableAttributes": ["name", "address"]}

# v1
index.set_settings(settings, True)

# v2
index.set_settings(settings, {'forwardToReplicas': True})

Exceptions

The import of the base AlgoliaException exception has changed:

1
2
3
4
5
# v1
from algoliasearch.helpers import AlgoliaException

# v2
from algoliasearch.exceptions import AlgoliaException

Miscellaneous

You can view all the changes on GitHub.