Helper methods
Helper methods extend or combine API operations to make using the Search API easier.
Browse for records
Required ACL: browse
Retrieves all records from an index.
This helper method is based on the Browse for records API operation.
It iterates over the paginated API response and returns an iterator that lets you aggregate all records.
1
2
3
4
5
6
7
SearchClient.browseObjects<T>(
indexName: String,
browseParams: BrowseParamsObject,
aggregator: (BrowseResponse<T>) -> Void,
validate: (BrowseResponse<T>) -> Bool
requestOptions: RequestOptions?,
)
Parameters
indexName
|
type: String
Required
Index name from which to get all records. |
browseParams
|
type: BrowseParamsObject
Required
Parameters for the Browse for records request. |
aggregator
|
type: (BrowseResponse<T>) -> Void
Required
A function that runs after each iteration. For example, you can use this to aggregate all records into a single list. |
validate
|
type: (BrowseResponse<T>) -> Bool
default: { response in response.cursor == nil }
A function that returns true when to stop iterating over the responses. |
T
|
type: type parameter
The model of your index’s records. |
requestOptions
|
type: RequestOptions
default: nil
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 is based on the Search for rules API operation.
It iterates over the paginated API response and returns an iterable that lets you aggregate all rules.
1
2
3
4
5
6
7
SearchClient.browseRules(
indexName: String,
searchRulesParams: SearchRulesParams,
validate: ((SearchRulesResponse) -> Bool)?,
aggregator: (SearchRulesResponse) -> Void,
requestOptions: RequestOptions?,
)
Parameters
indexName
|
type: String
Required
Index name from which to get all rules. |
searchRulesParams
|
type: SearchRulesParams
Parameters for the Search for rules request. |
aggregator
|
type: (SearchRulesResponse) -> Void
Required
A function that runs after each iteration. For example, you can use this to aggregate all records into a single list. |
validate
|
type: (SearchRulesResponse) -> Bool
default: nil
A function that returns true when to stop iterating over the responses. |
requestOptions
|
type: RequestOptions
default: nil
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 is based on the Search for synonyms API operation.
It iterates over the paginated API response and aggregates all synonyms.
1
2
3
4
5
6
7
SearchClient.browseSynonyms(
indexName: String,
searchSynonymsParams: SearchSynonymsParams ,
validate: ((SearchSynonymsResponse) -> Bool)?,
aggregator: (SearchSynonymsResponse) -> Void,
requestOptions: RequestOptions?,
)
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: (SearchRulesResponse) -> Void
Required
A function that runs after each iteration. For example, you can use this to aggregate all records into a single list. |
validate
|
type: (SearchRulesResponse) -> Bool
default: nil
A function that returns true when to stop iterating over the responses. |
requestOptions
|
type: RequestOptions
default: nil
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 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
SearchClient.deleteObjects(
indexName: String,
objectIDs: [String],
requestOptions: RequestOptions?,
)
Parameters
indexName
|
type: String
Required
Index name from which to delete records. |
objectIDs
|
type: Array
items: String
Required
Object IDs to delete. |
requestOptions
|
type: RequestOptions
default: nil
Extra parameters, such as headers or timeouts. For more information, see Request options. |
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:
-
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.
-
Concatenate the SHA-256 HMAC with the list of query parameters to a single string.
-
Encode the whole string in
base64
.
1
2
3
4
SearchClient.generateSecuredApiKey(
parentApiKey: String,
restrictions: SecuredApiKeyRestrictions,
)
Parameters
parentApiKey
|
type: String
Required
The API key to be used as secret for the secured API key. The secured API key inherits all restrictions from this API key. You can’t use an Admin API key. |
restrictions
|
type: SecuredApiKeyRestrictions
Restrictions to apply to the secured API key.
You must add at least one restriction.
If you make requests with a secured API key with the same restrictions as the |
restrictions ➔ SecuredApiKeyRestrictions
searchParams
|
type: SearchParamsObject
Search parameters that will always be applied with this API key. For more information, see Search. |
filters
|
type: String
Filters that will always be applied with this API key. |
validUntil
|
type: Int
Timestamp when the API key expires, in seconds since the Unix epoch. |
restrictIndices
|
type: Array
items: String
Index names that this API key should be allowed to access.
You can use the wildcard character |
restrictSources
|
type: String
IP network range that is allowed to use this API key. |
userToken
|
type: String
Pseudonymous user identifier to restrict usage of this API key to specific users. By default, rate limits are set based on IP addresses. This can be an issue if many users search from the same IP address. To avoid this, add a user token to each generated API key. |
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
SearchClient.getSecuredApiKeyRemainingValidity(
securedApiKey: String,
)
Parameters
securedApiKey
|
type: String
Required
Secured API key for which to retrieve the time of validity. |
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 whether the create_if_not_exists
option is true or false)
and automatically sends requests in batches of 1,000 records.
1
2
3
4
5
6
SearchClient.partialUpdateObjects(
indexName: String,
objects: [some Encodable],
Bool createIfNotExists,
requestOptions: RequestOptions?,
)
Parameters
indexName
|
type: String
Required
Index name where to update records. |
objects
|
type: Array
items: Encodable
Required
Records to update |
createIfNotExists
|
type: Bool
default: false
Whether to create a new record if it doesn’t exist. |
requestOptions
|
type: RequestOptions
default: nil
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’s based on the Batch indexing operations on one index and Copy or move an index API operations and performs these actions:
- Copy settings, synonyms, and rules to a temporary index.
- Add the records from the
objects
parameter to the temporary index. - 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
SearchClient.replaceAllObjects(
indexName: String,
objects: [some Encodable],
batchSize: Int,
requestOptions: RequestOptions?,
)
Parameters
indexName
|
type: String
Required
Index name where to replace all records. |
objects
|
type: Array
items: Encodable
Required
Records that replace the existing records in your index. |
batchSize
|
type: Int
default: 1000
Batch size for the indexing operation. |
requestOptions
|
type: RequestOptions
default: nil
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 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
SearchClient.saveObjects(
indexName: String,
objects: [some Encodable],
requestOptions: RequestOptions?,
)
Parameters
indexName
|
type: String
Required
Index name to which to add records. |
objects
|
type: Array
items: Encodable
Required
Records to add. |
requestOptions
|
type: RequestOptions
default: nil
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.
1
2
3
4
5
6
7
8
SearchClient.waitForApiKey(
key: String,
operation: ApiKeyOperation,
apiKey: ApiKey?,
maxRetries: Int,
timeout: (Int) -> TimeInterval,
requestOptions: RequestOptions?,
)
Parameters
key
|
type: String
Required
The API key that was added, update, or deleted. For example, you can get this value from the API response when creating or updating. |
operation
|
type: ApiKeyOperation
Required
The type of operation to wait for:
|
apiKey
|
type: ApiKey
default: nil
When waiting for an API key to be updated,
|
maxRetries
|
type: Int
default: 50
Maximum number of times the task status should be checked. |
timeout
|
type: (Int) -> TimeInterval
default: min(TimeInterval(retryCount) * 0.2, 5)
A function that takes one parameter, the current number of retries, and returns the number of seconds after which to check the task’s status again. |
requestOptions
|
type: RequestOptions
default: nil
Extra parameters, such as headers or timeouts. For more information, see Request options. |
Examples
Wait until an API key is added:
1
2
3
4
5
6
7
8
import Search
let client = try SearchClient(appID: "ALGOLIA_APPLICATION_ID", apiKey: "ALGOLIA_API_KEY")
let response = try await client.waitForApiKey(
key: "api-key-add-operation-test-swift",
operation: ApiKeyOperation.add
)
Wait until an API key is updated:
1
2
3
4
5
6
7
8
import Search
let client = try SearchClient(appID: "ALGOLIA_APPLICATION_ID", apiKey: "ALGOLIA_API_KEY")
let response = try await client.waitForApiKey(
key: "api-key-add-operation-test-swift",
operation: ApiKeyOperation.add
)
Wait until an API key is deleted:
1
2
3
4
5
6
7
8
import Search
let client = try SearchClient(appID: "ALGOLIA_APPLICATION_ID", apiKey: "ALGOLIA_API_KEY")
let response = try await client.waitForApiKey(
key: "api-key-add-operation-test-swift",
operation: ApiKeyOperation.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
SearchClient.waitForAppTask(
taskID: Int64,
maxRetries: Int,
timeout: (Int) -> TimeInterval,
requestOptions: RequestOptions?,
)
Parameters
taskID
|
type: Int64
Required
Task ID for which to wait. |
maxRetries
|
type: Int
default: 50
Maximum number of times the task status should be checked. |
timeout
|
type: (Int) -> TimeInterval
default: min(TimeInterval(retryCount) * 0.2, 5)
A function that takes one parameter, the current number of retries, and returns the number of seconds after which to check the task’s status again. |
requestOptions
|
type: RequestOptions
default: nil
Extra parameters, such as headers or timeouts. For more information, see Request options. |
Examples
1
2
3
4
5
import Search
let client = try SearchClient(appID: "ALGOLIA_APPLICATION_ID", apiKey: "ALGOLIA_API_KEY")
let response = try await client.waitForAppTask(taskID: Int64(123))
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
SearchClient.waitForTask(
indexName: String,
taskID: Int64,
maxRetries: Int,
timeout: (Int) -> TimeInterval,
requestOptions: RequestOptions?,
)
Parameters
indexName
|
type: String
Required
Index name for which to check the task. |
taskID
|
type: Int64
Required
Task ID for which to wait. |
maxRetries
|
type: Int
default: 50
Maximum number of times the task status should be checked. |
timeout
|
type: (Int) -> TimeInterval
default: min(TimeInterval(retryCount) * 0.2, 5)
A function that takes one parameter, the current number of retries, and returns the number of seconds after which to check the task’s status again. |
requestOptions
|
type: RequestOptions
default: nil
Extra parameters, such as headers or timeouts. For more information, see Request options. |
Examples
1
2
3
4
5
import Search
let client = try SearchClient(appID: "ALGOLIA_APPLICATION_ID", apiKey: "ALGOLIA_API_KEY")
let response = try await client.waitForTask(indexName: "ALGOLIA_INDEX_NAME", taskID: Int64(123))