⚡️ A fully-featured and blazing-fast Kotlin/Android API client to interact with Algolia.
Documentation • Community Forum • Stack Overflow • Report a bug • FAQ • Support
1.6
and higher.SearchClient
, AnalyticsClient
, and InsightsClient
in a multithreaded environment.Install the Kotlin client by adding the following dependency to your gradle.build
file:
repositories {
mavenCentral()
}
dependencies {
implementation "com.algolia:algoliasearch-client-kotlin:$kotlin_client_version"
}
Also, choose and add to your dependencies one of Ktor http client engines.
Alternatively, you can use algoliasearch-client-kotlin-bom.
For full documentation, visit the Algolia Kotlin API Client.
ℹ️ Please follow the migration guide to migrate from 1.x
to the latest version.
All methods performing HTTP calls in the Kotlin client are suspending functions. This means these functions can only be called from a coroutine.
In the example below, a coroutine is launched in the main thread. The context is switched to a thread pool to perform the search HTTP call off the main thread. The response can be manipulated from the main thread.
class Searcher : CoroutineScope {
override val coroutineContext = Job()
fun search() {
launch(Dispatchers.Main) {
val response = withContext(Dispatchers.Default) { index.search() }
}
}
}
The developer is responsible for implementing the asynchronous logic that matches their specific requirements. The Kotlin client doesn't execute HTTP calls on any particular thread, it is up to the developer to define it explicitly using coroutines. Learn more about coroutines.
Waiting for an asynchronous server task is made available via a function literal with receiver.
Use the apply or run functions on your index or client.
index.apply {
setSettings(Settings()).wait()
}
client.run {
multipleBatchObjects(listOf<BatchOperationIndex>()).waitAll()
}
The wait
functions are suspending, and should only be called from a coroutine.
Response and parameters objects are typed to provide extensive compile time safety coverage.
Example for creating a Client instance without mixing the application ID and the API key.
val appID = ApplicationID("YourApplicationID")
val apiKey = APIKey("YourAdminAPIKey")
val client = ClientSearch(appID, apiKey)
Example for attributes:
val color = Attribute("color")
val category = Attribute("category")
Query(
attributesToRetrieve = listOf(color, category)
)
Sealed class are used to represent enumerated types. It allows to quickly discover possible values for each type thanks to IDE autocomplete support.
All sealed class have an Other
class case for avoiding runtime crashes in case of unforeseen value.
val query = Query()
query.sortFacetsBy = SortFacetsBy.Count
// query.sortFacetsBy = SortFacetsBy.Alpha
// query.sortFacetsBy = SortFacetsBy.Other("unforeseen value")
If you use this library in an Android project which uses R8, there is nothing you have to do. The specific rules are already bundled into the JAR, which can be interpreted by R8 automatically.
If however, you don’t use R8 you have to apply the rules from this file.
Encountering an issue? Before reaching out to support, we recommend heading to our FAQ where you will find answers for the most common issues and gotchas with the client.
If you want to contribute to this project without installing all its dependencies, you can use our Docker image. Please check our dedicated guide to learn more.
Algolia Kotlin API Client is an open-sourced software licensed under the MIT license.