Keep your Go API client up to date to benefit from improvements and bug fixes.
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.
// version 3import "github.com/algolia/algoliasearch-client-go/v3/algolia/search"// version 4import "github.com/algolia/algoliasearch-client-go/v4/algolia/search"
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.
The index.Search() method is now client.SearchSingleIndex().
Build the request with NewApiSearchSingleIndexRequest and attach search parameters with WithSearchParams:
Go
// version 3index := client.InitIndex("INDEX_NAME")res, err := index.Search("QUERY", opt.Filters("category:Book"))// version 4response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest( "INDEX_NAME").WithSearchParams( search.SearchParamsObjectAsSearchParams( search.NewEmptySearchParamsObject(). SetQuery("QUERY"). SetFacetFilters(search.ArrayOfFacetFiltersAsFacetFilters([]search.FacetFilters{*search.StringAsFacetFilters("category:Book")})))))
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.
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 anotherresponse, 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"), })))
In version 3, you could check if an index existed using the Exists method on the index object.
In version 4, use the IndexExists helper method on the client:
Go
// version 3index := client.InitIndex("INDEX_NAME")ok, err := index.Exists()// version 4response, err := client.IndexExists("INDEX_NAME")
The opt.Safe() functional option has been removed. In version 3, passing opt.Safe(true) caused the helper to wait after each step. In version 4, the helper always waits—equivalent to the previous opt.Safe(true) behavior.
Go
// version 3res, err := index.ReplaceAllObjects(objects, opt.Safe(true))// version 4res, err := client.ReplaceAllObjects(search.ReplaceAllObjectsParams{ IndexName: "INDEX_NAME", Objects: objects, Scopes: []search.ScopeType{search.SCOPETYPE_SETTINGS, search.SCOPETYPE_RULES, search.SCOPETYPE_SYNONYMS},})
The opt.AutoGenerateObjectIDIfNotExist() functional option has been removed. In version 4, every object must include an ObjectID. To have the API generate object IDs, use ChunkedBatch with search.ACTION_ADD_OBJECT.
Go
// version 3res, err := index.SaveObjects(objects, opt.AutoGenerateObjectIDIfNotExist(true))// version 4// Objects must include ObjectID, or use ChunkedBatch with ACTION_ADD_OBJECTres, err := client.SaveObjects(search.SaveObjectsParams{ IndexName: "INDEX_NAME", Objects: objects,})
The opt.CreateIfNotExists() functional option has been replaced with an explicit field on the params struct. The default also changed: in version 3 it defaulted to false (used partialUpdateObjectNoCreate); in version 4 it defaults to true.
Go
// version 3// Default: createIfNotExists = falseres, err := index.PartialUpdateObjects(objects, opt.CreateIfNotExists(true))// version 4// Default: createIfNotExists = trueres, err := client.PartialUpdateObjects(search.PartialUpdateObjectsParams{ IndexName: "INDEX_NAME", Objects: objects, CreateIfNotExists: algoliaUtils.ToPtr(false), // explicitly set false to match old default})
The ObjectIterator, RuleIterator, and SynonymIterator types have been removed. These helpers now use an Aggregator callback that is called with each page of results.
The helper was renamed from WaitTask to WaitForTask, moved to the client, and now returns *GetTaskResponse instead of error. The timeToWait config option is replaced by explicit WithMaxRetries and WithTimeout options—the default timeout uses exponential backoff capped at 5 seconds.
Go
// version 3err := index.WaitTask(taskID)// version 4resp, err := client.WaitForTask("INDEX_NAME", taskID)// With explicit retry controls:resp, err := client.WaitForTask("INDEX_NAME", taskID, search.WithWaitForTaskMaxRetries(50), search.WithWaitForTaskTimeout(func(count int) time.Duration { return min(time.Duration(count)*200*time.Millisecond, 5*time.Second) }),)
This is a new standalone helper in version 4. In version 3, waiting for API key operations required polling GetAPIKey manually.
Go
// Wait for a key to be created:resp, err := client.WaitForApiKey("my-api-key", search.APIKEYOPERATION_ADD, nil)// Wait for a key update (pass the expected final state):apiKey := &search.ApiKey{Acl: []search.Acl{search.ACL_SEARCH}}resp, err := client.WaitForApiKey("my-api-key", search.APIKEYOPERATION_UPDATE, search.WithWaitForApiKeyApiKey(apiKey),)
The function moved from a package-level function to a method on the client and was renamed from GenerateSecuredAPIKey to GenerateSecuredApiKey. The restrictions are now a single typed struct instead of variadic functional options.
Go
// version 3key, err := search.GenerateSecuredAPIKey("parentApiKey", opt.ValidUntil(1893456000), opt.RestrictIndices("INDEX_NAME"),)// version 4key, err := client.GenerateSecuredApiKey("parentApiKey", &search.SecuredApiKeyRestrictions{ ValidUntil: algoliaUtils.ToPtr(int64(1893456000)), RestrictIndices: []string{"INDEX_NAME"},})
In version 3, the Account type provided a CopyIndex method for copying an index between two different Algolia applications. It accepted two *Index values, each carrying its own app credentials.In version 4, the Account type is removed. You can compose existing helpers across two clients to achieve the same result.
New in version 4. Routes objects through the Algolia Push connector. Requires the IngestionTransporter to be configured at client initialization via a region.
New in version 4. Atomically replaces all objects via the Push connector (copy settings/rules/synonyms to a temp index → push objects → move back). Requires the IngestionTransporter to be configured at client initialization.
