Upgrade the Swift API client to version 9

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

// version 8
.package(url: "https://github.com/algolia/algoliasearch-client-swift", from: "8.0.0")

// version 9
.package(url: "https://github.com/algolia/algoliasearch-client-swift", from: "9.0.0")

If you’re using Xcode, update the package version in File > Swift Packages.

CocoaPods

If you use CocoaPods, update your Podfile:

Ruby

# version 8
pod 'AlgoliaSearchClient', '~> 8.0'

# version 9
pod 'AlgoliaSearchClient', '~> 9.0.0'

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

// version 8
import AlgoliaSearchClient

// version 9
import AlgoliaCore
import AlgoliaSearch

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

// Search API
import AlgoliaSearch
// Recommend API
import AlgoliaRecommend
// A/B testing API
import AlgoliaAbtesting
// Analytics API
import AlgoliaAnalytics
// Personalization API
import AlgoliaPersonalization
// Query Suggestions API
import AlgoliaQuerySuggestions

Update client initialization

In version 9, SearchClient initialization can throw, requiring the try keyword:

Swift

// version 8
let client = SearchClient(appID: "ALGOLIA_APPLICATION_ID", apiKey: "ALGOLIA_API_KEY")

// version 9
let client = try SearchClient(appID: "ALGOLIA_APPLICATION_ID", apiKey: "ALGOLIA_API_KEY")

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

// version 8
let client = SearchClient(appID: "ALGOLIA_APPLICATION_ID", apiKey: "ALGOLIA_API_KEY")
let index = client.index(withName: "ALGOLIA_INDEX_NAME")
index.search(query: "QUERY")

// version 9
let client = try SearchClient(appID: "ALGOLIA_APPLICATION_ID", apiKey: "ALGOLIA_API_KEY")
try await client.searchSingleIndex(
    indexName: "ALGOLIA_INDEX_NAME",
    searchParams: SearchSearchParams.searchSearchParamsObject(
        SearchSearchParamsObject(query: "QUERY")
    )
)

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

// version 8 -- completion handler
let index = client.index(withName: "ALGOLIA_INDEX_NAME")
index.search(query: Query("QUERY")) { result in
    switch result {
    case .success(let response):
        print(response.hits)
    case .failure(let error):
        print(error)
    }
}

// version 9 -- async/await
let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "ALGOLIA_INDEX_NAME",
    searchParams: SearchSearchParams.searchSearchParamsObject(
        SearchSearchParamsObject(query: "QUERY")
    )
)

If you’re calling Algolia methods from synchronous code, wrap them in a Task:

Swift

// version 9 -- calling from synchronous code
Task {
    do {
        let response: SearchResponse<Hit> = try await client.searchSingleIndex(
            indexName: "ALGOLIA_INDEX_NAME",
            searchParams: SearchSearchParams.searchSearchParamsObject(
                SearchSearchParamsObject(query: "QUERY")
            )
        )
        print(response.hits)
    } catch {
        print(error)
    }
}

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

// version 8
let index = client.index(withName: "ALGOLIA_INDEX_NAME")
let result = index.search(query: "QUERY")

// version 9
let result: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "ALGOLIA_INDEX_NAME",
    searchParams: SearchSearchParams.searchSearchParamsObject(
        SearchSearchParamsObject(
            query: "QUERY",
            facetFilters: SearchFacetFilters.arrayOfSearchFacetFilters(
                [SearchFacetFilters.string("category:Book")]
            )
        )
    )
)

Search multiple indices

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

Swift

// version 8
let results = client.multipleQueries(queries: [
    IndexQuery(indexName: "INDEX_1", query: Query("QUERY")),
    IndexQuery(indexName: "INDEX_2", query: Query("QUERY")),
])

// version 9
let response: SearchResponses<Hit> = try await client.search(
    searchMethodParams: SearchMethodParams(
        requests: [
            SearchQuery.searchForHits(SearchForHits(
                indexName: "INDEX_1",
                query: "QUERY"
            )),
            SearchQuery.searchForHits(SearchForHits(
                indexName: "INDEX_2",
                query: "QUERY"
            )),
        ]
    )
)

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

Swift

// version 8
let index = client.index(withName: "ALGOLIA_INDEX_NAME")
let results = index.searchForFacetValues(of: "category", matching: "book")

// version 9
let results = try await client.searchForFacetValues(
    indexName: "ALGOLIA_INDEX_NAME",
    facetName: "category",
    searchForFacetValuesRequest: SearchForFacetValuesRequest(facetQuery: "book")
)

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

// version 8
let index = client.index(withName: "ALGOLIA_INDEX_NAME")
index.saveObject(["objectID": "1", "name": "Record"])

// version 9
let response = try await client.saveObject(
    indexName: "ALGOLIA_INDEX_NAME",
    body: [
        "objectID": "1",
        "name": "Record",
    ]
)
// saveObjects works the same way:
let response = try await client.saveObjects(
    indexName: "ALGOLIA_INDEX_NAME",
    objects: [["objectID": "1", "name": "Record"]]
)

Partially update records

Swift

// version 8
let index = client.index(withName: "ALGOLIA_INDEX_NAME")
index.partialUpdateObject(["objectID": "1", "name": "Updated"])

// version 9
let response = try await client.partialUpdateObject(
    indexName: "ALGOLIA_INDEX_NAME",
    objectID: "1",
    attributesToUpdate: ["name": "Updated"]
)

Delete records

Swift

// version 8
let index = client.index(withName: "ALGOLIA_INDEX_NAME")
index.deleteObject(withID: "1")

// version 9
let response = try await client.deleteObject(indexName: "ALGOLIA_INDEX_NAME", objectID: "1")

Update settings, synonyms, and rules

Get and set settings

Swift

// version 8
let index = client.index(withName: "ALGOLIA_INDEX_NAME")
let settings = index.getSettings()
index.setSettings(Settings().set(\.searchableAttributes, to: ["title", "author"]))

// version 9
let settings = try await client.getSettings(
    indexName: "ALGOLIA_INDEX_NAME"
)
try await client.setSettings(
    indexName: "ALGOLIA_INDEX_NAME",
    indexSettings: IndexSettings(searchableAttributes: ["title", "author"])
)

Save synonyms and rules

Swift

// version 8
let index = client.index(withName: "ALGOLIA_INDEX_NAME")
index.saveSynonyms([Synonym.regular(objectID: "1", synonyms: ["car", "auto"])])
index.saveRules([Rule(objectID: "1")])

// version 9
try await client.saveSynonyms(
    indexName: "ALGOLIA_INDEX_NAME",
    synonymHit: [SynonymHit(objectID: "1", type: SynonymType.synonym, synonyms: ["car", "auto"])]
)
try await client.saveRules(
    indexName: "ALGOLIA_INDEX_NAME",
    rules: [Rule(
        objectID: "1",
        conditions: [SearchCondition(pattern: "shoes", anchoring: SearchAnchoring.contains)],
        consequence: SearchConsequence(params: SearchConsequenceParams(filters: "brand:nike"))
    )]
)

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

// version 8
client.copyIndex(from: "SOURCE_INDEX_NAME", to: "DESTINATION_INDEX_NAME")

// version 9
try await client.operationIndex(
    indexName: "SOURCE_INDEX_NAME",
    operationIndexParams: OperationIndexParams(
        operation: OperationType.copy,
        destination: "DESTINATION_INDEX_NAME"
    )
)

Move (rename) an index

Swift

// version 8
client.moveIndex(from: "SOURCE_INDEX_NAME", to: "DESTINATION_INDEX_NAME")

// version 9
try await client.operationIndex(
    indexName: "SOURCE_INDEX_NAME",
    operationIndexParams: OperationIndexParams(
        operation: OperationType.move,
        destination: "DESTINATION_INDEX_NAME"
    )
)

Copy only rules or settings

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

Swift

// version 9 -- copy only rules and settings from one index to another
try await client.operationIndex(
    indexName: "SOURCE_INDEX_NAME",
    operationIndexParams: OperationIndexParams(
        operation: OperationType.copy,
        destination: "DESTINATION_INDEX_NAME",
        scope: [ScopeType.rules, ScopeType.settings]
    )
)

Update task handling

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

Swift

// version 8
let index = client.index(withName: "ALGOLIA_INDEX_NAME")
index.saveObjects(records).wait()

// version 9
let response = try await client.saveObjects(
    indexName: "ALGOLIA_INDEX_NAME",
    objects: records
)
try await client.waitForTask(indexName: "ALGOLIA_INDEX_NAME", taskID: Int64(response.taskID))

Version 9 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 8 and version 9.

Search API client

Version 8 (legacy)		Version 9 (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.batch`	→	`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.browse`	→	`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`

Version 8 (legacy)		Version 9 (current)
`client.getFrequentlyBoughtTogether`	→	`client.getRecommendations`
`client.getRecommendations`	→	`client.getRecommendations`
`client.getRelatedProducts`	→	`client.getRecommendations`

API clients (current)

Clients and methods

Upgrade the Swift API client to version 9

Update your dependencies

Swift Package Manager

CocoaPods

Update imports

Update client initialization

Remove `index(withName:)`

Add async/await

Update search calls

Search a single index

Search multiple indices

Search for facet values

Update indexing operations

Add or replace records

Partially update records

Delete records

Update settings, synonyms, and rules

Get and set settings

Save synonyms and rules

Update index management

Copy an index

Move (rename) an index

Copy only rules or settings

Update task handling

Method changes reference

Search API client

API clients (current)

Clients and methods

​Update your dependencies

​Swift Package Manager

​CocoaPods

​Update imports

​Update client initialization

​Remove index(withName:)

​Add async/await

​Update search calls

​Search a single index

​Search multiple indices

​Search for facet values

​Update indexing operations

​Add or replace records

​Partially update records

​Delete records

​Update settings, synonyms, and rules

​Get and set settings

​Save synonyms and rules

​Update index management

​Copy an index

​Move (rename) an index

​Copy only rules or settings

​Update task handling

​Method changes reference

​Search API client

​Recommend API client

Update your dependencies

Swift Package Manager

CocoaPods

Update imports

Update client initialization

Remove `index(withName:)`

Add async/await

Update search calls

Search a single index

Search multiple indices

Search for facet values

Update indexing operations

Add or replace records

Partially update records

Delete records

Update settings, synonyms, and rules

Get and set settings

Save synonyms and rules

Update index management

Copy an index

Move (rename) an index

Copy only rules or settings

Update task handling

Method changes reference

Search API client

Recommend API client