Skip to main content
The latest major version of the algoliasearch-client-kotlin package is version 3. This page helps you upgrade from version 2 and explains the breaking changes you need to address. Algolia generates the version 3 clients from OpenAPI specifications, which provides consistent behavior across all languages and up-to-date API coverage. The main architectural changes are the removal of the initIndex pattern and the Kotlin DSL: all methods are now on the client instance directly, with indexName as a parameter, and parameters use typed data classes instead of DSL builders. For the full list of changes, see the Kotlin changelog.

Update your dependencies

Update the algoliasearch-client-kotlin dependency to version 3 in your build file:
build.gradle

Update imports

The package structure changed from com.algolia.search to com.algolia.client. Type wrapper classes like ApplicationID, APIKey, IndexName, and ObjectID no longer exist.
Kotlin
Version 3 also includes dedicated packages for each API. If you only need methods from a specific API, you can import them separately:
Kotlin

Update client initialization

Version 3 renames ClientSearch to SearchClient. It also removes the ApplicationID and APIKey type wrappers. Pass plain strings instead.
Kotlin
The other major change concerns what follows initialization: initIndex no longer exists.

Remove initIndex

This is the most significant structural change when upgrading. Version 2 relied on an index object with methods called on it. In version 3, all methods belong to the client instance, with indexName as a parameter.
Kotlin
If you have many files to update, search your codebase for initIndex or IndexName( to find every place that needs changing.

Replace the domain-specific language

Version 2 of the Kotlin client included a domain-specific language (DSL) for building queries, settings, and filters. Version 3 removes this DSL. Replace all DSL builder blocks with typed data class constructors and named parameters.

Query parameters

Kotlin

Settings

Kotlin

Filters

Kotlin
If you used the DSL extensively, search your codebase for query {, settings {, and filters { to find every block that needs rewriting.

Update search calls

Search a single index

The index.search() method is now client.searchSingleIndex(). Pass the index name and search parameters using named arguments:
Kotlin

Search multiple indices

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

Search for facet values

The index.searchForFacets() method becomes client.searchForFacetValues() with an indexName parameter:
Kotlin

Update indexing operations

In version 3, indexing methods are on the client instead of the index object, with indexName as a parameter. Version 3 replaces type wrappers like ObjectID("id") with plain strings.

Add or replace records

Kotlin

Partially update records

Kotlin

Delete records

Kotlin

Update settings, synonyms, and rules

Get and set settings

Kotlin

Save synonyms and rules

Kotlin
In version 2, index.replaceAllRules() and index.replaceAllSynonyms() replaced all rules or synonyms. In version 3, use client.saveRules() or client.saveSynonyms() with the clearExistingRules or clearExistingSynonyms parameter set to true.

Update index management

The copyIndex, moveIndex, copyRules, copySynonyms, and copySettings methods are all replaced by a single operationIndex method.

Copy an index

Kotlin

Move (rename) an index

Kotlin

Copy only rules or settings

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

Check if an index exists

In version 2, you could check if an index existed using the exists method on the index object. In version 3, use the indexExists helper method on the client:
Kotlin

Update task handling

Version 2 supported chaining .wait() on operations. Version 3 replaces this pattern with dedicated wait helpers.
Kotlin
Version 3 includes three wait helpers:

Helper method changes

The following sections document breaking changes in helper method signatures and behavior between version 2 and version 3.

generateSecuredApiKey

The method was renamed from generateAPIKey to generateSecuredApiKey. The input type also changed from APIKey wrapper to String, and the return type changed from APIKey to String.
Kotlin

securedApiKeyRemainingValidity

The function was renamed and its return type changed from Long (milliseconds) to Duration. In version 3 it is a top-level function, not a method on the client.
Kotlin

replaceAllObjects

This helper moved from the Index object to SearchClient. The KSerializer<T> requirement was removed—objects are now passed as List<JsonObject>. New batchSize (default 1,000) and scopes parameters were added, and the return type changed from List<TaskIndex> to ReplaceAllObjectsResponse.
Kotlin

saveObjects

This helper moved from the Index object to SearchClient. The KSerializer<T> requirement was removed. Two new optional parameters are available:
  • waitForTasks (default false)
  • batchSize (default 1,000)
Kotlin

deleteObjects

This helper moved from the Index object to SearchClient. Two new optional parameters are available:
  • waitForTasks (default false)
  • batchSize (default 1,000)
Kotlin

partialUpdateObjects

This helper moved from the Index object to SearchClient. The createIfNotExists parameter is now required—in version 2 it defaulted to true. The input type changed from List<Pair<ObjectID, Partial>> to List<JsonObject>.
Kotlin

browseObjects, browseRules, browseSynonyms

These helpers moved from the Index object to SearchClient. The input type changed from Query/RuleQuery/SynonymQuery to BrowseParamsObject/SearchRulesParams/SearchSynonymsParams. They now use an aggregator callback instead of returning a list, and accept an optional validate callback to stop early.
Kotlin

waitForTask

The helper was renamed from waitTask to waitForTask. The timeout parameter type changed from Long? (milliseconds cap) to Duration (default Duration.INFINITE). Explicit maxRetries (default 100), initialDelay (default 200ms), and maxDelay (default 5s) parameters were added. The return type changed from TaskStatus to GetTaskResponse.
Kotlin

waitForAppTask

This is a new helper in version 3.
Kotlin

waitForApiKey

This is a new standalone helper in version 3. In version 2, waiting for API key operations required polling manually.
Kotlin

indexExists

The helper was renamed from exists() on the Index object to indexExists() on the client.
Kotlin

chunkedBatch

chunkedBatch is now a public helper in version 3. The waitForTasks parameter is required and must be passed explicitly.
Kotlin

copyIndexBetweenApplications

In version 2, the ClientAccount singleton provided a copyIndex(source, destination) suspend function for copying an index between two different Algolia applications. In version 3, ClientAccount is removed. You can compose existing helpers across two clients to achieve the same result.
Kotlin

saveObjectsWithTransformation

In version 3: routes records with the Push to Algolia connector. Requires transformationOptions to be installed on the client via SearchClient.withTransformation (or setTransformationOptions). region is required; every other field keeps the Ingestion API defaults.
Kotlin

replaceAllObjectsWithTransformation

In version 3: atomically replaces all records with the Push to Algolia connector. It copies settings, rules, and synonyms to a temporary index, pushes records to the temporary index, and moves the temporary index back. scopes defaults to Settings, Rules, and Synonyms.
Kotlin

partialUpdateObjectsWithTransformation

In version 3: routes partial updates with the Push to Algolia connector. The createIfNotExists parameter defaults to false.
Kotlin

Method changes reference

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

Search API client

Recommend API client

Last modified on July 6, 2026