com.algolia.search.saas

Class OfflineIndex

Object

com.algolia.search.saas.OfflineIndex

public class OfflineIndex
extends Object

A purely offline index. Such an index has no online counterpart. It is updated and queried locally. **Note:** You cannot construct this class directly. Please use OfflineClient.getOfflineIndex(String) to obtain an instance. **Note:** Requires Algolia Offline Core. OfflineClient.enableOfflineMode(String) must be called with a valid license key prior to calling any offline-related method. ## Reading Read operations behave identically as with online indices. ## Writing Updating an index involves rebuilding it, which is an expensive and potentially lengthy operation. Therefore, all updates must be wrapped inside a **transaction**. The procedure to update an index is as follows: - Create a transaction by calling newTransaction(). - Populate the transaction: call the various write methods on the WriteTransaction class. - Either commit or rollback the transaction. ### Synchronous vs asynchronous updates Any write operation, especially (but not limited to) the final commit, is potentially lengthy. This is why all operations provide an asynchronous version, which accepts an optional completion handler that will be notified of the operation's completion (either successful or erroneous). If you already have a background thread/queue performing data-handling tasks, you may find it more convenient to use the synchronous versions of the write methods. They are named after the asynchronous versions, suffixed by `Sync`. The flow is identical to the asynchronous version (see above). **Warning:** You must not call synchronous methods from the main thread. The methods will throw an `IllegalStateException` if you do so. **Note:** The synchronous methods can throw; you have to catch and handle the exception. ### Parallel transactions While it is possible to create parallel transactions, there is little interest in doing so, since each committed transaction results in an index rebuild. Multiplying transactions therefore only degrades performance. Also, transactions are serially executed in the order they were committed, the latest transaction potentially overwriting the previous transactions' result. ### Manual build As an alternative to using write transactions, `OfflineIndex` also offers a **manual build** feature. Provided that you have: - the **index settings** (one JSON file); and - the **objects** (as many JSON files as needed, each containing an array of objects) ... available as local files on disk, you can replace the index's content with that data by calling buildFromFiles or buildFromRawResources. ## Caveats ### Limitations Though offline indices support most features of an online index, there are some limitations: - Objects **must contain an `objectID`** field. The SDK will refuse to index objects without an ID. - **Partial updates** are not supported. - **Replica indices** are not supported. ### Differences - **Settings** are not incremental: the new settings completely replace the previous ones. If a setting is omitted in the new version, it reverts back to its default value. (This is in contrast with the online API, where you can only specify the settings you want to change and omit the others.) - You cannot batch arbitrary write operations in a single method call (as you would do with Client.batchAsync). However, all write operations are *de facto* batches, since they must be wrapped inside a transaction (see below).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	OfflineIndex.WriteTransaction A transaction to update the index.

Method Summary

Modifier and Type	Method and Description
Request	browseAsync(Query query, CompletionHandler completionHandler) Browse all index content (initial call).
Request	browseFromAsync(String cursor, CompletionHandler completionHandler) Browse the index from a cursor.
Request	buildFromFiles(File settingsFile, File... objectFiles)
Request	buildFromFiles(File settingsFile, File[] objectFiles, CompletionHandler completionHandler) Build the index from local data stored on the filesystem.
Request	buildFromRawResources(android.content.res.Resources resources, int settingsResId, int... objectsResIds)
Request	buildFromRawResources(android.content.res.Resources resources, int settingsResId, int[] objectsResIds, CompletionHandler completionHandler) Build the index from local data stored in raw resources.
Request	deleteByQueryAsync(Query query, CompletionHandler completionHandler) Delete all objects matching a query (helper).
OfflineClient	getClient() Get the client to which this index belongs.
String	getName() Get this index's name.
Request	getObjectAsync(String objectID, CompletionHandler completionHandler) Get an object from this index (asynchronously).
Request	getObjectAsync(String objectID, List<String> attributesToRetrieve, CompletionHandler completionHandler) Get an object from this index, optionally restricting the retrieved content (asynchronously).
Request	getObjectsAsync(List<String> objectIDs, CompletionHandler completionHandler) Get several objects from this index (asynchronously).
Request	getSettingsAsync(CompletionHandler completionHandler) Get this index's settings (asynchronously).
boolean	hasOfflineData() Test if this index has offline data on disk.
Request	multipleQueriesAsync(List<Query> queries, Client.MultipleQueriesStrategy strategy, CompletionHandler completionHandler) Run multiple queries on this index with one API call.
OfflineIndex.WriteTransaction	newTransaction() Create a new write transaction.
Request	searchAsync(Query query, CompletionHandler completionHandler) Search inside this index (asynchronously).
Request	searchDisjunctiveFacetingAsync(Query query, List<String> disjunctiveFacets, Map<String,List<String>> refinements, CompletionHandler completionHandler) Perform a search with disjunctive facets, generating as many queries as number of disjunctive facets (helper).
Request	searchForFacetValuesAsync(String facetName, String facetQuery, Query query, CompletionHandler completionHandler) Search for facet values (asynchronously).
String	toString()

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

toString

public String toString()

Overrides:

toString in class Object

getName

public String getName()

Get this index's name.

Returns:

This index's name.

getClient

public OfflineClient getClient()

Get the client to which this index belongs.

Returns:

The client to which this index belongs.

searchAsync

public Request searchAsync(@NonNull
                           Query query,
                           @NonNull
                           CompletionHandler completionHandler)

Search inside this index (asynchronously).

Parameters:

query - Search parameters. May be null to use an empty query.

completionHandler - The listener that will be notified of the request's outcome.

Returns:

A cancellable request.

multipleQueriesAsync

public Request multipleQueriesAsync(@NonNull
                                    List<Query> queries,
                                    @Nullable
                                    Client.MultipleQueriesStrategy strategy,
                                    @NonNull
                                    CompletionHandler completionHandler)

Run multiple queries on this index with one API call. A variant of Client.multipleQueriesAsync(List, Client.MultipleQueriesStrategy, CompletionHandler) where the targeted index is always the receiver.

Parameters:

queries - The queries to run.

strategy - The strategy to use.

completionHandler - The listener that will be notified of the request's outcome.

Returns:

A cancellable request.

getObjectAsync

public Request getObjectAsync(@NonNull
                              String objectID,
                              @NonNull
                              CompletionHandler completionHandler)

Get an object from this index (asynchronously).

Parameters:

objectID - Identifier of the object to retrieve.

completionHandler - The listener that will be notified of the request's outcome.

Returns:

A cancellable request.

getObjectAsync

public Request getObjectAsync(@NonNull
                              String objectID,
                              List<String> attributesToRetrieve,
                              @NonNull
                              CompletionHandler completionHandler)

Get an object from this index, optionally restricting the retrieved content (asynchronously).

Parameters:

objectID - Identifier of the object to retrieve.

attributesToRetrieve - List of attributes to retrieve.

completionHandler - The listener that will be notified of the request's outcome.

Returns:

A cancellable request.

getObjectsAsync

public Request getObjectsAsync(@NonNull
                               List<String> objectIDs,
                               @NonNull
                               CompletionHandler completionHandler)

Get several objects from this index (asynchronously).

Parameters:

objectIDs - Identifiers of objects to retrieve.

completionHandler - The listener that will be notified of the request's outcome.

Returns:

A cancellable request.

getSettingsAsync

public Request getSettingsAsync(@NonNull
                                CompletionHandler completionHandler)

Get this index's settings (asynchronously).

Parameters:

completionHandler - The listener that will be notified of the request's outcome.

Returns:

A cancellable request.

browseAsync

public Request browseAsync(@NonNull
                           Query query,
                           @NonNull
                           CompletionHandler completionHandler)

Browse all index content (initial call). This method should be called once to initiate a browse. It will return the first page of results and a cursor, unless the end of the index has been reached. To retrieve subsequent pages, call `browseFromAsync` with that cursor.

Parameters:

query - The query parameters for the browse.

completionHandler - The listener that will be notified of the request's outcome.

Returns:

A cancellable request.

browseFromAsync

public Request browseFromAsync(@NonNull
                               String cursor,
                               @NonNull
                               CompletionHandler completionHandler)

Browse the index from a cursor. This method should be called after an initial call to `browseAsync()`. It returns a cursor, unless the end of the index has been reached.

Parameters:

cursor - The cursor of the next page to retrieve.

completionHandler - The listener that will be notified of the request's outcome.

Returns:

A cancellable request.

searchForFacetValuesAsync

public Request searchForFacetValuesAsync(@NonNull
                                         String facetName,
                                         @NonNull
                                         String facetQuery,
                                         @Nullable
                                         Query query,
                                         @NonNull
                                         CompletionHandler completionHandler)

Search for facet values (asynchronously). Same parameters as Index.searchForFacetValues(String, String, Query, CompletionHandler).

newTransaction

@NonNull
public OfflineIndex.WriteTransaction newTransaction()

Create a new write transaction.

hasOfflineData

public boolean hasOfflineData()

Test if this index has offline data on disk. **Warning:** This method is synchronous! It will block until completion.

Returns:

`true` if data exists on disk for this index, `false` otherwise.

buildFromFiles

public Request buildFromFiles(@NonNull
                              File settingsFile,
                              @NonNull
                              File[] objectFiles,
                              @Nullable
                              CompletionHandler completionHandler)

Build the index from local data stored on the filesystem.

Parameters:

settingsFile - Absolute path to the file containing the index settings, in JSON format.

objectFiles - Absolute path(s) to the file(s) containing the objects. Each file must contain an array of objects, in JSON format.

completionHandler - Optional completion handler to be notified of the build's outcome.

Returns:

A cancellable request. **Note:** Cancelling the request does *not* cancel the build; it merely prevents the completion handler from being called.

buildFromFiles

public Request buildFromFiles(@NonNull
                              File settingsFile,
                              @NonNull
                              File... objectFiles)

buildFromRawResources

public Request buildFromRawResources(@NonNull
                                     android.content.res.Resources resources,
                                     @NonNull
                                     int settingsResId,
                                     @NonNull
                                     int[] objectsResIds,
                                     @Nullable
                                     CompletionHandler completionHandler)

Build the index from local data stored in raw resources.

Parameters:

resources - A Resources instance to read resources from.

settingsResId - Resource identifier of the index settings, in JSON format.

objectsResIds - Resource identifiers of the various objects files. Each file must contain an array of objects, in JSON format.

completionHandler - Optional completion handler to be notified of the build's outcome.

Returns:

A cancellable request. **Note:** Cancelling the request does *not* cancel the build; it merely prevents the completion handler from being called.

buildFromRawResources

public Request buildFromRawResources(@NonNull
                                     android.content.res.Resources resources,
                                     @NonNull
                                     int settingsResId,
                                     @NonNull
                                     int... objectsResIds)

searchDisjunctiveFacetingAsync

public Request searchDisjunctiveFacetingAsync(@NonNull
                                              Query query,
                                              @NonNull
                                              List<String> disjunctiveFacets,
                                              @NonNull
                                              Map<String,List<String>> refinements,
                                              @NonNull
                                              CompletionHandler completionHandler)

Perform a search with disjunctive facets, generating as many queries as number of disjunctive facets (helper).

Parameters:

query - The query.

disjunctiveFacets - List of disjunctive facets.

refinements - The current refinements, mapping facet names to a list of values.

completionHandler - The listener that will be notified of the request's outcome.

Returns:

A cancellable request.

deleteByQueryAsync

public Request deleteByQueryAsync(@NonNull
                                  Query query,
                                  CompletionHandler completionHandler)

Delete all objects matching a query (helper).

Parameters:

query - The query that objects to delete must match.

completionHandler - The listener that will be notified of the request's outcome.

Returns:

A cancellable request.