Upgrade the Python API clients to v4

The latest major version of the algoliasearch package is v4. This page lists the breaking changes since the last release, v3.

Method changes overview

The following table has links for all methods and their replacements

Search API client

v3 (legacy) v4 (latest)
client.add_api_key client.add_api_key
client.add_api_key.wait client.wait_for_api_key
client.assign_user_id client.assign_user_id
not available client.batch_assign_user_ids
client.clear_dictionary_entries client.batch_dictionary_entries
client.copy_index client.operation_index
client.copy_rules client.operation_index
client.copy_synonyms client.operation_index
client.delete_api_key client.delete_api_key
client.delete_dictionary_entries client.batch_dictionary_entries
client.generate_secured_api_key client.generate_secured_api_key
client.get_api_key client.get_api_key
client.get_secured_api_key_remaining_validity client.get_secured_api_key_remaining_validity
client.get_top_user_ids client.get_top_user_ids
client.get_user_id client.get_user_id
client.list_api_keys client.list_api_keys
client.list_indices client.list_indices
client.list_user_ids client.list_user_ids
client.move_index client.operation_index
client.multiple_batch client.multiple_batch
client.multiple_queries client.search
client.remove_user_id client.remove_user_id
client.replace_dictionary_entries client.batch_dictionary_entries
client.restore_api_key client.restore_api_key
client.save_dictionary_entries client.batch_dictionary_entries
client.search_user_ids client.search_user_ids
client.update_api_key client.update_api_key
index.batch client.batch
index.browse_objects client.browse_objects
index.browse_rules client.browse_rules
index.browse_synonyms client.browse_synonyms
index.clear_objects client.clear_objects
index.clear_rules client.clear_rules
index.clear_synonyms client.clear_synonyms
index.copy_settings client.operation_index
index.delete client.delete_index
index.delete_by client.delete_by
index.delete_object client.delete_object
index.delete_objects client.delete_objects
index.delete_rule client.delete_rule
index.delete_synonym client.delete_synonym
index.find_object client.search_single_index
index.get_object client.get_object
index.get_objects client.get_objects
index.get_rule client.get_rule
index.get_settings client.get_settings
index.get_synonym client.get_synonym
index.get_task client.get_task
index.partial_update_object client.partial_update_object
index.partial_update_objects client.partial_update_objects
index.replace_all_objects client.replace_all_objects
index.replace_all_rules client.save_rules
index.replace_all_synonyms client.save_synonyms
index.save_object client.save_object
index.save_objects client.save_objects
index.save_rule client.save_rule
index.save_rules client.save_rules
index.save_synonym client.save_synonym
index.save_synonyms client.save_synonyms
index.search client.search_single_index
index.search_for_facet_values client.search_for_facet_values
index.search_rules client.search_rules
index.search_synonyms client.search_synonyms
index.set_settings client.set_settings
index.{operation}.wait client.wait_for_task

Recommend API client

v3 (legacy) v4 (latest)
client.get_frequently_bought_together client.get_recommendations
client.get_recommendations client.get_recommendations
client.get_related_products client.get_recommendations

Client imports

The imports for the API clients changed.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
# Search API
from algoliasearch.search.client import SearchClientSync
# Search API (async)
from algoliasearch.search.client import SearchClient
# Recommend API
from algoliasearch.recommend.client import RecommendClientSync
# Recommend API (async)
from algoliasearch.recommend.client import RecommendClient
# A/B testing
from algoliasearch.abtesting.client import AbtestingClientSync
# A/B testing (async)
from algoliasearch.abtesting.client import AbtestingClient
# Analytics API
from algoliasearch.analytics.client import AnalyticsClientSync
# Analytics API (async)
from algoliasearch.analytics.client import AnalyticsClient
# Ingestion API
from algoliasearch.ingestion.client import IngestionClientSync
# Ingestion API (async)
from algoliasearch.ingestion.client import IngestionClient
# Insights API
from algoliasearch.insights.client import InsightsClientSync
# Insights API (async)
from algoliasearch.insights.client import InsightsClient
# Monitoring API
from algoliaserarch.monitoring.client import MonitoringClientSync
# Monitoring API (async)
from algoliaserarch.monitoring.client import MonitoringClient
# Personalization API
from algoliasearch.personalization.client import PersonalizationClientSync
# Personalization API (async)
from algoliasearch.personalization.client import PersonalizationClient
# Query Suggestions API
from algoliasearch.query_suggestions.client import QuerySuggestionsClientSync
# Query Suggestions API (async)
from algoliasearch.query_suggestions.client import QuerySuggestionsClient

Client creation

To create a client, create an instance of the SearchClientSync class. In async environment, create an instance of the SearchClient class instead. The SearchClient.create() method has been removed. The async API clients support the async with syntax to automatically close open connections.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
from algoliasearch.search.client import SearchClientSync
from algoliasearch.search.client import SearchClient # async client
from algoliasearch.search.config import SearchConfig

app_id = "ALGOLIA_APPLICATION_ID"
api_key = "ALGOLIA_API_KEY"

# With positional arguments
client = SearchClientSync(app_id, api_key)

# With keyword arguments
client = SearchClientSync(app_id=app_id, api_key=api_key)

# With a custom configuration
client = SearchClientSync(
    app_id=app_id,
    api_key=api_key,
    config=SearchConfig()
)

# async
async with SearchClient(app_id=app_id, api_key=api_key) as client:
    ...

Removal of init_index

All methods are methods of a client instance. The init_index method of the SearchClient has been removed. Instead, all methods require a index_name parameter.

1
2
3
4
5
6
7
8
# v3
client = SearchClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
index = client.init_index("ALGOLIA_INDEX_NAME")
index.search("QUERY")

# v4
client = SearchClientSync("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
client.search_single_index("ALGOLIA_INDEX_NAME", {"query": "QUERY"})

Wait for tasks

The wait method has been removed. Instead, use one of the following helpers:

Copy or move indices, settings, synonyms, or rules

Use the operation_index method, which replaces the following methods:

  • copy_index
  • move_index
  • copy_rules
  • copy_synonyms
  • copy_settings
Did you find this page helpful?
Python API clients v4