Upgrade the Kotlin API client to version 3

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

// version 2
implementation("com.algolia:algoliasearch-client-kotlin:2.x.x")

// version 3
implementation("com.algolia:algoliasearch-client-kotlin:3.+")

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 2
import com.algolia.search.client.ClientSearch
import com.algolia.search.model.ApplicationID
import com.algolia.search.model.APIKey
import com.algolia.search.model.IndexName
import com.algolia.search.model.ObjectID
import com.algolia.search.model.search.Query
import com.algolia.search.dsl.query
import com.algolia.search.dsl.settings

// version 3
import com.algolia.client.api.SearchClient
import com.algolia.client.model.search.*

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

Kotlin

// Search API
import com.algolia.client.api.SearchClient
// Recommend API
import com.algolia.client.api.RecommendClient
// A/B testing API
import com.algolia.client.api.AbtestingClient
// Analytics API
import com.algolia.client.api.AnalyticsClient
// Personalization API
import com.algolia.client.api.PersonalizationClient
// Query Suggestions API
import com.algolia.client.api.QuerySuggestionsClient

Update client initialization

Version 3 renames ClientSearch to SearchClient. It also removes the ApplicationID and APIKey type wrappers. Pass plain strings instead.

Kotlin

// version 2
val client = ClientSearch(
    ApplicationID("ALGOLIA_APPLICATION_ID"),
    APIKey("ALGOLIA_API_KEY")
)

// version 3
val client = SearchClient(
    appId = "ALGOLIA_APPLICATION_ID",
    apiKey = "ALGOLIA_API_KEY"
)

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

// version 2
val client = ClientSearch(
    ApplicationID("ALGOLIA_APPLICATION_ID"),
    APIKey("ALGOLIA_API_KEY")
)
val index = client.initIndex(IndexName("ALGOLIA_INDEX_NAME"))
index.search(Query("QUERY"))

// version 3
val client = SearchClient(
    appId = "ALGOLIA_APPLICATION_ID",
    apiKey = "ALGOLIA_API_KEY"
)
client.searchSingleIndex(
    indexName = "ALGOLIA_INDEX_NAME",
    searchParamsObject = SearchParamsObject(query = "QUERY")
)

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

// version 2
val query = query {
    attributesToRetrieve {
        +"color"
        +"category"
    }
}

// version 3
val params = SearchParamsObject(
    query = "QUERY",
    attributesToRetrieve = listOf("color", "category")
)

Settings

Kotlin

// version 2
val settings = settings {
    searchableAttributes {
        +"title"
        +"author"
    }
}

// version 3
val settings = IndexSettings(
    searchableAttributes = listOf("title", "author")
)

Filters

Kotlin

// version 2
val query = query {
    filters {
        and {
            facet("color", "red")
            facet("category", "shirt")
        }
    }
}

// version 3
val params = SearchParamsObject(
    query = "QUERY",
    filters = "color:red AND category:shirt"
)

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

// version 2
val index = client.initIndex(IndexName("ALGOLIA_INDEX_NAME"))
val results = index.search(Query("QUERY").apply {
    facetFilters = listOf(listOf("category:Book"))
})

// version 3
val results = client.searchSingleIndex(
    indexName = "ALGOLIA_INDEX_NAME",
    searchParamsObject = SearchParamsObject(
        query = "QUERY",
        filters = "category:Book"
    )
)

Search multiple indices

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

Kotlin

// version 2
val results = client.multipleQueries(
    listOf(
        IndexQuery(IndexName("INDEX_1"), Query("QUERY")),
        IndexQuery(IndexName("INDEX_2"), Query("QUERY"))
    )
)

// version 3
val results = client.search(
    searchMethodParams = SearchMethodParams(
        requests = listOf(
            SearchForHits(indexName = "INDEX_1", query = "QUERY"),
            SearchForHits(indexName = "INDEX_2", query = "QUERY")
        )
    )
)

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

Kotlin

// version 2
val index = client.initIndex(IndexName("ALGOLIA_INDEX_NAME"))
val results = index.searchForFacets(Attribute("category"), "book")

// version 3
val results = client.searchForFacetValues(
    indexName = "ALGOLIA_INDEX_NAME",
    facetName = "category",
    searchForFacetValuesRequest = SearchForFacetValuesRequest(facetQuery = "book")
)

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

// version 2
val index = client.initIndex(IndexName("ALGOLIA_INDEX_NAME"))
index.saveObject(buildJsonObject {
    put("objectID", "1")
    put("name", "Record")
})

// version 3
client.saveObject(
    indexName = "ALGOLIA_INDEX_NAME",
    body = buildJsonObject {
        put("objectID", "1")
        put("name", "Record")
    }
)

Partially update records

Kotlin

// version 2
val index = client.initIndex(IndexName("ALGOLIA_INDEX_NAME"))
index.partialUpdateObject(buildJsonObject {
    put("objectID", "1")
    put("name", "Updated")
})

// version 3
client.partialUpdateObject(
    indexName = "ALGOLIA_INDEX_NAME",
    objectID = "1",
    attributesToUpdate = buildJsonObject { put("name", "Updated") }
)

Delete records

Kotlin

// version 2
val index = client.initIndex(IndexName("ALGOLIA_INDEX_NAME"))
index.deleteObject(ObjectID("1"))

// version 3
client.deleteObject(
    indexName = "ALGOLIA_INDEX_NAME",
    objectID = "1"
)

Update settings, synonyms, and rules

Get and set settings

Kotlin

// version 2
val index = client.initIndex(IndexName("ALGOLIA_INDEX_NAME"))
val settings = index.getSettings()
index.setSettings(settings { searchableAttributes { +"title"; +"author" } })

// version 3
val settings = client.getSettings(
    indexName = "ALGOLIA_INDEX_NAME"
)
client.setSettings(
    indexName = "ALGOLIA_INDEX_NAME",
    indexSettings = IndexSettings(
        searchableAttributes = listOf("title", "author")
    )
)

Save synonyms and rules

Kotlin

// version 2
val index = client.initIndex(IndexName("ALGOLIA_INDEX_NAME"))
index.saveSynonyms(
    listOf(SynonymMultiWay(ObjectID("1"), listOf("car", "auto")))
)

// version 3
client.saveSynonyms(
    indexName = "ALGOLIA_INDEX_NAME",
    synonymHit = listOf(
        SynonymHit(
            objectID = "1",
            type = SynonymType.entries.first { it.value == "synonym" },
            synonyms = listOf("car", "auto")
        )
    )
)

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

// version 2
client.copyIndex(IndexName("SOURCE_INDEX_NAME"), IndexName("DESTINATION_INDEX_NAME"))

// version 3
client.operationIndex(
    indexName = "SOURCE_INDEX_NAME",
    operationIndexParams = OperationIndexParams(
        operation = OperationType.entries.first { it.value == "copy" },
        destination = "DESTINATION_INDEX_NAME"
    )
)

Move (rename) an index

Kotlin

// version 2
client.moveIndex(IndexName("SOURCE_INDEX_NAME"), IndexName("DESTINATION_INDEX_NAME"))

// version 3
client.operationIndex(
    indexName = "SOURCE_INDEX_NAME",
    operationIndexParams = OperationIndexParams(
        operation = OperationType.entries.first { it.value == "move" },
        destination = "DESTINATION_INDEX_NAME"
    )
)

Copy only rules or settings

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

Kotlin

// version 3: copy only rules and settings from one index to another
client.operationIndex(
    indexName = "SOURCE_INDEX_NAME",
    operationIndexParams = OperationIndexParams(
        operation = OperationType.entries.first { it.value == "copy" },
        destination = "DESTINATION_INDEX_NAME",
        scope = listOf(
            ScopeType.entries.first { it.value == "rules" },
            ScopeType.entries.first { it.value == "settings" }
        )
    )
)

Update task handling

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

Kotlin

// version 2
val index = client.initIndex(IndexName("ALGOLIA_INDEX_NAME"))
index.apply {
    saveObjects(Contact.serializer(), records).wait()
}

// version 3
val response = client.saveObject(
    indexName = "ALGOLIA_INDEX_NAME",
    body = record
)
client.waitForTask(indexName = "ALGOLIA_INDEX_NAME", taskID = response.taskID)

Version 3 includes three wait helpers:

waitForTask: wait until indexing operations are done.
waitForAppTask: wait for application-level tasks.
waitForApiKey: wait for API key operations.

Method changes reference

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

Search API client

Version 2 (legacy)		Version 3 (current)
`client.addAPIKey`	→	`client.addApiKey`
`client.addAPIKey.wait`	→	`client.waitForApiKey`
`client.clearDictionaryEntries`	→	`client.batchDictionaryEntries`
`client.copyIndex`	→	`client.operationIndex`
`client.copyRules`	→	`client.operationIndex`
`client.copySynonyms`	→	`client.operationIndex`
`client.deleteAPIKey`	→	`client.deleteApiKey`
`client.deleteDictionaryEntries`	→	`client.batchDictionaryEntries`
`client.generateAPIKey`	→	`client.generateSecuredApiKey`
`client.getAPIKey`	→	`client.getApiKey`
`client.getSecuredAPIKeyRemainingValidity`	→	`client.getSecuredApiKeyRemainingValidity`
`client.listAPIKeys`	→	`client.listApiKeys`
`client.listIndices`	→	`client.listIndices`
`client.moveIndex`	→	`client.operationIndex`
`client.multipleBatchObjects`	→	`client.multipleBatch`
`client.multipleQueries`	→	`client.search`
`client.replaceDictionaryEntries`	→	`client.batchDictionaryEntries`
`client.restoreAPIKey`	→	`client.restoreApiKey`
`client.saveDictionaryEntries`	→	`client.batchDictionaryEntries`
`client.updateAPIKey`	→	`client.updateApiKey`
`index.batch`	→	`client.batch`
`index.clearObjects`	→	`client.clearObjects`
`index.clearRules`	→	`client.clearRules`
`index.clearSynonyms`	→	`client.clearSynonyms`
`index.copySettings`	→	`client.operationIndex`
`index.delete`	→	`client.deleteIndex`
`index.deleteBy`	→	`client.deleteBy`
`index.deleteObject`	→	`client.deleteObject`
`index.deleteObjects`	→	`client.deleteObjects`
`index.deleteRule`	→	`client.deleteRule`
`index.deleteSynonym`	→	`client.deleteSynonym`
`index.findObject`	→	`client.searchSingleIndex`
`index.getObject`	→	`client.getObject`
`index.getObjects`	→	`client.getObjects`
`index.getRule`	→	`client.getRule`
`index.getSettings`	→	`client.getSettings`
`index.getSynonym`	→	`client.getSynonym`
`index.getTask`	→	`client.getTask`
`index.partialUpdateObject`	→	`client.partialUpdateObject`
`index.partialUpdateObjects`	→	`client.partialUpdateObjects`
`index.replaceAllObjects`	→	`client.replaceAllObjects`
`index.replaceAllRules`	→	`client.saveRules`
`index.replaceAllSynonyms`	→	`client.saveSynonyms`
`index.saveObject`	→	`client.saveObject`
`index.saveObjects`	→	`client.saveObjects`
`index.saveRule`	→	`client.saveRule`
`index.saveRules`	→	`client.saveRules`
`index.saveSynonym`	→	`client.saveSynonym`
`index.saveSynonyms`	→	`client.saveSynonyms`
`index.search`	→	`client.searchSingleIndex`
`index.searchForFacets`	→	`client.searchForFacetValues`
`index.searchRules`	→	`client.searchRules`
`index.searchSynonyms`	→	`client.searchSynonyms`
`index.setSettings`	→	`client.setSettings`
`index.{operation}.wait`	→	`client.waitForTask`

Version 2 (legacy)		Version 3 (current)
`client.getFrequentlyBoughtTogether`	→	`client.getRecommendations`
`client.getRecommendations`	→	`client.getRecommendations`
`client.getRelatedProducts`	→	`client.getRecommendations`

API clients (current)

Clients and methods

Upgrade the Kotlin API client to version 3

Update your dependencies

Update imports

Update client initialization

Remove `initIndex`

Replace the domain-specific language

Query parameters

Settings

Filters

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

​Remove initIndex

​Replace the domain-specific language

​Query parameters

​Settings

​Filters

​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

Remove `initIndex`

Replace the domain-specific language

Query parameters

Settings

Filters

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