OfflineIndex

@objcMembers
public class OfflineIndex : NSObject, Searchable

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.offlineIndex(withName:) to obtain an instance.

Note

Requires Algolia Offline Core. OfflineClient.enableOfflineMode(...) 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 assert if you do so.

Note

The synchronous methods can throw; you have to catch and handle the error.

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

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 Index.batch(...)). However, all write operations are de facto batches, since they must be wrapped inside a transaction (see below).

Properties

  • This index’s name.

    Declaration

    Swift

    @objc
public let name: String

  • API client used by this index.

    Declaration

    Swift

    @objc
public let client: OfflineClient

  • Whether this index has offline data on disk.

    Declaration

    Swift

    @objc
public var hasOfflineData: Bool { get }

Read operations

  • Get an object from this index.

    Declaration

    Swift

    @discardableResult
@objc
public func getObject(withID objectID: String, completionHandler: @escaping CompletionHandler) -> Operation

    Parameters

    objectID

    Identifier of the object to retrieve.
    completionHandler

    Completion handler to be notified of the request’s outcome.

    Return Value

    A cancellable operation.

  • Get an object from this index, optionally restricting the retrieved content.

    Declaration

    Swift

    @discardableResult
@objc
public func getObject(withID objectID: String, attributesToRetrieve: [String]?, completionHandler: @escaping CompletionHandler) -> Operation

    Parameters

    objectID

    Identifier of the object to retrieve.
    attributesToRetrieve

    List of attributes to retrieve. If nil, all (retrievable) attributes will be retrieved.
    completionHandler

    Completion handler to be notified of the request’s outcome.

    Return Value

    A cancellable operation.

  • Get several objects from this index.

    Declaration

    Swift

    @discardableResult
@objc
public func getObjects(withIDs objectIDs: [String], completionHandler: @escaping CompletionHandler) -> Operation

    Parameters

    objectIDs

    Identifiers of objects to retrieve.
    completionHandler

    Completion handler to be notified of the request’s outcome.

    Return Value

    A cancellable operation.

  • Get several objects from this index, optionally restricting the retrieved content.

    Declaration

    Swift

    @discardableResult
@objc
public func getObjects(withIDs objectIDs: [String], attributesToRetrieve: [String]?, completionHandler: @escaping CompletionHandler) -> Operation

    Parameters

    objectIDs

    Identifiers of objects to retrieve.
    attributesToRetrieve

    List of attributes to retrieve. If nil, all (retrievable) attributes will be retrieved.
    completionHandler

    Completion handler to be notified of the request’s outcome.

    Return Value

    A cancellable operation.

  • Search this index.

    Declaration

    Swift

    @discardableResult
@objc
public func search(_ query: Query, requestOptions: RequestOptions? = nil, completionHandler: @escaping CompletionHandler) -> Operation

    Parameters

    query

    Search parameters.
    completionHandler

    Completion handler to be notified of the request’s outcome.

    Return Value

    A cancellable operation.

  • Get this index’s settings.

    Declaration

    Swift

    @discardableResult
@objc(getSettings:)
public func getSettings(completionHandler: @escaping CompletionHandler) -> Operation

    Parameters

    completionHandler

    Completion handler to be notified of the request’s outcome.

    Return Value

    A cancellable operation.

  • 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 browseFrom with that cursor.

    Declaration

    Swift

    @discardableResult
@objc
public func browse(query: Query, completionHandler: @escaping CompletionHandler) -> Operation

    Parameters

    query

    The query parameters for the browse.
    completionHandler

    Completion handler to be notified of the request’s outcome.

    Return Value

    A cancellable operation.

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

    Declaration

    Swift

    @discardableResult
@objc
public func browseFrom(cursor: String, completionHandler: @escaping CompletionHandler) -> Operation

    Parameters

    cursor

    The cursor of the next page to retrieve
    completionHandler

    Completion handler to be notified of the request’s outcome.

    Return Value

    A cancellable operation.

  • Run multiple queries on this index.

    Declaration

    Swift

    @discardableResult
@objc
public func multipleQueries(_ queries: [Query], strategy: String?, completionHandler: @escaping CompletionHandler) -> Operation

    Parameters

    queries

    The queries to run.
    strategy

    The strategy to use.
    completionHandler

    Completion handler to be notified of the request’s outcome.

    Return Value

    A cancellable operation.

  • Run multiple queries on this index.

    Declaration

    Swift

    @discardableResult
public func multipleQueries(_ queries: [Query], strategy: Client.MultipleQueriesStrategy? = nil, completionHandler: @escaping CompletionHandler) -> Operation

    Parameters

    queries

    The queries to run.
    strategy

    The strategy to use.
    completionHandler

    Completion handler to be notified of the request’s outcome.

    Return Value

    A cancellable operation.

  • Search for facet values. Same parameters as Index.searchForFacetValues(...).

    Declaration

    Swift

    @discardableResult
@objc(searchForFacetValuesOf:matching:query:requestOptions:completionHandler:)
public func searchForFacetValues(of facetName: String, matching text: String, query: Query? = nil, requestOptions: RequestOptions? = nil, completionHandler: @escaping CompletionHandler) -> Operation

Write operations

  • A transaction to update the index.

    A transaction gathers all the operations that will be performed when the transaction is committed. Its purpose is twofold:

    1. Avoid rebuilding the index for every individual operation, which would be very costly.
    2. Avoid keeping all the necessary data in memory, e.g. by flushing added objects to temporary files on disk.

    A transaction can be created by calling OfflineIndex.newTransaction().

    See more

    Declaration

    Swift

    @objcMembers
public class WriteTransaction : NSObject

  • Create a new write transaction.

    Declaration

    Swift

    @objc
public func newTransaction() -> WriteTransaction

Manual build

  • Build the index from local files. This method is a shortcut alternative to using write transactions if all of your data is already available as plain JSON files on disk.

    Note

    Cancelling the request does not cancel the build; it merely prevents the completion handler from being called.

    Declaration

    Swift

    @discardableResult
@objc
public func build(settingsFile: String, objectFiles: [String], completionHandler: CompletionHandler? = nil) -> Operation

    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

    An optional completion handler to be notified when the build has finished.

    Return Value

    A cancellable operation.

Helpers

  • Delete all objects matching a query.

    Warning

    This method will assert/crash if no transaction is currently open.

    Declaration

    Swift

    @discardableResult
@objc
public func deleteByQuery(_ query: Query, completionHandler: CompletionHandler? = nil) -> Operation

    Parameters

    query

    The query that objects to delete must match.
    completionHandler

    Completion handler to be notified of the request’s outcome.

    Return Value

    A cancellable operation.

  • Delete all objects matching a query (synchronously).

    Warning

    This method will assert/crash if no transaction is currently open.

    Warning

    This method must not be called from the main thread.

    Declaration

    Swift

    @discardableResult
@objc
public func deleteByQuerySync(_ query: Query, transaction: WriteTransaction) throws -> [String]

    Parameters

    query

    The query that objects to delete must match.

    Return Value

    List of deleted object IDs.

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

    Declaration

    Swift

    @discardableResult
@objc
public func searchDisjunctiveFaceting(_ query: Query, disjunctiveFacets: [String], refinements: [String: [String]], requestOptions: RequestOptions? = nil, completionHandler: @escaping CompletionHandler) -> Operation

    Parameters

    query

    The query.
    disjunctiveFacets

    List of disjunctive facets.
    refinements

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

    Completion handler to be notified of the request’s outcome.

    Return Value

    A cancellable operation.