Skip to main content
The latest major version of the algoliasearch-client-go 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 Go changelog.

​
Update your dependencies

Update the algoliasearch-client-go package to version 4: 
go get github.com/algolia/algoliasearch-client-go/v4

​
Update imports

The import path changed from v3 to v4:
Go
// version 3
import "github.com/algolia/algoliasearch-client-go/v3/algolia/search"

// version 4
import "github.com/algolia/algoliasearch-client-go/v4/algolia/search"

​
Update client initialization

In version 3, NewClient returned a client directly. In version 4, it returns a (client, error) pair, so you need to handle the error:
Go
// version 3
client := search.NewClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")

// version 4
client, err := search.NewClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
if err != nil {
  panic(err)
}

​
Understand the new API surface

Version 4 introduces two major changes to the API surface:
  • No more InitIndex. Version 3 relied on an index object with methods called on it. In version 4, all methods belong to the client instance, with indexName as a parameter.
  • Builder pattern for requests. Version 4 introduces typed request builders (NewApi*Request constructors) with With* methods for optional parameters.
The builder pattern is more verbose than version 3’s flat function signatures. The tradeoff is strong typing, better IDE autocompletion, and predictable structure that works well with AI coding assistants.
Go
// version 3
client := search.NewClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
index := client.InitIndex("ALGOLIA_INDEX_NAME")
index.Search("QUERY")

// version 4
client, err := search.NewClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
if err != nil {
  panic(err)
}
response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "ALGOLIA_INDEX_NAME").WithSearchParams(
    search.SearchParamsObjectAsSearchParams(
      search.NewEmptySearchParamsObject().SetQuery("QUERY"))))
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(). Build the request with NewApiSearchSingleIndexRequest and attach search parameters with WithSearchParams:
Go
// version 3
index := client.InitIndex("ALGOLIA_INDEX_NAME")
res, err := index.Search("QUERY", opt.Filters("category:Book"))

// version 4
response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
  "ALGOLIA_INDEX_NAME").WithSearchParams(
    search.SearchParamsObjectAsSearchParams(
      search.NewEmptySearchParamsObject().
        SetQuery("QUERY").
        SetFacetFilters(search.ArrayOfFacetFiltersAsFacetFilters([]search.FacetFilters{*search.StringAsFacetFilters("category:Book")})))))

​
Search multiple indices

The client.MultipleQueries() method is now client.Search(). Each query in the request requires an IndexName:
Go
// version 3
res, err := client.MultipleQueries([]search.IndexedQuery{
  {IndexName: "INDEX_1", Params: search.Params{Query: search.Query("QUERY")}},
  {IndexName: "INDEX_2", Params: search.Params{Query: search.Query("QUERY")}},
})

// version 4
response, err := client.Search(client.NewApiSearchRequest(
  search.NewEmptySearchMethodParams().SetRequests(
    []search.SearchQuery{
      *search.SearchForHitsAsSearchQuery(
        search.NewEmptySearchForHits().SetIndexName("INDEX_1").SetQuery("QUERY")),
      *search.SearchForHitsAsSearchQuery(
        search.NewEmptySearchForHits().SetIndexName("INDEX_2").SetQuery("QUERY")),
    })))

​
Search for facet values

The index.SearchForFacetValues() method becomes client.SearchForFacetValues() with an indexName parameter:
Go
// version 3
index := client.InitIndex("ALGOLIA_INDEX_NAME")
res, err := index.SearchForFacetValues("category", "book", nil)

// version 4
response, err := client.SearchForFacetValues(client.NewApiSearchForFacetValuesRequest(
  "ALGOLIA_INDEX_NAME", "category"))

​
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

Go
// version 3
index := client.InitIndex("ALGOLIA_INDEX_NAME")
res, err := index.SaveObject(map[string]any{"objectID": "1", "name": "Record"})

// version 4
response, err := client.SaveObject(client.NewApiSaveObjectRequest(
  "ALGOLIA_INDEX_NAME",
  map[string]any{
    "objectID": "1",
    "name":     "Record",
  }))

​
Partially update records

Go
// version 3
index := client.InitIndex("ALGOLIA_INDEX_NAME")
res, err := index.PartialUpdateObject(map[string]any{"objectID": "1", "name": "Updated"})

// version 4
response, err := client.PartialUpdateObject(client.NewApiPartialUpdateObjectRequest(
  "ALGOLIA_INDEX_NAME", "1", map[string]any{"name": "Updated"}))

​
Delete records

Go
// version 3
index := client.InitIndex("ALGOLIA_INDEX_NAME")
res, err := index.DeleteObject("1")

// version 4
response, err := client.DeleteObject(client.NewApiDeleteObjectRequest(
  "ALGOLIA_INDEX_NAME", "1"))

​
Update settings, synonyms, and rules

​
Get and set settings

Go
// version 3
index := client.InitIndex("ALGOLIA_INDEX_NAME")
settings, err := index.GetSettings()
index.SetSettings(search.Settings{SearchableAttributes: opt.SearchableAttributes("title", "author")})

// version 4
settingsResponse, err := client.GetSettings(client.NewApiGetSettingsRequest(
  "ALGOLIA_INDEX_NAME"))

setResponse, err := client.SetSettings(client.NewApiSetSettingsRequest(
  "ALGOLIA_INDEX_NAME",
  search.NewEmptyIndexSettings().
    SetSearchableAttributes([]string{"title", "author"})))

​
Save synonyms and rules

Go
// version 3
index := client.InitIndex("ALGOLIA_INDEX_NAME")
index.SaveSynonyms([]search.Synonym{{ObjectID: "1", Type: search.RegularSynonymType, Synonyms: []string{"car", "auto"}}})
index.SaveRules([]search.Rule{{ObjectID: "1", Conditions: []search.RuleCondition{{Anchoring: search.Contains, Pattern: "shoes"}}, Consequence: search.RuleConsequence{Params: &search.RuleParams{Query: search.NewRuleQueryObject(search.RuleQueryObjectParams{Edits: []search.QueryEdit{{Type: search.Remove, Delete: "shoes", Insert: "sneakers"}}})}}}})

// version 4
synonymResponse, err := client.SaveSynonyms(client.NewApiSaveSynonymsRequest(
  "ALGOLIA_INDEX_NAME",
  []search.SynonymHit{
    *search.NewEmptySynonymHit().SetObjectID("1").
      SetType(search.SynonymType("synonym")).
      SetSynonyms([]string{"car", "auto"}),
  }))

rulesResponse, err := client.SaveRules(client.NewApiSaveRulesRequest(
  "ALGOLIA_INDEX_NAME",
  []search.Rule{
    *search.NewEmptyRule().SetObjectID("1").
      SetConditions([]search.Condition{
        *search.NewEmptyCondition().SetPattern("shoes").SetAnchoring(search.Anchoring("contains")),
      }).
      SetConsequence(search.NewEmptyConsequence().SetParams(
        search.NewEmptyConsequenceParams().SetFilters("brand:sneakers"))),
  }))
In version 3, index.ReplaceAllRules() and index.ReplaceAllSynonyms() replaced all rules or synonyms. In version 4, use client.SaveRules() or client.SaveSynonyms() with the WithClearExistingRules(true) or WithReplaceExistingSynonyms(true) option on the request builder.

​
Update index management

The CopyIndex, MoveIndex, CopyRules, CopySynonyms, and CopySettings methods are all replaced by a single OperationIndex method.

​
Copy an index

Go
// version 3
client.CopyIndex("SOURCE_INDEX_NAME", "DESTINATION_INDEX_NAME")

// version 4
response, err := client.OperationIndex(client.NewApiOperationIndexRequest(
  "SOURCE_INDEX_NAME",
  search.NewEmptyOperationIndexParams().
    SetOperation(search.OperationType("copy")).
    SetDestination("DESTINATION_INDEX_NAME")))

​
Move (rename) an index

Go
// version 3
client.MoveIndex("SOURCE_INDEX_NAME", "DESTINATION_INDEX_NAME")

// version 4
response, err := client.OperationIndex(client.NewApiOperationIndexRequest(
  "SOURCE_INDEX_NAME",
  search.NewEmptyOperationIndexParams().
    SetOperation(search.OperationType("move")).
    SetDestination("DESTINATION_INDEX_NAME")))

​
Copy only rules or settings

In version 4, use the SetScope parameter to limit the operation to specific data:
Go
// version 4 -- copy only rules and settings from one index to another
response, err := client.OperationIndex(client.NewApiOperationIndexRequest(
  "SOURCE_INDEX_NAME",
  search.NewEmptyOperationIndexParams().
    SetOperation(search.OperationType("copy")).
    SetDestination("DESTINATION_INDEX_NAME").
    SetScope([]search.ScopeType{
      search.ScopeType("rules"),
      search.ScopeType("settings"),
    })))

​
Update task handling

Version 3 supported chaining .Wait() on operations. Version 4 replaces this pattern with dedicated wait helpers.
Go
// version 3
index := client.InitIndex("ALGOLIA_INDEX_NAME")
res, err := index.SaveObjects(records)
res.Wait()

// version 4
response, err := client.SaveObjects("ALGOLIA_INDEX_NAME", records)
client.WaitForTask("ALGOLIA_INDEX_NAME", *response[0].TaskID)
Version 4 includes three wait helpers:

​
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.GetStatus→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
Last modified on March 2, 2026