Upgrade the Ruby API client to version 3

Keep your Ruby API client up to date to benefit from improvements and bug fixes.

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:

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("ALGOLIA_INDEX_NAME")
index.search("QUERY")

# version 3
client = Algolia::SearchClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
client.search_single_index("ALGOLIA_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("ALGOLIA_INDEX_NAME")
results = index.search("QUERY", {
  facetFilters: ["category:Book"]
})

# version 3
results = client.search_single_index(
  "ALGOLIA_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")
    ]
  )
)

Search for facet values

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("ALGOLIA_INDEX_NAME")
results = index.search_for_facet_values("category", "book")

# version 3
results = client.search_for_facet_values(
  "ALGOLIA_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("ALGOLIA_INDEX_NAME")
index.save_object({objectID: "1", name: "Record"})
index.save_objects([{objectID: "1", name: "Record"}])

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

Partially update records

Ruby

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

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

Delete records

Ruby

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

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

Update settings, synonyms, and rules

Get and set settings

Ruby

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

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

Save synonyms and rules

Ruby

# version 2
index = client.init_index("ALGOLIA_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(
  "ALGOLIA_INDEX_NAME",
  [Algolia::Search::SynonymHit.new(algolia_object_id: "1", type: "synonym", synonyms: ["car", "auto"])]
)
client.save_rules(
  "ALGOLIA_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"]
  )
)

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("ALGOLIA_INDEX_NAME")
index.save_objects(records).wait

# version 3 -- the third argument (true) waits for tasks to complete
client.save_objects("ALGOLIA_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.

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.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

Recommend API client

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