Update the Python API client
This is documentation for v3 of the Python API clients, which is not the latest version. To see the documentation for the latest version, see Python v4.
You should keep your Python API client up to date to benefit from improvements and bug fixes.
The Python API client follows Semantic Versioning.
Upgrade to version 3.0.0
From version 2.x.x
This document lists every known breaking change:
- Remove support for Python 2
- Add support for Python 3.9 and above
- Remove deprecated
RecommendationClient
, use thePersonalizationClient
instead
Update your algoliasearch
dependency to >=3.0,<4.0
using pip:
$
python -m pip install --upgrade 'algoliasearch>=3.0,<4.0'
Then, update your requirements in your setup.py
or requirements.txt
to: algoliasearch>=3.0,<4.0
.
From version 1.x.x
Follow the Upgrade from 1.20.0 to 2.0.0 and From versions 2.x.x guides.
Upgrade 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.
Update your algoliasearch
dependency to >=2.0,<3.0
using pip:
$
python -m 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
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) |
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
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) |
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
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 |
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
1.20.0 | Breaking Change | 2.0.0 |
---|---|---|
post(data, request_options=None) |
Removed |
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 rely 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
dictionary, 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