API Reference / API Methods / Upgrade guides for the API client

Upgrade guides for the API client

Upgrading from 1.20.0 to 2.0.0

We attempt to document every possible breaking change. Since some of these breaking changes are in obscure parts of the API Client, only a portion of these changes may actually affect your application.

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.

Search Client

Previously, to get started:

1
2
3
from algoliasearch.client import Client

client = Client('app_id', 'api_key')

Now, in the 2.0.0 you should update your code to:

1
2
3
from algoliasearch.search_client import SearchClient

client = SearchClient.create('app_id', 'api_key')
List of Method Signature Changes
1.20.0 Breaking Change 2.0.0
addUserKey(obj, validity=0, max_queries_per_ip_per_hour=0, max_hits_per_query=0, indexes=None) Removed, use add_api_key instead add_api_key(acl, request_options=None)
add_api_key(obj, validity=0, max_queries_per_ip_per_hour=0, max_hits_per_query=0, indexes=None, request_options=None) Changed add_api_key(acl, request_options=None)
add_user_key(obj, validity=0, max_queries_per_ip_per_hour=0, max_hits_per_query=0, indexes=None) Removed, use add_api_key instead add_api_key(acl, request_options=None)
batch(requests, request_options=None) Removed, use multiple_batch instead multiple_batch(operations, request_options=None)
copyIndex(src_index_name, dst_index_name) Removed, use copy_index instead copy_index(src_index_name, dst_index_name, request_options=None)
copy_index(src_index_name, dst_index_name, request_options=None, scope=None) Changed copy_index(src_index_name, dst_index_name, request_options=None)
deleteIndex(index_name) Removed, use init_index('name').delete() instead delete(request_options=None)
deleteUserKey(api_key) Removed, use delete_api_key instead delete_api_key(key, request_options=None)
delete_api_key(api_key, request_options=None) Changed delete_api_key(key, request_options=None)
delete_index(index_name, request_options=None) Removed, use init_index('name').delete() instead delete(request_options=None)
delete_user_key(api_key) Removed, use delete_api_key instead delete_api_key(key, request_options=None)
disableRateLimitForward() Removed, use RequestOptions param instead
disable_rate_limit_forward() Removed, use RequestOptions param instead
enableRateLimitForward(admin_api_key, end_user_ip, rate_limit_api_key) Removed, use RequestOptions param instead
enable_rate_limit_forward(end_user_ip, rate_limit_api_key) Removed, use RequestOptions param instead
generateSecuredApiKey(private_api_key, tag_filters, user_token='') Removed, use generate_secured_api_key instead generate_secured_api_key(parent_api_key, restrictions)
generate_secured_api_key(private_api_key, queryParameters, user_token='') Changed generate_secured_api_key(parent_api_key, restrictions)
getLogs(offset=0, length=10, type='all') Removed, use get_logs instead get_logs(request_options=None)
getUserKeyACL(api_key) Removed, use get_api_key instead get_api_key(key, request_options=None)
get_api_key(api_key, request_options=None) Changed get_api_key(key, request_options=None)
get_api_key_acl(api_key, request_options=None) Removed, use get_api_key instead get_api_key(key, request_options=None)
get_logs(offset=0, length=10, type='all', request_options=None) Changed get_logs(request_options=None)
get_task(index_name, task_id, request_options=None) Removed, use init_index('name').get_task instead get_task(task_id, request_options=None)
get_top_user_id(request_options=None) Removed, use get_top_user_ids instead get_top_user_ids(request_options=None)
get_user_key_acl(api_key) Removed, use get_api_key instead get_api_key(key, request_options=None)
initIndex(index_name) Removed, use init_index instead init_index(name)
init_analytics() Removed, use AnalyticsClient.create instead create(app_id=None, api_key=None, region=None)
init_index(index_name) Changed init_index(name)
init_insights_client(region='us') Removed, use InsightsClient.create instead create(app_id=None, api_key=None, region=None)
is_alive(request_options=None) Removed
is_task_published(index_name, task_id, request_options=None) Removed
listIndexes() Removed, use list_indices instead list_indices(request_options=None)
listUserKeys() Removed, use list_api_keys instead list_api_keys(request_options=None)
list_indexes(request_options=None) Removed, use list_indices instead list_indices(request_options=None)
list_user_ids(page=0, hits_per_page=20, request_options=None) Changed list_user_ids(request_options=None)
list_user_keys() Removed, use list_api_keys instead list_api_keys(request_options=None)
moveIndex(src_index_name, dst_index_name) Removed, use move_index instead move_index(src_index_name, dst_index_name, request_options=None)
multipleQueries(queries, index_name_key='indexName') Removed, use multiple_queries instead multiple_queries(queries, request_options=None)
multiple_queries(queries, index_name_key='indexName', strategy='none', request_options=None) Changed multiple_queries(queries, request_options=None)
restore_api_key(api_key, request_options=None) Changed restore_api_key(key, request_options=None)
search_user_ids(query, cluster=None, page=None, hits_per_page=None, request_options=None) Changed search_user_ids(query, request_options=None)
set_end_user_ip(end_user_ip) Removed, use RequestOptions param instead
set_extra_header(key, value) Removed, use RequestOptions param instead
set_extra_headers(**kwargs) Removed, use RequestOptions param instead
set_timeout(connect_timeout, read_timeout, search_timeout=5) Removed, use RequestOptions param instead
update_api_key(api_key, obj, validity=None, max_queries_per_ip_per_hour=None, max_hits_per_query=None, indexes=None, request_options=None) Changed update_api_key(key, request_options=None)
update_user_key(api_key, obj, validity=None, max_queries_per_ip_per_hour=None, max_hits_per_query=None, indexes=None) Removed, use update_api_key instead update_api_key(key, request_options=None)
wait_task(index_name, task_id, time_before_retry=100, request_options=None) Removed, use init_index('name').wait_task instead wait_task(task_id, request_options=None)

Search Index

Previously, to get started:

1
2
3
from algoliasearch.client import Client

index = Client('app_id', 'api_key').init_index('name')

Now, in the 2.0.0 you should update your code to:

1
2
3
from algoliasearch.search_client import SearchClient

index = SearchClient.create('app_id', 'api_key').init_index('name')
List of Method Signature Changes
1.20.0 Breaking Change 2.0.0
addObject(content, object_id=None) Removed, use save_object instead save_object(obj, request_options=None)
addObjects(objects) Removed, use save_objects instead save_objects(objects, request_options=None)
addUserKey(obj, validity=0, max_queries_per_ip_per_hour=0, max_hits_per_query=0) Removed, use SearchClient.add_api_key instead add_api_key(acl, request_options=None)
add_api_key(obj, validity=0, max_queries_per_ip_per_hour=0, max_hits_per_query=0, request_options=None) Removed, use SearchClient.add_api_key instead add_api_key(acl, request_options=None)
add_object(content, object_id=None, request_options=None) Removed, use save_object instead save_object(obj, request_options=None)
add_objects(objects, request_options=None) Removed, use save_objects instead save_objects(objects, request_options=None)
add_user_key(obj, validity=0, max_queries_per_ip_per_hour=0, max_hits_per_query=0) Removed, use SearchClient.add_api_key instead add_api_key(acl, request_options=None)
batch(requests, no_create=False, request_options=None) Changed batch(requests, request_options=None)
batch_rules(rules, forward_to_replicas=False, clear_existing_rules=False, request_options=None) Removed, use save_rules instead save_rules(rules, request_options=None)
batch_synonyms(synonyms, forward_to_slaves=False, replace_existing_synonyms=False, forward_to_replicas=False, request_options=None) Removed, use save_synonyms instead save_synonyms(synonyms, request_options=None)
browse(page=0, hits_per_page=1000) Removed, use browse_objects instead browse_objects(request_options=None)
browse_all(params=None, request_options=None) Removed, use browse_objects instead browse_objects(request_options=None)
browse_from(params=None, cursor=None, request_options=None) Removed, use browse_objects instead browse_objects(request_options=None)
clearIndex() Removed, use clear_objects instead clear_objects(request_options=None)
clear_index(request_options=None) Removed, use clear_objects instead clear_objects(request_options=None)
clear_rules(forward_to_replicas=False, request_options=None) Changed clear_rules(request_options=None)
clear_synonyms(forward_to_slaves=False, forward_to_replicas=False, request_options=None) Changed clear_synonyms(request_options=None)
deleteByQuery(query, params=None) Removed, use delete_by instead delete_by(filters, request_options=None)
deleteObject(object_id) Removed, use delete_object instead delete_object(object_id, request_options=None)
deleteObjects(objects) Removed, use delete_objects instead delete_objects(object_ids, request_options=None)
deleteUserKey(key) Removed, use SearchClient.delete_api_key instead delete_api_key(key, request_options=None)
delete_api_key(key, request_options=None) Removed, use SearchClient.delete_api_key instead delete_api_key(key, request_options=None)
delete_by(params, request_options=None) Changed delete_by(filters, request_options=None)
delete_by_query(query, params=None, request_options=None) Removed, use delete_by instead delete_by(filters, request_options=None)
delete_objects(objects, request_options=None) Changed delete_objects(object_ids, request_options=None)
delete_rule(objectID, forward_to_replicas=False, request_options=None) Changed delete_rule(object_id, request_options=None)
delete_synonym(object_id, forward_to_slaves=False, forward_to_replicas=False, request_options=None) Changed delete_synonym(object_id, request_options=None)
delete_user_key(key) Removed, use SearchClient.delete_api_key instead delete_api_key(key, request_options=None)
getObject(object_id, attributes_to_retrieve=None) Removed, use get_object instead get_object(object_id, request_options=None)
getObjects(object_ids) Removed, use get_objects instead get_objects(object_ids, request_options=None)
getSettings() Removed, use get_settings instead get_settings(request_options=None)
getUserKeyACL(key) Removed, use SearchClient.get_api_key instead get_api_key(key, request_options=None)
get_api_key_acl(key, request_options=None) Removed, use SearchClient.get_api_key instead get_api_key(key, request_options=None)
get_object(object_id, attributes_to_retrieve=None, request_options=None) Changed get_object(object_id, request_options=None)
get_objects(object_ids, attributes_to_retrieve=None, request_options=None) Changed get_objects(object_ids, request_options=None)
get_user_key_acl(key) Removed, use SearchClient.get_api_key instead get_api_key(key, request_options=None)
is_task_published(task_id, request_options=None) Removed
iter_rules(hits_per_page=1000, request_options=None) Removed, use browse_rules instead browse_rules(request_options=None)
iter_synonyms(hits_per_page=1000, request_options=None) Removed, use browse_synonyms instead browse_synonyms(request_options=None)
listUserKeys() Removed, use SearchClient.list_api_keys instead list_api_keys(self, request_options=None)
list_api_keys(request_options=None) Removed, use SearchClient.list_api_keys instead list_api_keys(self, request_options=None)
list_user_keys() Removed, use SearchClient.list_api_keys instead list_api_keys(self, request_options=None)
partialUpdateObject(partial_object) Removed, use partial_update_object instead partial_update_object(obj, request_options=None)
partialUpdateObjects(objects) Removed, use partial_update_objects instead partial_update_objects(objects, request_options=None)
partial_update_object(partial_object, no_create=False, request_options=None) Changed partial_update_object(obj, request_options=None)
partial_update_objects(objects, no_create=False, request_options=None) Changed partial_update_objects(objects, request_options=None)
read_rule(objectID, request_options=None) Removed, use get_rule instead get_rule(object_id, request_options=None)
saveObject(obj) Removed, use save_object instead save_object(obj, request_options=None)
saveObjects(objects) Removed, use save_objects instead save_objects(objects, request_options=None)
save_rule(rule, forward_to_replicas=False, request_options=None) Changed save_rule(rule, request_options=None)
save_synonym(content, object_id, forward_to_slaves=False, forward_to_replicas=False, request_options=None) Changed save_synonym(synonym, request_options=None)
search(query, args=None, request_options=None) Changed search(query, request_options=None)
searchDisjunctiveFaceting(query, disjunctive_facets, params=None, refinements=None) Removed
search_disjunctive_faceting(query, disjunctive_facets, params=None, refinements=None, request_options=None) Removed
search_facet(facet_name, facet_query, query=None, request_options=None) Removed, use search_for_facet_values instead search_for_facet_values(facet_name, facet_query, request_options=None)
search_for_facet_values(facet_name, facet_query, query=None, request_options=None) Removed, use search_for_facet_values instead search_for_facet_values(facet_name, facet_query, request_options=None)
search_rules(query=None, anchoring=None, context=None, page=None, hitsPerPage=None, request_options=None) Changed search_rules(query, request_options=None)
search_synonyms(query, types=[], page=0, hits_per_page=100, request_options=None) Changed search_synonyms(query, request_options=None)
setSettings(settings) Removed, use set_settings instead set_settings(settings, request_options=None)
set_settings(settings, forward_to_slaves=True, forward_to_replicas=True, request_options=None) Changed set_settings(settings, request_options=None)
update_api_key(key, obj, validity=None, max_queries_per_ip_per_hour=None, max_hits_per_query=None, request_options=None) Removed, use SearchClient.update_api_key instead update_api_key(key, request_options=None)
update_user_key(key, obj, validity=None, max_queries_per_ip_per_hour=None, max_hits_per_query=None) Removed, use SearchClient.update_api_key instead update_api_key(key, request_options=None)
waitTask(task_id, time_before_retry=100) Removed, use wait_task instead wait_task(task_id, request_options=None)
wait_task(task_id, time_before_retry=100, request_options=None) Changed wait_task(task_id, request_options=None)

Analytics Client

Previously, to get started:

1
2
3
from algoliasearch.client import Client

analytics = Client('app_id', 'api_key').init_analytics()

Now, in the 2.0.0 you should update your code to:

1
2
3
from algoliasearch.analytics_client import AnalyticsClient

analytics = AnalyticsClient.create('app_id', 'api_key')
List of Method Signature Changes
1.20.0 Breaking Change 2.0.0
add_ab_test(ab_test) Changed add_ab_test(ab_test, request_options=None)
delete_ab_test(ab_test_id) Changed delete_ab_test(ab_test_id, request_options=None)
get_ab_test(ab_test_id) Changed get_ab_test(ab_test_id, request_options=None)
get_ab_tests(args=None) Changed get_ab_tests(request_options=None)
stop_ab_test(ab_test_id) Changed stop_ab_test(ab_test_id, request_options=None)
wait_task(index_name, task_id, time_before_retry=100, request_options=None) Removed

Insights Client

Previously, to get started:

1
2
3
from algoliasearch.client import Client

insights = Client('app_id', 'api_key').init_insights()

Now, in the 2.0.0 you should update your code to:

1
2
3
from algoliasearch.insights_client import InsightsClient

insights = InsightsClient.create('app_id', 'api_key')
List of Method Signature Changes
1.20.0 Breaking Change 2.0.0
post(data, request_options=None) Removed

Using configuration

All clients can be instantiated via configuration objects. This is useful to affect 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, we followed 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 a few 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

We also encourage you to view the changes in the github.com/algolia/algoliasearch-client-python GitHub repository.

Did you find this page helpful?