Upgrade the Python API client to version 4

The latest major version of the algoliasearch package is version 4. This page helps you upgrade from version 3 and explains the breaking changes you need to address. Algolia generates the version 4 clients from OpenAPI specifications, which provides consistent behavior across all languages and up-to-date API coverage. The main architectural change is the removal of the init_index pattern: all methods are now on the client instance directly, with index_name as a parameter. For the full list of changes, see the Python changelog.

Update your dependencies

Update the algoliasearch package to version 4:

pip install 'algoliasearch>=4.0,<5.0'

Update imports

The import path changed from algoliasearch.search_client to algoliasearch.search.client.

Python

# version 3
from algoliasearch.search_client import SearchClient

# version 4
from algoliasearch.search.client import SearchClient, SearchClientSync

Version 4 also includes dedicated packages for each API. If you only need methods from a specific API, you can import them separately:

Python

# Search API
from algoliasearch.search.client import SearchClient, SearchClientSync
# A/B testing API
from algoliasearch.abtesting.client import AbtestingClient, AbtestingClientSync
# Analytics API
from algoliasearch.analytics.client import AnalyticsClient, AnalyticsClientSync
# Ingestion API
from algoliasearch.ingestion.client import IngestionClient, IngestionClientSync
# Insights API
from algoliasearch.insights.client import InsightsClient, InsightsClientSync
# Personalization API
from algoliasearch.personalization.client import (
    PersonalizationClient,
    PersonalizationClientSync,
)
# Query Suggestions API
from algoliasearch.query_suggestions.client import (
    QuerySuggestionsClient,
    QuerySuggestionsClientSync,
)
# Recommend API
from algoliasearch.recommend.client import RecommendClient, RecommendClientSync
# Monitoring API
from algoliasearch.monitoring.client import MonitoringClient, MonitoringClientSync

Update client initialization

Client creation changed in version 4. The SearchClient.create() factory method is gone. Create a SearchClientSync instance for synchronous code or a SearchClient instance for asynchronous code.

Python

# version 3
from algoliasearch.search_client import SearchClient
client = SearchClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")

# version 4 (synchronous)
from algoliasearch.search.client import SearchClientSync
client = SearchClientSync("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")

# version 4 (asynchronous)
from algoliasearch.search.client import SearchClient
async with SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY") as client:
    ...

Note the naming: SearchClientSync is the synchronous client, while SearchClient (without suffix) is the asynchronous client. The asynchronous client supports the async with syntax to automatically close open connections.

Understand the new API surface

Version 4 introduces three major changes to the API surface:

No more init_index. Version 3 relied on an index object with methods called on it. In version 4, all methods belong to the client instance, with index_name as a parameter.
Synchronous and asynchronous clients. Version 4 includes SearchClientSync for synchronous code and SearchClient for asynchronous code (with async/await). Version 3 only had a synchronous client.
Typed model classes. Version 4 includes model classes like SearchParams and IndexSettings for all API parameters (see Use model classes or dictionaries).

Python

# version 3
client = SearchClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
index = client.init_index("ALGOLIA_INDEX_NAME")
index.search("QUERY")

# version 4
client = SearchClientSync("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
client.search_single_index(
    index_name="ALGOLIA_INDEX_NAME",
    search_params=SearchParams(query="QUERY"),
)

If you have many files to update, search your codebase for init_index or .init_index( to find every place that needs changing.

Use model classes or dictionaries

Version 4 methods accept both model classes and dictionaries as parameters.

Python

# Using a model class
from algoliasearch.search.models.search_params import SearchParams

client.search_single_index(
    index_name="ALGOLIA_INDEX_NAME",
    search_params=SearchParams(query="QUERY"),
)

# Using a dictionary
client.search_single_index(
    index_name="ALGOLIA_INDEX_NAME",
    search_params={"query": "QUERY"},
)

Model classes give you IDE autocompletion, type safety, and predictable structure that works well with AI coding assistants. The code examples in this guide use model classes, but you can use dictionaries anywhere a model is expected.

Update search calls

Search a single index

The index.search() method is now client.search_single_index(). Pass the index name and search parameters as separate arguments:

Python

# version 3
index = client.init_index("ALGOLIA_INDEX_NAME")
results = index.search("QUERY", {
    "facetFilters": ["category:Book"],
})

# version 4
results = client.search_single_index(
    index_name="ALGOLIA_INDEX_NAME",
    search_params=SearchParams(
        query="QUERY",
        facet_filters=["category:Book"],
    ),
)

Search multiple indices

The client.multiple_queries() method is now client.search(). Each request in the list requires an indexName:

Python

# version 3
results = client.multiple_queries([
    {"indexName": "INDEX_1", "query": "QUERY"},
    {"indexName": "INDEX_2", "query": "QUERY"},
])

# version 4
results = client.search(
    search_method_params=SearchMethodParams(
        requests=[
            SearchForHits(index_name="INDEX_1", query="QUERY"),
            SearchForHits(index_name="INDEX_2", query="QUERY"),
        ],
    ),
)

The index.search_for_facet_values() method becomes client.search_for_facet_values() with an index_name parameter:

Python

# version 3
index = client.init_index("ALGOLIA_INDEX_NAME")
results = index.search_for_facet_values("category", "book")

# version 4
results = client.search_for_facet_values(
    index_name="ALGOLIA_INDEX_NAME",
    facet_name="category",
    search_for_facet_values_request=SearchForFacetValuesRequest(facet_query="book"),
)

Update indexing operations

In version 4, indexing methods are on the client instead of the index object, with index_name as a parameter.

Add or replace records

Python

# version 3
index = client.init_index("ALGOLIA_INDEX_NAME")
index.save_objects([{"objectID": "1", "name": "Record"}])

# version 4
response = client.save_objects(
    index_name="ALGOLIA_INDEX_NAME",
    objects=[{"objectID": "1", "name": "Record"}],
)

Partially update records

Python

# version 3
index = client.init_index("ALGOLIA_INDEX_NAME")
index.partial_update_object({"objectID": "1", "name": "Updated"})

# version 4
client.partial_update_object(
    index_name="ALGOLIA_INDEX_NAME",
    object_id="1",
    attributes_to_update={"name": "Updated"},
)

Delete records

Python

# version 3
index = client.init_index("ALGOLIA_INDEX_NAME")
index.delete_object("1")

# version 4
client.delete_object(
    index_name="ALGOLIA_INDEX_NAME",
    object_id="1",
)

Update settings, synonyms, and rules

Get and set settings

Python

# version 3
index = client.init_index("ALGOLIA_INDEX_NAME")
settings = index.get_settings()
index.set_settings({"searchableAttributes": ["title", "author"]})

# version 4
settings = client.get_settings(
    index_name="ALGOLIA_INDEX_NAME",
)
client.set_settings(
    index_name="ALGOLIA_INDEX_NAME",
    index_settings=IndexSettings(searchable_attributes=["title", "author"]),
)

Save synonyms and rules

Python

# version 3
index = client.init_index("ALGOLIA_INDEX_NAME")
index.save_synonyms([{"objectID": "1", "type": "synonym", "synonyms": ["car", "auto"]}])
index.save_rules([{"objectID": "1", "conditions": [{"anchoring": "contains", "pattern": "shoes"}], "consequence": {"params": {"query": "sneakers"}}}])

# version 4
client.save_synonyms(
    index_name="ALGOLIA_INDEX_NAME",
    synonym_hit=[
        {"objectID": "1", "type": "synonym", "synonyms": ["car", "auto"]},
    ],
)
client.save_rules(
    index_name="ALGOLIA_INDEX_NAME",
    rules=[
        {
            "objectID": "1",
            "conditions": [{"anchoring": "contains", "pattern": "shoes"}],
            "consequence": {"params": {"query": "sneakers"}},
        },
    ],
)

In version 3, index.replace_all_rules() and index.replace_all_synonyms() replaced all rules or synonyms. In version 4, use client.save_rules() or client.save_synonyms() with the clear_existing_rules or replace_existing_synonyms parameter set to True.

Update index management

The copy_index, move_index, copy_rules, copy_synonyms, and copy_settings methods are all replaced by a single operation_index method.

Copy an index

Python

# version 3
client.copy_index("SOURCE_INDEX_NAME", "DESTINATION_INDEX_NAME")

# version 4
client.operation_index(
    index_name="SOURCE_INDEX_NAME",
    operation_index_params=OperationIndexParams(
        operation="copy",
        destination="DESTINATION_INDEX_NAME",
    ),
)

Move (rename) an index

Python

# version 3
client.move_index("SOURCE_INDEX_NAME", "DESTINATION_INDEX_NAME")

# version 4
client.operation_index(
    index_name="SOURCE_INDEX_NAME",
    operation_index_params=OperationIndexParams(
        operation="move",
        destination="DESTINATION_INDEX_NAME",
    ),
)

Copy only rules or settings

In version 4, use the scope parameter to limit the operation to specific data:

Python

# version 4 -- copy only rules and settings from one index to another
client.operation_index(
    index_name="SOURCE_INDEX_NAME",
    operation_index_params=OperationIndexParams(
        operation="copy",
        destination="DESTINATION_INDEX_NAME",
        scope=["rules", "settings"],
    ),
)

Update task handling

Version 3 supported chaining .wait() on operations. Version 4 replaces this pattern with dedicated wait helpers.

Python

# version 3
index = client.init_index("ALGOLIA_INDEX_NAME")
index.set_settings({"searchableAttributes": ["title"]}).wait()

# version 4
response = client.set_settings(
    index_name="ALGOLIA_INDEX_NAME",
    index_settings=IndexSettings(searchable_attributes=["title"]),
)
client.wait_for_task(index_name="ALGOLIA_INDEX_NAME", task_id=response.task_id)

Version 4 includes three wait helpers:

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

Method changes reference

The following tables list all method names that changed between version 3 and version 4.

Search API client

Version 3 (legacy)		Version 4 (current)
`client.add_api_key`	→	`client.add_api_key`
`client.add_api_key.wait`	→	`client.wait_for_api_key`
`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.list_api_keys`	→	`client.list_api_keys`
`client.list_indices`	→	`client.list_indices`
`client.move_index`	→	`client.operation_index`
`client.multiple_batch`	→	`client.multiple_batch`
`client.multiple_queries`	→	`client.search`
`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.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`

Version 3 (legacy)		Version 4 (current)
`client.get_frequently_bought_together`	→	`client.get_recommendations`
`client.get_recommendations`	→	`client.get_recommendations`
`client.get_related_products`	→	`client.get_recommendations`

API clients (current)

Clients and methods

Upgrade the Python API client to version 4

Update your dependencies

Update imports

Update client initialization

Understand the new API surface

Use model classes or dictionaries

Update search calls

Search a single index

Search multiple indices

Search for facet values

Update indexing operations

Add or replace records

Partially update records

Delete records

Update settings, synonyms, and rules

Get and set settings

Save synonyms and rules

Update index management

Copy an index

Move (rename) an index

Copy only rules or settings

Update task handling

Method changes reference

Search API client

API clients (current)

Clients and methods

​Update your dependencies

​Update imports

​Update client initialization

​Understand the new API surface

​Use model classes or dictionaries

​Update search calls

​Search a single index

​Search multiple indices

​Search for facet values

​Update indexing operations

​Add or replace records

​Partially update records

​Delete records

​Update settings, synonyms, and rules

​Get and set settings

​Save synonyms and rules

​Update index management

​Copy an index

​Move (rename) an index

​Copy only rules or settings

​Update task handling

​Method changes reference

​Search API client

​Recommend API client

Update your dependencies

Update imports

Update client initialization

Understand the new API surface

Use model classes or dictionaries

Update search calls

Search a single index

Search multiple indices

Search for facet values

Update indexing operations

Add or replace records

Partially update records

Delete records

Update settings, synonyms, and rules

Get and set settings

Save synonyms and rules

Update index management

Copy an index

Move (rename) an index

Copy only rules or settings

Update task handling

Method changes reference

Search API client

Recommend API client