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`

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.

Copy
# 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.

Copy
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.

Copy
# 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:

wait_for_task to wait until indexing operations are done
wait_for_app_task to wait for application-level tasks
wait_for_api_key to wait for API key operations

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