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 iterates over the paginated API response from the Browse API operation.

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

1
2
3
4
5
6
public <T> Iterable<T> browseObjects(
  String indexName,
  BrowseParamsObject params,
  Class<T> innerType,
  RequestOptions requestOptions,
)

Parameters

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. You can use this, for example, to retrieve all rules from your index.

1
2
3
4
5
public Iterable<Rule> browseRules(
  String indexName,
  SearchRulesParams searchRulesParams,
  RequestOptions requestOptions,
)

Parameters

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. You can use this, for example, to retrieve all synonyms from your index.

1
2
3
4
5
public Iterable<Synonym> browseSynonyms(
  String indexName,
  SearchSynonymsParams searchSynonymsParams,
  RequestOptions requestOptions,
)

Parameters

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.

1
2
3
4
5
6
public List<BatchResponse> deleteObjects(
  String indexName,
  List<String> objectIDs,
  boolean waitForTasks,
  RequestOptions requestOptions,
)

Examples

1
2
3
4
5
6
import com.algolia.api.SearchClient;
import com.algolia.config.*;

SearchClient client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

client.deleteObjects("ALGOLIA_INDEX_NAME", Arrays.asList("1", "2"));

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
public String generateSecuredApiKey(
  String parentApiKey,
  SecuredApiKeyRestrictions restrictions,
)

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 number 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
public Duration getSecuredApiKeyRemainingValidity(
  String securedApiKey,
)

Parameters

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.

1
2
3
public boolean indexExists(
  String indexName,
)

Examples

1
2
3
4
5
6
import com.algolia.api.SearchClient;
import com.algolia.config.*;

SearchClient client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

client.indexExists("ALGOLIA_INDEX_NAME");

Parameters

Update attributes of records

Required ACL: addObject

Adds or updates attributes of records

This helper method 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.

1
2
3
4
5
6
7
public <T> List<BatchResponse> partialUpdateObjects(
  String indexName,
  Iterable<T> objects,
  boolean createIfNotExists,
  boolean waitForTasks,
  RequestOptions requestOptions,
)

Examples

With createIfNotExists true:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import com.algolia.api.SearchClient;
import com.algolia.config.*;

SearchClient client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

client.partialUpdateObjects(
  "ALGOLIA_INDEX_NAME",
  Arrays.asList(
    new HashMap() {
      {
        put("objectID", "1");
        put("name", "Adam");
      }
    },
    new HashMap() {
      {
        put("objectID", "2");
        put("name", "Benoit");
      }
    }
  ),
  true
);

With createIfNotExists false:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import com.algolia.api.SearchClient;
import com.algolia.config.*;

SearchClient client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

client.partialUpdateObjects(
  "ALGOLIA_INDEX_NAME",
  Arrays.asList(
    new HashMap() {
      {
        put("objectID", "3");
        put("name", "Cyril");
      }
    },
    new HashMap() {
      {
        put("objectID", "4");
        put("name", "David");
      }
    }
  ),
  false
);

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 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 response from this method contains the API responses from the individual requests:

1
2
3
4
5
public class ReplaceAllObjectsResponse {
  private UpdatedAtResponse copyOperationResponse;
  private List<BatchResponse> batchResponses;
  private UpdatedAtResponse moveOperationResponse;
}

You can access each response via getter methods.

1
2
3
4
5
6
public <T> ReplaceAllObjectsResponse replaceAllObjects(
  String indexName,
  Iterable<T> objects,
  int batchSize,
  RequestOptions requestOptions,
)

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
import com.algolia.api.SearchClient;
import com.algolia.config.*;

SearchClient client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

client.replaceAllObjects(
  "ALGOLIA_INDEX_NAME",
  Arrays.asList(
    new HashMap() {
      {
        put("objectID", "1");
        put("name", "Adam");
      }
    },
    new HashMap() {
      {
        put("objectID", "2");
        put("name", "Benoit");
      }
    },
    new HashMap() {
      {
        put("objectID", "3");
        put("name", "Cyril");
      }
    },
    new HashMap() {
      {
        put("objectID", "4");
        put("name", "David");
      }
    },
    new HashMap() {
      {
        put("objectID", "5");
        put("name", "Eva");
      }
    },
    new HashMap() {
      {
        put("objectID", "6");
        put("name", "Fiona");
      }
    },
    new HashMap() {
      {
        put("objectID", "7");
        put("name", "Gael");
      }
    },
    new HashMap() {
      {
        put("objectID", "8");
        put("name", "Hugo");
      }
    },
    new HashMap() {
      {
        put("objectID", "9");
        put("name", "Igor");
      }
    },
    new HashMap() {
      {
        put("objectID", "10");
        put("name", "Julia");
      }
    }
  ),
  3
);

Parameters

Save records

Required ACL: addObject

Adds records to an index.

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

The underlying method is subject to indexing rate limits.

1
2
3
4
5
6
public <T> List<BatchResponse> saveObjects(
  String indexName,
  Iterable<T> objects,
  boolean waitForTasks,
  RequestOptions requestOptions,
)

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import com.algolia.api.SearchClient;
import com.algolia.config.*;

SearchClient client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

client.saveObjects(
  "ALGOLIA_INDEX_NAME",
  Arrays.asList(
    new HashMap() {
      {
        put("objectID", "1");
        put("name", "Adam");
      }
    },
    new HashMap() {
      {
        put("objectID", "2");
        put("name", "Benoit");
      }
    }
  )
);

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
public GetApiKeyResponse waitForApiKey(
  String key,
  ApiKeyOperation operation,
  ApiKey apiKey,
  int maxRetries,
  IntUnaryOperator timeout,
  RequestOptions requestOptions,
)

Examples

Wait until an API key is added:

1
2
3
4
5
6
import com.algolia.api.SearchClient;
import com.algolia.config.*;

SearchClient client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

client.waitForApiKey("api-key-add-operation-test-java", ApiKeyOperation.ADD);

Wait until an API key is updated:

1
2
3
4
5
6
import com.algolia.api.SearchClient;
import com.algolia.config.*;

SearchClient client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

client.waitForApiKey("api-key-add-operation-test-java", ApiKeyOperation.ADD);

Wait until an API key is deleted:

1
2
3
4
5
6
import com.algolia.api.SearchClient;
import com.algolia.config.*;

SearchClient client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

client.waitForApiKey("api-key-add-operation-test-java", ApiKeyOperation.ADD);

Parameters

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 taskID 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
public GetTaskResponse waitForAppTask(
  Long taskID,
  int maxRetries,
  IntUnaryOperator timeout,
  RequestOptions requestOptions,
)

Examples

1
2
3
4
5
6
import com.algolia.api.SearchClient;
import com.algolia.config.*;

SearchClient client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

client.waitForAppTask(123L);

Parameters

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 taskID 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
public GetTaskResponse waitForTask(
  String indexName,
  Long taskID,
  int maxRetries,
  IntUnaryOperator timeout,
  RequestOptions requestOptions,
)

Examples

1
2
3
4
5
6
import com.algolia.api.SearchClient;
import com.algolia.config.*;

SearchClient client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

client.waitForTask("ALGOLIA_INDEX_NAME", 123L);

Parameters