Helper methods

Helper methods extend or combine API operations to make using the Search API easier.

Import the client extensions

To use the helper methods, import the extensions package:

1
import com.algolia.client.extensions.*

Delete records

Required ACL: deleteObject

Deletes records from an index using their object IDs.

This helper methods is based on the Batch operations on one index API operation.

It constructs the batch write request with the deleteObject action and automatically sends requests in batches of 1,000 records.

1
2
3
4
5
client.deleteObjects(
  indexName: String,
  objectIDs: List<String>,
  requestOptions: RequestOptions?,
)

Parameters

Create secured API keys

Creates a secured API key without any calls to Algolia’s servers.

This helper method takes a parent API key and adds restrictions to it, which can’t be changed at query time.

Secured API keys are forms of hash-based message authentication codes (HMAC).

This helper performs these steps to create a secured API key:

1. Compute a SHA-256 HMAC with the parent API key as secret, and a URL-encoded list of query parameters as message. These query parameters will be applied with every use of the API key and can’t be changed by users.

2. Concatenate the SHA-256 HMAC with the list of query parameters to a single string.

3. Encode the whole string in base64.

1
2
3
4
client.generateSecuredApiKey(
  parentApiKey: String,
  restrictions: SecuredApiKeyRestrictions,
)

Parameters

restrictions ➔ SecuredApiKeyRestrictions

Get secured API key remaining validity

Retrieves the time in seconds until the secured API key expires.

This helper method returns the amount of seconds left until the secured API key expires, as defined by its validUntil property. If the key already expired, this method returns a negative number, indicating the number of seconds since the key expired.

1
2
3
client.securedApiKeyRemainingValidity(
  apiKey: String,
)

Parameters

Update attributes of records

Required ACL: addObject

Adds or updates attributes of records

This helper methods is based on the Batch operations on one index API operation.

It constructs the batch write request with the partialUpdateObject or partialUpdateObjectNoCreate action (depending on the createIfNotExists option) and automatically sends requests in batches of 1,000 records.

1
2
3
4
5
6
client.partialUpdateObjects(
  indexName: String,
  objects: List<JsonObject>,
  createIfNotExists: Boolean,
  requestOptions: RequestOptions?,
)

Parameters

Replace all records

Required ACL: addObject

Replaces all records in an index with new ones.

This helper lets you replace all records in an index without interrupting the ability to search.

It’s based on the Batch indexing operations on one index and Copy or move an index API operations and performs these actions:

1. Copy settings, synonyms, and rules to a temporary index.
2. Add the records from the objects parameter to the temporary index.
3. Move the temporary index to the original index to replace it.

If you use an API key with indexes restrictions, you need to allow access to the index INDEX_NAME_tmp_* (replace INDEX_NAME with the name of your original index).

1
2
3
4
5
6
client.replaceAllObjects(
  indexName: String,
  objects: List<JsonObject>,
  batchSize: Int,
  requestOptions: RequestOptions?,
)

Parameters

Save records

Required ACL: addObject

Adds records to an index.

This helper methods is based on the Batch operations on one index API operation.

It constructs the batch write request with the addObject action and automatically sends requests in batches of 1,000 records.

1
2
3
4
5
client.saveObjects(
  indexName: String,
  objects: List<JsonObject>,
  requestOptions: RequestOptions?,
)

Parameters

Wait for API keys

Waits for an API key operation to be finished.

When you add, update, or delete API keys, it might take a while before the change is applied.

1
2
3
4
5
6
7
8
9
client.waitForApiKey(
  ApiKeyOperation operation,
  String key,
  ApiKey apiKey,
  // Optional parameter
  int maxRetries,
  IntUnaryOperator timeout,
  RequestOptions requestOptions,
)

Parameters

Examples

Wait until an API key is added:

1
2
3
4
5
6
7
8
9
import com.algolia.client.api.SearchClient
import com.algolia.client.extensions.*

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

var response = client.waitForApiKey(
  key = "api-key-add-operation-test-kotlin",
  operation = ApiKeyOperation.entries.first { it.value == "add" },
)

Wait until an API key is updated:

1
2
3
4
5
6
7
8
9
import com.algolia.client.api.SearchClient
import com.algolia.client.extensions.*

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

var response = client.waitForApiKey(
  key = "api-key-add-operation-test-kotlin",
  operation = ApiKeyOperation.entries.first { it.value == "add" },
)

Wait until an API key is deleted:

1
2
3
4
5
6
7
8
9
import com.algolia.client.api.SearchClient
import com.algolia.client.extensions.*

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

var response = client.waitForApiKey(
  key = "api-key-add-operation-test-kotlin",
  operation = ApiKeyOperation.entries.first { it.value == "add" },
)

Wait for application-level tasks

Waits for an application-level task to complete.

While indexing operations are index-level tasks, some tasks, such as working with dictionaries, are application-level tasks. They’re asynchronous: when you make a request, Algolia adds the task to a queue and runs it depending on the server load. The response includes a task_id property that you can use to wait until the task is complete.

This helper method polls the Check application task status API operation and stops if the task’s status is published.

1
2
3
4
5
6
7
8
client.waitAppTask(
  taskID: Long,
  maxRetries: Int,
  timeout: Duration,
  initialDelay: Duration,
  maxDelay: Duration
  requestOptions: RequestOptions?,
)

Parameters

Examples

1
2
3
4
5
6
7
8
import com.algolia.client.api.SearchClient
import com.algolia.client.extensions.*

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

var response = client.waitForAppTask(
  taskID = 123L,
)

Wait for index operations

Waits for an indexing task to complete.

Indexing operations are asynchronous. When you make a request for an indexing operation, such as, adding or updating records, Algolia adds a task to a queue and returns a task_id property with the response. The task itself runs separately, depending on the server load.

This helper method polls the Check task status API operation and stops if the task’s status is published.

1
2
3
4
5
6
7
8
9
client.waitTask(
  indexName: String,
  taskID: Long,
  maxRetries: Int,
  timeout: Duration,
  initialDelay: Duration,
  maxDelay: Duration,
  requestOptions: RequestOptions?,
)

Parameters

Examples

1
2
3
4
5
6
7
8
9
import com.algolia.client.api.SearchClient
import com.algolia.client.extensions.*

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

var response = client.waitForTask(
  indexName = "ALGOLIA_INDEX_NAME",
  taskID = 123L,
)