API clients / Scala

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 SearchClientExtensions package:

Copy 
1

import algoliasearch.extension.SearchClientExtensions

Browse for records

Required ACL: browse

Retrieves all records from an index.

This helper method iterates over the paginated API response from the Browse API operation and lets you run an aggregator function on every iteration.

You can use this, for example, to retrieve all records from your index.

Copy 
1
2
3
4
5
6
7

def browseObjects(
  indexName: String,
  browseParams: BrowseParamsObject,
  validate: BrowseResponse => Boolean,
  aggregator: (BrowseResponse) => Unit,
  requestOptions: Option[RequestOptions],
): Future[BrowseResponse]

Parameters

indexName
type: String
Required

Index name from which to get all records.
browseParams
type: BrowseParamsObject
Required

Parameters for the Browse request.
aggregator
type: BrowseResponse => Unit
Required

A function that runs on every iteration, for example, to aggregate all records from the response.
validate
type: BrowseResponse => Boolean
default: response => response.cursor.isEmpty

A function that takes the API response and returns true when the iteration should stop. By default, the iteration stops if the response does not contain a cursor property.
requestOptions
type: Option[RequestOptions]
default: None

Extra parameters, such as headers or timeouts. For more information, see Request options.

Browse for rules

Required ACL: settings

Retrieves all rules from an index.

This helper method iterates over the paginated API response from the Search for rules API operation and lets you run an aggregator function on every iteration.

You can use this, for example, to retrieve all rules from your index.

Copy 
1
2
3
4
5
6
7

def browseRules(
  indexName: String,
  searchRulesParams: SearchRulesParams,
  validate: Option[SearchRulesResponse => Boolean],
  aggregator: SearchRulesResponse => Unit,
  requestOptions: Option[RequestOptions]
): Future[SearchRulesResponse]

Parameters

indexName
type: String
Required

Index name from which to get all rules.
searchRulesParams
type: SearchRulesParams
Required

Parameters for the Search for rules request.
aggregator
type: SearchRulesResponse => Unit
Required

A function that runs on every iteration, for example, to aggregate all rules from the response.
validate
type: Option[SearchRulesResponse => Boolean]
default: None

A function that takes the API response and returns true when the iteration should stop. By default, the iteration stops if the number of rules returned by the response is smaller than the hitsPerPage parameter.
requestOptions
type: Option[RequestOptions]
default: None

Extra parameters, such as headers or timeouts. For more information, see Request options.

Browse for synonyms

Required ACL: settings

Retrieves all synonyms from an index.

This helper method iterates over the paginated API response from the Search for synonyms API operation and lets you run an aggregator function on every iteration.

You can use this, for example, to retrieve all synonyms from your index.

Copy 
1
2
3
4
5
6
7

def browseSynonyms(
  indexName: String,
  searchSynonymsParams: SearchSynonymsParams,
  validate: Option[SearchSynonymsResponse => Boolean],
  aggregator: SearchSynonymsResponse => Unit,
  requestOptions: Option[RequestOptions],
): Future[SearchSynonymsResponse]

Parameters

indexName
type: String
Required

Index name from which to get all synonyms.
searchSynonymsParams
type: SearchSynonymsParams

Parameters for the Search for synonyms request.
aggregator
type: SearchSynonymsResponse => Unit
Required

A function that runs on every iteration, for example, to aggregate all synonyms from the response.
validate
type: Option[SearchSynonymsResponse => Boolean]
default: None

A function that takes the API response and returns true when the iteration should stop. By default, the iteration stops if the number of synonyms returned by the response is smaller than the hitsPerPage parameter.
requestOptions
type: Option[RequestOptions]
default: None

Extra parameters, such as headers or timeouts. For more information, see Request options.

Delete records

Required ACL: deleteObject

Deletes records from an index using their object IDs.

This helper function creates batch write requests with deleteObject actions and sends these requests in batches of 1,000.

Copy 
1
2
3
4
5
6

def deleteObjects(
  indexName: String,
  objectIDs: Seq[String],
  waitForTasks: Boolean,
  requestOptions: Option[RequestOptions],
): Future[Seq[BatchResponse]]

Parameters

indexName
type: String
Required

Index name from which to delete records.
objectIDs
type: Seq
items: String
Required

Object IDs to delete.
waitForTasks
type: Boolean
default: false

Whether to wait until all tasks created by this method are completed.
requestOptions
type: Option[RequestOptions]
default: None

Extra parameters, such as headers or timeouts. For more information, see Request options.

Check if index exists

Required ACL: settings

Checks whether an index exists.

This helper method makes a request to the Retrieve index settings endpoint, and returns true if that request returns a success response.

Copy 
1
2
3

def indexExists(
  indexName: String
): Future[Boolean]

Parameters

indexName
type: String
Required

Index name to check.

Update attributes of records

Required ACL: addObject

Adds or updates attributes of records

This helper function creates batch write requests with partialUpdateObject or partialUpdateObjectNoCreate actions (depending on whether the createIfNotExists option is true or false) and sends these requests in batches of 1,000.

The underlying method is subject to indexing rate limits.

Copy 
1
2
3
4
5
6
7

def partialUpdateObjects(
  indexName: String,
  objects: Seq[Any],
  createIfNotExists: Boolean,
  waitForTasks: Boolean,
  requestOptions: Option[RequestOptions],
): Future[Seq[BatchResponse]]

Parameters

indexName
type: String
Required

Index name where to update records.
objects
type: Seq
items: Any
Required

Records to update
createIfNotExists
type: Boolean
default: false

Whether to create new records if they don’t exist yet.
waitForTasks
type: bool
default: false

Whether to wait until all tasks created by this method are completed.
requestOptions
type: Option[RequestOptions]
default: None

Extra parameters, such as headers or timeouts. For more information, see Request options.

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 combines batch, copy, and move requests:

  1. Copy settings, synonyms, and rules to a temporary index.
  2. Add the records from the objects parameter to the temporary index.
  3. Replace the original index with the temporary index (move).

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).

The underlying methods are subject to indexing rate limits.

The resolved response from this method contains the API responses from the individual requests:

Copy 
1
2
3
4
5

case class ReplaceAllObjectsResponse(
  copyOperationResponse: UpdatedAtResponse,
  batchResponses: Seq[BatchResponse],
  moveOperationResponse: UpdatedAtResponse
)
Copy 
1
2
3
4
5
6

def replaceAllObjects(
  indexName: String,
  objects: Seq[Any],
  batchSize: Int,
  requestOptions: Option[RequestOptions]
): Future[ReplaceAllObjectResponse]

Parameters

indexName
type: String
Required

Index name where to replace all records.
objects
type: Seq
items: Any
Required

Records that replace the existing records in your index.
batchSize
type: int
default: 1,000

Batch size for the indexing operation.
requestOptions
type: Option[RequestOptions]
default: None

Extra parameters, such as headers or timeouts. For more information, see Request options.

Save records

Required ACL: addObject

Adds records to an index.

This helper method creates batch write request with addObject actions and sends these requests in batches of 1,000.

The underlying method is subject to indexing rate limits.

Copy 
1
2
3
4
5
6

def saveObjects(
  indexName: String,
  objects: Seq[Any],
  waitForTasks: Boolean,
  requestOptions: Option[RequestOptions],
): Future[Seq[BatchResponse]]

Parameters

indexName
type: String
Required

Index name to which to add records.
objects
type: Seq
items: Any
Required

Records to add.
waitForTasks
type: bool
default: false

Whether to wait until all tasks created by this method are completed.
requestOptions
type: Option[RequestOptions]
default: None

Extra parameters, such as headers or timeouts. For more information, see Request options.

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.

Copy 
1
2
3
4
5
6
7
8

def waitForApiKey(
  operation: ApiKeyOperation,
  key: String,
  apiKey: Option[ApiKey],
  maxRetries: Int,
  delay: Long => Long,
  requestOptions: Option[RequestOptions]
): Future[Any]

Parameters

operation
type: ApiKeyOperation
Required

The type of operation to wait for:

  • ApiKeyOperation.Add. Wait for the addition of a new API key
  • ApiKeyOperation.Update. Wait for the update of an existing API key
  • ApiKeyOperation.Delete. Wait for the deletion of an API key.
key
type: String
Required

The API key that was added, updated, or deleted. For example, you can get this value from the API response when creating or updating.
apiKey
type: ApiKey
default: None

When waiting for an API key to be updated, apiKey expects the original ApiKey object you passed to the Update API key operation.
maxRetries
type: int
default: 50

Maximum number of times the task status is checked.
delay
type: Long => Long
default: (retries: Long) => Math.min(retries * 200, 5000)

Sets the waiting time between iteration. By default, the initial delay is 200 millisecond, which is increased with every iteration until the maximum of 5 seconds.
requestOptions
type: Option[RequestOptions]
default: None

When waiting for an API key to be updated, apiKey expects the original ApiKey object you passed to the Update API key operation.
maxRetries
type: int
default: 50

Maximum number of times the task status is checked.
delay
type: Long => Long
default: (retries: Long) => Math.min(retries * 200, 5000)

Sets the waiting time between iteration. By default, the initial delay is 200 millisecond, which is increased with every iteration until the maximum of 5 seconds.
requestOptions
type: RequestOptions?
default: null

Extra parameters, such as headers or timeouts. For more information, see Request options.

Wait for application-level tasks

Waits for an application-level task to complete.

Some tasks are application-level tasks, such as working with dictionaries. 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.

Copy 
1
2
3
4
5
6

def waitAppTask(
  taskID: Long,
  maxRetries: Int,
  delay: Long => Long,
  requestOptions Option[RequestOptions],
): Future[TaskStatus]

Parameters

taskID
type: Long
Required

Task ID for which to wait.
maxRetries
type: Int
default: 50

Maximum number of times the task status should be checked.
delay
type: Long => Long
default: (retries: Long) => Math.min(retries * 200, 5000)

Sets the waiting time between iteration. By default, the initial delay is 200 millisecond, which is increased with every iteration until the maximum of 5 seconds.
requestOptions
type: Option[RequestOptions]
default: None

Extra parameters, such as headers or timeouts. For more information, see Request options.

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.

Copy 
1
2
3
4
5
6
7

def waitTask(
  indexName: String,
  taskID: Long,
  maxRetries: Int,
  delay: Long => Long,
  requestOptions: Option[RequestOptions],
): Future[TaskStatus]

Parameters

indexName
type: String
Required

Index name for which to check the task.
taskID
type: Long
Required

Task ID for which to wait.
maxRetries
type: Int
default: 50

Maximum number of times the task status should be checked.
delay
type: Long => Long
default: (retries: Long) => Math.min(retries * 200, 5000)

Sets the waiting time between iteration. By default, the initial delay is 200 millisecond, which is increased with every iteration until the maximum of 5 seconds.
requestOptions
type: Option[RequestOptions]
default: None

Extra parameters, such as headers or timeouts. For more information, see Request options.
Did you find this page helpful?