Upgrade the Ruby API client to version 3

The latest major version of the algolia gem is version 3. This page helps you upgrade from version 2 and explains the breaking changes you need to address. Algolia generates the version 3 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 init_index pattern: all methods are now on the client instance directly, with index_name as a parameter. For the full list of changes, see the Ruby changelog.

Update your dependencies

Update the algolia gem to version 3:

Command line

bundle add algolia --version '~> 3.0'
# or: gem install algolia -v '~> 3.0'

The gem name stays algolia. Don’t confuse it with the older algoliasearch gem, which installs version 1.

Update imports

The module paths for API clients changed. Algolia::Search::Client is now Algolia::SearchClient, and all other clients follow the same flattened pattern.

Ruby

# version 2
require "algolia"
Algolia::Search::Client

# version 3
require "algolia"
Algolia::SearchClient

Version 3 includes dedicated client classes for each API:

Ruby

# Search API
Algolia::SearchClient
# Recommend API
Algolia::RecommendClient
# A/B testing API
Algolia::AbtestingClient
# Analytics API
Algolia::AnalyticsClient
# Ingestion API
Algolia::IngestionClient
# Insights API
Algolia::InsightsClient
# Monitoring API
Algolia::MonitoringClient
# Personalization API
Algolia::PersonalizationClient
# Query Suggestions API
Algolia::QuerySuggestionsClient
# Usage API
Algolia::UsageClient

Update client initialization

Besides the class name change, client creation follows the same pattern. The constructor still accepts your application ID and API key:

Ruby

# version 2
client = Algolia::Search::Client.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")

# version 3
client = Algolia::SearchClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")

The other major change concerns what follows initialization: init_index no longer exists.

Remove `init_index`

This is the most significant change when upgrading. Version 2 relied on an index object with methods called on it. In version 3, all methods belong to the client instance, with index_name as a parameter.

Ruby

# version 2
client = Algolia::Search::Client.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
index = client.init_index("INDEX_NAME")
index.search("QUERY")

# version 3
client = Algolia::SearchClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
client.search_single_index("INDEX_NAME", Algolia::Search::SearchParamsObject.new(query: "QUERY"))

If you have many files to update, search your codebase for init_index or .init_index( to find every place that needs changing.

Update search calls

Search a single index

The index.search method is now client.search_single_index. Pass the index name and search parameters as positional arguments:

Ruby

# version 2
index = client.init_index("INDEX_NAME")
results = index.search("QUERY", {
  facetFilters: ["category:Book"]
})

# version 3
results = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(query: "QUERY", facet_filters: ["category:Book"])
)

Search multiple indices

The client.multiple_queries method is now client.search. Each request in the array requires an index_name:

Ruby

# version 2
results = client.multiple_queries([
  {indexName: "INDEX_1", query: "QUERY"},
  {indexName: "INDEX_2", query: "QUERY"}
])

# version 3
response = client.search(
  Algolia::Search::SearchMethodParams.new(
    requests: [
      Algolia::Search::SearchForHits.new(index_name: "INDEX_1", query: "QUERY"),
      Algolia::Search::SearchForHits.new(index_name: "INDEX_2", query: "QUERY")
    ]
  )
)

The index.search_for_facet_values method becomes client.search_for_facet_values with an index_name parameter:

Ruby

# version 2
index = client.init_index("INDEX_NAME")
results = index.search_for_facet_values("category", "book")

# version 3
results = client.search_for_facet_values(
  "INDEX_NAME",
  "category",
  Algolia::Search::SearchForFacetValuesRequest.new(facet_query: "book")
)

Update indexing operations

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

Add or replace records

Ruby

# version 2
index = client.init_index("INDEX_NAME")
index.save_object({objectID: "1", name: "Record"})
index.save_objects([{objectID: "1", name: "Record"}])

# version 3
client.save_object("INDEX_NAME", {objectID: "1", name: "Record"})
client.save_objects("INDEX_NAME", [{objectID: "1", name: "Record"}])

Partially update records

Ruby

# version 2
index = client.init_index("INDEX_NAME")
index.partial_update_object({objectID: "1", name: "Updated"})

# version 3
client.partial_update_object("INDEX_NAME", "1", {name: "Updated"})

Delete records

Ruby

# version 2
index = client.init_index("INDEX_NAME")
index.delete_object("1")

# version 3
client.delete_object("INDEX_NAME", "1")

Update settings, synonyms, and rules

Get and set settings

Ruby

# version 2
index = client.init_index("INDEX_NAME")
settings = index.get_settings
index.set_settings({searchableAttributes: ["title", "author"]})

# version 3
settings = client.get_settings("INDEX_NAME")
client.set_settings(
  "INDEX_NAME",
  Algolia::Search::IndexSettings.new(searchable_attributes: ["title", "author"])
)

Save synonyms and rules

Ruby

# version 2
index = client.init_index("INDEX_NAME")
index.save_synonyms([{objectID: "1", type: "synonym", synonyms: ["car", "auto"]}])
index.save_rules([{objectID: "1", conditions: [{anchoring: "contains", pattern: "shoes"}], consequence: {params: {filters: "brand:nike"}}}])

# version 3
client.save_synonyms(
  "INDEX_NAME",
  [Algolia::Search::SynonymHit.new(algolia_object_id: "1", type: "synonym", synonyms: ["car", "auto"])]
)
client.save_rules(
  "INDEX_NAME",
  [Algolia::Search::Rule.new(
    algolia_object_id: "1",
    conditions: [Algolia::Search::Condition.new(pattern: "shoes", anchoring: "contains")],
    consequence: Algolia::Search::Consequence.new(
      params: Algolia::Search::ConsequenceParams.new(filters: "brand:nike")
    )
  )]
)

In version 2, index.replace_all_rules and index.replace_all_synonyms replaced all rules or synonyms. In version 3, use client.save_rules or client.save_synonyms with clear_existing_rules or replace_existing_synonyms set to true.

Update index management

The copy_index, move_index, copy_rules, copy_synonyms, and copy_settings methods are all replaced by a single operation_index method.

Copy an index

Ruby

# version 2
client.copy_index("SOURCE_INDEX_NAME", "DESTINATION_INDEX_NAME")

# version 3
client.operation_index(
  "SOURCE_INDEX_NAME",
  Algolia::Search::OperationIndexParams.new(operation: "copy", destination: "DESTINATION_INDEX_NAME")
)

Move (rename) an index

Ruby

# version 2
client.move_index("SOURCE_INDEX_NAME", "DESTINATION_INDEX_NAME")

# version 3
client.operation_index(
  "SOURCE_INDEX_NAME",
  Algolia::Search::OperationIndexParams.new(operation: "move", destination: "DESTINATION_INDEX_NAME")
)

Copy only rules or settings

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

Ruby

# version 3 -- copy only rules and settings from one index to another
client.operation_index(
  "SOURCE_INDEX_NAME",
  Algolia::Search::OperationIndexParams.new(
    operation: "copy",
    destination: "DESTINATION_INDEX_NAME",
    scope: ["rules", "settings"]
  )
)

Check if an index exists

In version 2, you could check if an index existed using the exists? method on the index object. In version 3, use the index_exists helper method on the client:

Ruby

# version 2
index = client.init_index("INDEX_NAME")
index.exists?

# version 3
client.index_exists("INDEX_NAME")

Update task handling

Version 2 supported chaining .wait on operations. Version 3 replaces this pattern with dedicated wait helpers or the built-in wait_for_tasks parameter.

Ruby

# version 2
index = client.init_index("INDEX_NAME")
index.save_objects(records).wait

# version 3 -- the third argument (true) waits for tasks to complete
client.save_objects("INDEX_NAME", records, true)

Version 3 includes three wait helpers:

wait_for_task: wait until indexing operations are done.
wait_for_app_task: wait for application-level tasks.
wait_for_api_key: wait for API key operations.

Helper method changes

The following sections document breaking changes in helper method signatures and behavior between version 2 and version 3.

Bang methods removed

All bang (!) variants of helper methods have been removed. In version 2, bang methods (save_objects!, delete_objects!, partial_update_objects!, replace_all_objects!) automatically waited for indexing tasks to complete. In version 3, pass true as the wait_for_tasks argument instead.

Ruby

# version 2
index.save_objects!(objects)
index.delete_objects!(["id1", "id2"])
index.partial_update_objects!(objects)
index.replace_all_objects!(objects)

# version 3
client.save_objects("INDEX_NAME", objects, true)
client.delete_objects("INDEX_NAME", ["id1", "id2"], true)
client.partial_update_objects("INDEX_NAME", objects, true, true) # create_if_not_exists, wait_for_tasks
client.replace_all_objects("INDEX_NAME", objects)

`replace_all_objects`

The safe: option has been removed. In version 2, safe: true caused the helper to wait after each step. In version 3, the helper always waits—equivalent to the previous safe: true behavior. The scopes parameter is optional. When omitted, it defaults to all three: settings, rules, and synonyms.

Ruby

# version 2
index.replace_all_objects(objects, safe: true)

# version 3
client.replace_all_objects("INDEX_NAME", objects)

`save_objects` and `delete_objects`

Two new optional parameters are available in version 3: wait_for_tasks (default false) and batch_size (default 1,000). In version 2, you had to call the bang variants to wait for tasks.

Ruby

# version 2
index.save_objects(objects)
index.delete_objects(["id1", "id2"])

# version 3
client.save_objects("INDEX_NAME", objects, wait_for_tasks: false, batch_size: 1000)
client.delete_objects("INDEX_NAME", ["id1", "id2"], wait_for_tasks: false, batch_size: 1000)

`browse_objects`, `browse_rules`, `browse_synonyms`

These helpers moved from the index object to the client and now accept index_name as an explicit first argument. The block receives individual records—one record per block call, not a page object.

Ruby

# version 2
index.browse_objects do |object|
  process(object)
end

# version 3
client.browse_objects("INDEX_NAME") do |object|
  process(object)
end

`generate_secured_api_key` and `get_secured_api_key_remaining_validity`

Both methods were class methods in version 2. In version 3, they are available both as instance methods on the client and as class methods on Algolia::Search::SearchClient.

Ruby

# version 2
key = Algolia::SearchClient.generate_secured_api_key("parentApiKey", { validUntil: 1893456000 })
remaining = Algolia::SearchClient.get_secured_api_key_remaining_validity(key)

# version 3
key = client.generate_secured_api_key("parentApiKey", { validUntil: 1893456000 })
remaining = client.get_secured_api_key_remaining_validity(key)

# Class method still works too:
key = Algolia::Search::SearchClient.generate_secured_api_key("parentApiKey", { validUntil: 1893456000 })

`wait_for_task`

The helper was renamed from wait_task and moved from the index object to the client. The index_name parameter is now required as an explicit argument.

Ruby

# version 2
index.wait_task(task_id)

# version 3
client.wait_for_task("INDEX_NAME", task_id)

`wait_for_api_key`

In version 2, waiting for API key operations was done by calling .wait on the response object returned by add_api_key, update_api_key, or delete_api_key. Version 3 provides a standalone wait_for_api_key helper.

Ruby

# version 2
response = client.add_api_key(["search"])
response.wait

# version 3
client.add_api_key(acl: ["search"])
client.wait_for_api_key("my-api-key", "add")

# Wait for an update (pass the expected final state):
client.wait_for_api_key("my-api-key", "update",
  Search::ApiKey.new(acl: ["search", "browse"])
)

`wait_for_app_task` and `chunked_batch`

These are new helpers in version 3 with no equivalent in version 2.

Ruby

# Wait for an application-level task:
client.wait_for_app_task(task_id)

# Batch objects in chunks with a chosen action:
client.chunked_batch("INDEX_NAME", objects, Action::ADD_OBJECT, true)

`index_exists?`

This is a new helper in version 3.

Ruby

# version 2
# No equivalent — had to rescue NotFoundException from get_settings

# version 3
exists = client.index_exists?("INDEX_NAME")

`copy_index_between_applications`

In version 2, the separate Algolia::AccountClient class provided a copy_index method for copying an index between two different Algolia applications. It accepted two index objects, each belonging to a different client. In version 3, AccountClient is removed. You can compose existing helpers across two clients to achieve the same result.

Ruby

# version 2
account_client = Algolia::AccountClient.new
account_client.copy_index(src_index, dest_index)

# version 3
src = Algolia::SearchClient.create("SRC_APP_ID", "SRC_API_KEY")
dst = Algolia::SearchClient.create("DST_APP_ID", "DST_API_KEY")

# Copy settings
settings = src.get_settings("SOURCE_INDEX")
dst.set_settings("DEST_INDEX", settings)

# Copy rules
rules = []
src.browse_rules("SOURCE_INDEX") { |rule| rules << rule }
dst.save_rules("DEST_INDEX", rules) unless rules.empty?

# Copy synonyms
synonyms = []
src.browse_synonyms("SOURCE_INDEX") { |synonym| synonyms << synonym }
dst.save_synonyms("DEST_INDEX", synonyms) unless synonyms.empty?

# Copy objects
objects = []
src.browse_objects("SOURCE_INDEX") { |object| objects << object }
dst.replace_all_objects("DEST_INDEX", objects)

`save_objects_with_transformation`

In version 3 and later: routes records with the Push to Algolia connector. Requires set_transformation_options to be called, or the client created via Algolia::SearchClient.with_transformation.

Ruby

client = Algolia::SearchClient.with_transformation(
  "ALGOLIA_APPLICATION_ID",
  "ALGOLIA_API_KEY",
  Algolia::TransformationOptions.new("us")
)

client.save_objects_with_transformation("INDEX_NAME", objects, false, 1000)

`replace_all_objects_with_transformation`

In version 3 and later: 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.

Ruby

client.replace_all_objects_with_transformation("INDEX_NAME", objects, 1000)

`partial_update_objects_with_transformation`

In version 3 and later: routes partial updates with the Push to Algolia connector. The create_if_not_exists parameter defaults to false.

Ruby

client.partial_update_objects_with_transformation("INDEX_NAME", objects, false, false, 1000)

Method changes reference

The following tables list all method names that changed between version 2 and version 3.

A few methods were also renamed: list_indexes is now list_indices, and get_top_user_id is now get_top_user_ids.

Search API client

Version 2 (legacy)		Version 3 (current)
`client.add_api_key`	→	`client.add_api_key`
`client.add_api_key.wait`	→	`client.wait_for_api_key`
`client.clear_dictionary_entries`	→	`client.batch_dictionary_entries`
`client.copy_index`	→	`client.operation_index`
`client.copy_rules`	→	`client.operation_index`
`client.copy_synonyms`	→	`client.operation_index`
`client.delete_api_key`	→	`client.delete_api_key`
`client.delete_dictionary_entries`	→	`client.batch_dictionary_entries`
`client.generate_secured_api_key`	→	`client.generate_secured_api_key`
`client.get_api_key`	→	`client.get_api_key`
`client.get_secured_api_key_remaining_validity`	→	`client.get_secured_api_key_remaining_validity`
`client.get_top_user_id`	→	`client.get_top_user_ids`
`client.list_api_keys`	→	`client.list_api_keys`
`client.list_indexes`	→	`client.list_indices`
`client.move_index`	→	`client.operation_index`
`client.multiple_batch`	→	`client.multiple_batch`
`client.multiple_queries`	→	`client.search`
`client.replace_dictionary_entries`	→	`client.batch_dictionary_entries`
`client.restore_api_key`	→	`client.restore_api_key`
`client.save_dictionary_entries`	→	`client.batch_dictionary_entries`
`client.update_api_key`	→	`client.update_api_key`
`index.batch`	→	`client.batch`
`index.browse_objects`	→	`client.browse_objects`
`index.browse_rules`	→	`client.browse_rules`
`index.browse_synonyms`	→	`client.browse_synonyms`
`index.clear_objects`	→	`client.clear_objects`
`index.clear_rules`	→	`client.clear_rules`
`index.clear_synonyms`	→	`client.clear_synonyms`
`index.copy_settings`	→	`client.operation_index`
`index.delete`	→	`client.delete_index`
`index.delete_by`	→	`client.delete_by`
`index.delete_object`	→	`client.delete_object`
`index.delete_objects`	→	`client.delete_objects`
`index.delete_rule`	→	`client.delete_rule`
`index.delete_synonym`	→	`client.delete_synonym`
`index.exists?`	→	`client.index_exists?`
`index.find_object`	→	`client.search_single_index`
`index.get_object`	→	`client.get_object`
`index.get_objects`	→	`client.get_objects`
`index.get_rule`	→	`client.get_rule`
`index.get_settings`	→	`client.get_settings`
`index.get_synonym`	→	`client.get_synonym`
`index.get_task`	→	`client.get_task`
`index.partial_update_object`	→	`client.partial_update_object`
`index.partial_update_objects`	→	`client.partial_update_objects`
`index.replace_all_objects`	→	`client.replace_all_objects`
`index.replace_all_rules`	→	`client.save_rules`
`index.replace_all_synonyms`	→	`client.save_synonyms`
`index.save_object`	→	`client.save_object`
`index.save_objects`	→	`client.save_objects`
`index.save_rule`	→	`client.save_rule`
`index.save_rules`	→	`client.save_rules`
`index.save_synonym`	→	`client.save_synonym`
`index.save_synonyms`	→	`client.save_synonyms`
`index.search`	→	`client.search_single_index`
`index.search_for_facet_values`	→	`client.search_for_facet_values`
`index.search_rules`	→	`client.search_rules`
`index.search_synonyms`	→	`client.search_synonyms`
`index.set_settings`	→	`client.set_settings`
`index.{operation}.wait`	→	`client.wait_for_task`

Version 2 (legacy)		Version 3 (current)
`client.get_frequently_bought_together`	→	`client.get_recommendations`
`client.get_recommendations`	→	`client.get_recommendations`
`client.get_related_products`	→	`client.get_recommendations`

API clients (current)

Reference

Upgrade the Ruby API client to version 3

Update your dependencies

Update imports

Update client initialization

Remove `init_index`

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

Check if an index exists

Update task handling

Helper method changes

Bang methods removed

`replace_all_objects`

`save_objects` and `delete_objects`

`browse_objects`, `browse_rules`, `browse_synonyms`

`generate_secured_api_key` and `get_secured_api_key_remaining_validity`

`wait_for_task`

`wait_for_api_key`

`wait_for_app_task` and `chunked_batch`

`index_exists?`

`copy_index_between_applications`

`save_objects_with_transformation`

`replace_all_objects_with_transformation`

`partial_update_objects_with_transformation`

Method changes reference

Search API client

​Update your dependencies

​Update imports

​Update client initialization

​Remove init_index

​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

​Check if an index exists

​Update task handling

​Helper method changes

​Bang methods removed

​replace_all_objects

​save_objects and delete_objects

​browse_objects, browse_rules, browse_synonyms

​generate_secured_api_key and get_secured_api_key_remaining_validity

​wait_for_task

​wait_for_api_key

​wait_for_app_task and chunked_batch

​index_exists?

​copy_index_between_applications

​save_objects_with_transformation

​replace_all_objects_with_transformation

​partial_update_objects_with_transformation

​Method changes reference

​Search API client

​Recommend API client

Update your dependencies

Update imports

Update client initialization

Remove `init_index`

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

Check if an index exists

Update task handling

Helper method changes

Bang methods removed

`replace_all_objects`

`save_objects` and `delete_objects`

`browse_objects`, `browse_rules`, `browse_synonyms`

`generate_secured_api_key` and `get_secured_api_key_remaining_validity`

`wait_for_task`

`wait_for_api_key`

`wait_for_app_task` and `chunked_batch`

`index_exists?`

`copy_index_between_applications`

`save_objects_with_transformation`

`replace_all_objects_with_transformation`

`partial_update_objects_with_transformation`

Method changes reference

Search API client

Recommend API client