Skip to main content
The latest major version of the algoliasearch-client-swift package is version 9. This page helps you upgrade from version 8 and explains the breaking changes you need to address. Algolia generates the version 9 clients from OpenAPI specifications, which provides consistent behavior across all languages and up-to-date API coverage. The main architectural changes are:
  • The index(withName:) pattern is removed. All methods are now on the client instance directly, with indexName as a parameter.
  • Client initialization can throw, so try is required.
  • All API calls use Swift’s native async/await concurrency model.
  • All module names are prefixed with Algolia (for example, import AlgoliaSearch instead of import Search).
  • The client is compatible with Swift 6.
For the full list of changes, see the Swift changelog.

Update your dependencies

Swift Package Manager

Update your Swift Package Manager dependency to version 9. In your Package.swift, change the version requirement:
Swift
If you’re using Xcode, update the package version in File > Swift Packages.

CocoaPods

If you use CocoaPods, update your Podfile:
Ruby
With CocoaPods, all Algolia modules are bundled into a single AlgoliaSearchClient module. This means you use import AlgoliaSearchClient instead of the individual module imports shown in the rest of this guide.To support CocoaPods’ module flattening, some model names are prefixed with the client name to avoid conflicts. This applies regardless of your installation method. The prefixed names are more verbose, but the tradeoff is better autocompletion in IDEs and more predictable structure that works well with AI coding assistants.

Update imports

Since version 9.40.0, all module names are prefixed with Algolia to avoid conflicts with other dependencies. The main module changed from AlgoliaSearchClient to AlgoliaSearch:
Swift
Most version 9 code requires AlgoliaCore alongside the API-specific module, since AlgoliaCore defines shared types such as SearchClient configuration and request options. Version 9 includes dedicated modules for each API. To access methods from a specific API, import the corresponding module:
Swift

Update client initialization

In version 9, SearchClient initialization can throw, requiring the try keyword:
Swift
The try keyword is required because version 9 validates your application ID and API key during initialization. If you’re initializing the client inside a function that doesn’t already throw, wrap it in a do/catch block.
The other major change concerns what follows initialization: index(withName:) no longer exists.

Remove index(withName:)

This is the most significant change when upgrading. Version 8 relied on an index object with methods called on it. In version 9, all methods belong to the client instance, with indexName as a parameter.
Swift
If you have many files to update, search your codebase for index(withName:) or .index(withName: to find every place that needs changing.

Add async/await

Version 9 is built on Swift’s native concurrency model. All API calls are async functions that require try await. In version 8, API calls rely on completion handlers:
Swift
If you’re calling Algolia methods from synchronous code, wrap them in a Task:
Swift

Update search calls

Search a single index

The index.search() method is now client.searchSingleIndex(). Pass the index name and search parameters as named arguments:
Swift

Search multiple indices

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

Search for facet values

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

Update indexing operations

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

Add or replace records

Swift

Partially update records

Swift

Delete records

Swift

Update settings, synonyms, and rules

Get and set settings

Swift

Save synonyms and rules

Swift
In version 8, index.replaceAllRules() and index.replaceAllSynonyms() replaced all rules or synonyms. In version 9, use client.saveRules() or client.saveSynonyms() with the clearExistingRules or replaceExistingSynonyms 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

Swift

Move (rename) an index

Swift

Copy only rules or settings

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

Check if an index exists

In version 8, you could check if an index existed using the exists method on the index object. In version 9, use the indexExists helper method on the client:
Swift

Update task handling

Version 8 supported chaining .wait() on operations. Version 9 replaces this pattern with dedicated wait helpers.
Swift
Version 9 includes three wait helpers:

Helper method changes

The following sections document breaking changes in helper method signatures and behavior between version 8 and version 9.

replaceAllObjects

The safe parameter has been removed. In version 8, safe: true caused the helper to wait after each step. In version 9, the helper always waits—equivalent to the previous safe: true behavior. The completion-handler-based API has also been removed in favor of Swift concurrency (async/await).
Swift

saveObjects

The autoGeneratingObjectID parameter has been removed. In version 9, every object must include an objectID. The completion-handler-based API has also been removed in favor of Swift concurrency.
Swift

deleteObjects

The input type changed from [ObjectID] (a typed wrapper) to [String]. The helper moved to the client, and two new optional parameters are available: waitForTasks (default false) and batchSize (default 1,000).
Swift

partialUpdateObjects

The input type changed from [(objectID: ObjectID, update: PartialUpdate)] to [some Encodable]. The createIfNotExists default flipped from true (version 8) to false (version 9). The completion-handler API was also replaced with Swift concurrency.
Swift

browseObjects, browseRules, browseSynonyms

  • In version 8, these helpers fetched all pages and returned the full result array through a completion handler or a throwing call.
  • In version 9, they use Swift concurrency and accept an aggregator closure, which is invoked for each page. They also accept an optional validate closure to stop pagination early.
Swift

generateSecuredApiKey and getSecuredApiKeyRemainingValidity

Both method names changed from API (all caps) to Api (title case) to follow Swift naming conventions.
Swift

waitForTask

The helper was renamed from waitTask to waitForTask, moved to the client, and now uses Swift concurrency. The timeout parameter changed from TimeInterval? (a maximum wall-clock limit) to a retry-count-to-delay closure (with delays that increase exponentially). An explicit maxRetries parameter (default 100) was added.
Swift

waitForAppTask

This is a new helper in version 9.
Swift

waitForApiKey

This is a new standalone helper in version 9.
Swift

indexExists

This helper is new in version 9.
Swift

chunkedBatch

chunkedBatch is now a public helper in version 9. In version 8, chunking was an internal detail of saveObjects. The action parameter defaults to .addObject and waitForTasks defaults to false.
Swift

copyIndexBetweenApplications

In version 8, the AccountClient struct provided a static copyIndex(source:destination:) method for copying an index between two different Algolia applications. In version 9, AccountClient is removed. You can compose existing helpers across two clients to achieve the same result.
Swift

saveObjectsWithTransformation

In version 9: routes records with the Push to Algolia connector. Requires transformationOptions to be set on the client configuration. region is required; every other field keeps the Ingestion API defaults.
Swift

replaceAllObjectsWithTransformation

In version 9: atomically replaces all records with the Push to Algolia connector. It copies settings, rules, and synonyms to a temporary index, pushes records to the temporary index, and moves the temporary index back. scopes defaults to .settings, .rules, and .synonyms.
Swift

partialUpdateObjectsWithTransformation

In version 9: routes partial updates with the Push to Algolia connector. The createIfNotExists parameter defaults to true.
Swift

Method changes reference

The following tables list all method names that changed between version 8 and version 9.

Search API client

Recommend API client

Last modified on July 6, 2026