Upgrade the Java API client to version 4

Keep your Java API client up to date to benefit from improvements and bug fixes.

The latest major version of the algoliasearch package is version 4. This page helps you upgrade from version 3 and explains the breaking changes you need to address.

Algolia generates the version 4 clients from OpenAPI specifications, which provides consistent behavior across all languages and up-to-date API coverage. The main architectural change is the removal of the initIndex pattern: all methods are now on the client instance directly, with indexName as a parameter.

For the full list of changes, see the Java changelog.

Update your dependencies

Version 4 consolidates the separate algoliasearch-core and HTTP client packages into a single algoliasearch artifact. You no longer need algoliasearch-apache or algoliasearch-java-net.

Maven

Replace your Algolia dependencies in pom.xml:

pom.xml

<!-- version 3 -->
<dependency>
  <groupId>com.algolia</groupId>
  <artifactId>algoliasearch-core</artifactId>
</dependency>
<dependency>
  <groupId>com.algolia</groupId>
  <artifactId>algoliasearch-apache</artifactId>
</dependency>

<!-- version 4 -->
<dependency>
  <groupId>com.algolia</groupId>
  <artifactId>algoliasearch</artifactId>
</dependency>

Gradle

Update your build.gradle file:

build.gradle

// version 3
implementation 'com.algolia:algoliasearch-core:VERSION'
implementation 'com.algolia:algoliasearch-apache:VERSION'

// version 4
implementation 'com.algolia:algoliasearch:VERSION'

Find the latest version on Maven Central.

Update imports

The package structure changed. Client classes moved from com.algolia.search to com.algolia.api, and model classes moved to com.algolia.model.search.

Java

// version 3
import com.algolia.search.DefaultSearchClient;
import com.algolia.search.SearchClient;
import com.algolia.search.SearchIndex;
import com.algolia.search.models.indexing.Query;
import com.algolia.search.models.indexing.SearchResult;

// version 4
import com.algolia.api.SearchClient;
import com.algolia.model.search.*;

Version 4 also includes dedicated client classes for each API:

Java

// Search API
import com.algolia.api.SearchClient;
// Recommend API
import com.algolia.api.RecommendClient;
// A/B testing API
import com.algolia.api.AbtestingClient;
// Analytics API
import com.algolia.api.AnalyticsClient;
// Personalization API
import com.algolia.api.PersonalizationClient;
// Query Suggestions API
import com.algolia.api.QuerySuggestionsClient;

Update client initialization

In version 3, the DefaultSearchClient.create() factory method created the client. Version 4 removes this factory. Use the SearchClient constructor instead.

Java

// version 3
SearchClient client = DefaultSearchClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

// version 4
var client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");

The version 4 client implements Closeable. Use try-with-resources to ensure the client is properly closed:

Java

// version 4 (recommended)
try (var client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")) {
    // use client
}

Understand the new API surface

Version 4 introduces two major changes to the API surface:

• No more initIndex. In version 3, the client created a typed SearchIndex<T> object with methods called on it. In version 4, the SearchIndex class is gone. All methods belong to the client instance, with indexName as a parameter.
• Generic type parameter moves to each method call. In version 3, you set the result type once on initIndex("INDEX", Record.class). In version 4, you pass the target class (for example, Hit.class) as the last argument to each method that returns typed results, such as searchSingleIndex or getObject.

Java

// version 3
SearchClient client = DefaultSearchClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");
SearchIndex<Record> index = client.initIndex("ALGOLIA_INDEX_NAME", Record.class);
index.search(new Query("QUERY"));

// version 4
var client = new SearchClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY");
client.searchSingleIndex(
    "ALGOLIA_INDEX_NAME",
    new SearchParamsObject().setQuery("QUERY"),
    Hit.class
);

If you have many files to update, search your codebase for initIndex or .initIndex( to find every place that needs changing.

Update search calls

Search a single index

The index.search() method is now client.searchSingleIndex(). Pass the index name, a SearchParamsObject, and the target class:

Java

// version 3
SearchIndex<Record> index = client.initIndex("ALGOLIA_INDEX_NAME", Record.class);
SearchResult<Record> results = index.search(new Query("QUERY"));

// version 4
var results = client.searchSingleIndex(
    "ALGOLIA_INDEX_NAME",
    new SearchParamsObject().setQuery("QUERY"),
    Hit.class
);

Search multiple indices

The client.multipleQueries() method is now client.search(). Each request in the list requires an indexName:

Java

// version 3
client.multipleQueries(Arrays.asList(
    new IndexQuery("INDEX_1", new Query("QUERY")),
    new IndexQuery("INDEX_2", new Query("QUERY"))
));

// version 4
var results = client.search(
    new SearchMethodParams().setRequests(Arrays.asList(
        new SearchForHits().setIndexName("INDEX_1").setQuery("QUERY"),
        new SearchForHits().setIndexName("INDEX_2").setQuery("QUERY")
    )),
    Hit.class
);

Search for facet values

The index.searchForFacetValues() method becomes client.searchForFacetValues() with an indexName parameter:

Java

// version 3
SearchIndex<Record> index = client.initIndex("ALGOLIA_INDEX_NAME", Record.class);
index.searchForFacetValues("category", "book", new Query());

// version 4
var results = client.searchForFacetValues(
    "ALGOLIA_INDEX_NAME",
    "category",
    new SearchForFacetValuesRequest().setFacetQuery("book")
);

Update indexing operations

In version 4, indexing methods are on the client instead of the index object, with indexName as a parameter.

Add or replace records

Java

// version 3
SearchIndex<Record> index = client.initIndex("ALGOLIA_INDEX_NAME", Record.class);
index.saveObject(record);
index.saveObjects(records);

// version 4
client.saveObject("ALGOLIA_INDEX_NAME", record);
// saveObjects works the same way:
client.saveObjects("ALGOLIA_INDEX_NAME", records);

Partially update records

Java

// version 3
SearchIndex<Record> index = client.initIndex("ALGOLIA_INDEX_NAME", Record.class);
index.partialUpdateObject(new Record().setObjectID("1").setName("Updated"));

// version 4
client.partialUpdateObject(
    "ALGOLIA_INDEX_NAME",
    "1",
    Map.of("name", "Updated")
);

Delete records

Java

// version 3
SearchIndex<Record> index = client.initIndex("ALGOLIA_INDEX_NAME", Record.class);
index.deleteObject("1");

// version 4
client.deleteObject("ALGOLIA_INDEX_NAME", "1");

Update settings, synonyms, and rules

Get and set settings

Java

// version 3
SearchIndex<Record> index = client.initIndex("ALGOLIA_INDEX_NAME", Record.class);
IndexSettings settings = index.getSettings();
index.setSettings(new IndexSettings().setSearchableAttributes(Arrays.asList("title", "author")));

// version 4
IndexSettings settings = client.getSettings("ALGOLIA_INDEX_NAME");
client.setSettings(
    "ALGOLIA_INDEX_NAME",
    new IndexSettings().setSearchableAttributes(Arrays.asList("title", "author"))
);

Save synonyms and rules

Java

// version 3
SearchIndex<Record> index = client.initIndex("ALGOLIA_INDEX_NAME", Record.class);
index.saveSynonyms(synonymsList);
index.saveRules(rulesList);

// version 4
client.saveSynonyms("ALGOLIA_INDEX_NAME", synonymsList);
client.saveRules("ALGOLIA_INDEX_NAME", rulesList);

In version 3, index.replaceAllRules() and index.replaceAllSynonyms() replaced all rules or synonyms. In version 4, use client.saveRules() or client.saveSynonyms() with the clearExistingRules or clearExistingSynonyms parameter set to true.

Update index management

The copyIndex, moveIndex, copyRules, copySynonyms, and copySettings methods are all replaced by a single operationIndex method.

Copy an index

Java

// version 3
client.copyIndex("SOURCE_INDEX_NAME", "DESTINATION_INDEX_NAME");

// version 4
client.operationIndex(
    "SOURCE_INDEX_NAME",
    new OperationIndexParams().setOperation(OperationType.COPY).setDestination("DESTINATION_INDEX_NAME")
);

Move (rename) an index

Java

// version 3
client.moveIndex("SOURCE_INDEX_NAME", "DESTINATION_INDEX_NAME");

// version 4
client.operationIndex(
    "SOURCE_INDEX_NAME",
    new OperationIndexParams().setOperation(OperationType.MOVE).setDestination("DESTINATION_INDEX_NAME")
);

Copy only rules or settings

In version 4, use the scope parameter to limit the operation to specific data:

Java

// version 4: copy only rules and settings from one index to another
client.operationIndex(
    "SOURCE_INDEX_NAME",
    new OperationIndexParams()
        .setOperation(OperationType.COPY)
        .setDestination("DESTINATION_INDEX_NAME")
        .setScope(Arrays.asList(ScopeType.RULES, ScopeType.SETTINGS))
);

Update task handling

Version 3 supported chaining .waitTask() on operations. Version 4 replaces this pattern with dedicated wait helpers.

Java

// version 3
SearchIndex<Record> index = client.initIndex("ALGOLIA_INDEX_NAME", Record.class);
index.saveObject(record).waitTask();

// version 4
var response = client.saveObject("ALGOLIA_INDEX_NAME", record);
client.waitForTask("ALGOLIA_INDEX_NAME", response.getTaskID());

Version 4 includes three wait helpers:

• waitForTask: wait until indexing operations are done.
• waitForAppTask: wait for application-level tasks.
• waitForApiKey: wait for API key operations.

Method changes reference

The following tables list all method names that changed between version 3 and version 4.

Search API client

Version 3 (legacy)		Version 4 (current)
client.addApiKey	→	client.addApiKey
client.addApiKey.wait	→	client.waitForApiKey
client.clearDictionaryEntries	→	client.batchDictionaryEntries
client.copyIndex	→	client.operationIndex
client.copyRules	→	client.operationIndex
client.copySynonyms	→	client.operationIndex
client.deleteApiKey	→	client.deleteApiKey
client.deleteDictionaryEntries	→	client.batchDictionaryEntries
client.generateSecuredApiKey	→	client.generateSecuredApiKey
client.getApiKey	→	client.getApiKey
client.getSecuredApiKeyRemainingValidity	→	client.getSecuredApiKeyRemainingValidity
client.listApiKeys	→	client.listApiKeys
client.listIndices	→	client.listIndices
client.moveIndex	→	client.operationIndex
client.multipleBatch	→	client.multipleBatch
client.multipleQueries	→	client.search
client.replaceDictionaryEntries	→	client.batchDictionaryEntries
client.restoreApiKey	→	client.restoreApiKey
client.saveDictionaryEntries	→	client.batchDictionaryEntries
client.updateApiKey	→	client.updateApiKey
index.batch	→	client.batch
index.browseObjects	→	client.browseObjects
index.browseRules	→	client.browseRules
index.browseSynonyms	→	client.browseSynonyms
index.clearObjects	→	client.clearObjects
index.clearRules	→	client.clearRules
index.clearSynonyms	→	client.clearSynonyms
index.copySettings	→	client.operationIndex
index.delete	→	client.deleteIndex
index.deleteBy	→	client.deleteBy
index.deleteObject	→	client.deleteObject
index.deleteObjects	→	client.deleteObjects
index.deleteRule	→	client.deleteRule
index.deleteSynonym	→	client.deleteSynonym
index.findObject	→	client.searchSingleIndex
index.getObject	→	client.getObject
index.getObjects	→	client.getObjects
index.getRule	→	client.getRule
index.getSettings	→	client.getSettings
index.getSynonym	→	client.getSynonym
index.getTask	→	client.getTask
index.partialUpdateObject	→	client.partialUpdateObject
index.partialUpdateObjects	→	client.partialUpdateObjects
index.replaceAllObjects	→	client.replaceAllObjects
index.replaceAllRules	→	client.saveRules
index.replaceAllSynonyms	→	client.saveSynonyms
index.saveObject	→	client.saveObject
index.saveObjects	→	client.saveObjects
index.saveRule	→	client.saveRule
index.saveRules	→	client.saveRules
index.saveSynonym	→	client.saveSynonym
index.saveSynonyms	→	client.saveSynonyms
index.search	→	client.searchSingleIndex
index.searchForFacetValues	→	client.searchForFacetValues
index.searchRules	→	client.searchRules
index.searchSynonyms	→	client.searchSynonyms
index.setSettings	→	client.setSettings
index.{operation}.wait	→	client.waitForTask

Recommend API client

Version 3 (legacy)		Version 4 (current)
client.getFrequentlyBoughtTogether	→	client.getRecommendations
client.getRecommendations	→	client.getRecommendations
client.getRelatedProducts	→	client.getRecommendations