API Reference
/
API Methods
/
Upgrade guides for the API client
May. 02, 2019
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:
Copy
$
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:
Copy
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:
Copy
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:
Copy
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:
Copy
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:
Copy
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:
Copy
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:
Copy
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:
Copy
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:
Copy
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 & Request Options
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 dict, as the last argument, and is called
request_options - The client never sets any default values
Here are a few examples:
Copy
1
2
3
4
5
# v1
client.get_logs(0, 100, 'all')
# v2
client.get_logs({'offset': 0, 'length': 100, 'type': 'all'})
Copy
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})
Copy
1
2
3
4
5
6
7
object = {'foo': 'bar'}
# v1
index.add_object(object)
# v2
index.save_object(object, {'autoGenerateObjectIDIfNotExist': True})
Copy
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:
Copy
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.
