Upgrade the Ruby API client to version 2

The Ruby API client follows semantic versioning.

Upgrade from version 1 to version 2

The Ruby client is fully rebuilt while keeping a similar design to make it as smooth as possible to upgrade. It’s compatible with Ruby 2.2 and later.

Upgrade the library

In your Gemfile, replace the algoliasearch gem with the algolia gem.

Command line

gem 'algoliasearch'
gem 'algolia'

Then, run the following command to install all dependencies:

Command line

bundle install

Class names

Most classes have a different name and namespace in the new version. The most used classes are now as follows:

Algolia::Client → Algolia::Search::Client
Algolia::Index → Algolia::Search::Index
Algolia::AccountClient → Algolia::Account::Client
Algolia::Analytics → Algolia::Analytics::Client
Algolia::Insights → Algolia::Insights::Client

Client instantiation

There’s a slight change in how you instantiate the client. Index initialization remains the same:

Ruby

# Before
client = Algolia::Client.new(
  application_id: "ALGOLIA_APPLICATION_ID",
  api_key: "ALGOLIA_API_KEY"
)
index = client.init_index("index_name")

# After - Option 1
client = Algolia::Search::Client.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
index = client.init_index("index_name")

# After - Option 2
search_config = Algolia::Search::Config.new(application_id: "ALGOLIA_APPLICATION_ID", api_key: "ALGOLIA_API_KEY")
client = Algolia::Search::Client.create_with_config(search_config)
index = client.init_index("index_name")

By default, the keys of the response hashes are symbols. If you want the keys to be strings instead of symbols, you can set the symbolize_keys configuration option to false:

Ruby

search_config = Algolia::Search::Config.new(application_id: app_id, api_key: api_key, symbolize_keys: false)
client = Algolia::Search::Client.create_with_config(search_config)

Instantiate with configuration

You can instantiate all clients using configuration objects. This helps you change their default behavior and settings, such as the default region in the Insights client or custom hosts in the Search client. All setters have been moved from the client to the configuration object. If, for instance, you rely on the set_extra_headers method or have configured timeouts by passing options to the client during initialization, you need to change your code to use a configuration object. For example:

Ruby

# Before
Algolia.set_extra_header("NAME-OF-HEADER", "value")
client = Algolia::Client.new(
  {
    application_id: "ALGOLIA_APPLICATION_ID",
    api_key: "ALGOLIA_API_KEY",
    connect_timeout: 2,
    receive_timeout: 10
  }
)

# After
search_config = Algolia::Search::Config.new(
  application_id: "ALGOLIA_APPLICATION_ID",
  api_key: "ALGOLIA_API_KEY",
  read_timeout: 10,
  connect_timeout: 2
)
search_config.set_extra_header("NAME-OF-HEADER", "value")

client = Algolia::Search::Client.create_with_config(search_config)

Optional parameters

To have the most consistent, predictable, and future-proof method signatures, methods follow two rules:

All required parameters have a single argument each
All optional arguments are part of a hash called opts as the last argument

Most method names remain the same, just the arguments have changed. Typically, optional parameters have been removed, which you must now pass in the opts hash. The same goes for any search_parameters and request_options arguments. For example:

Ruby

# Before
request_opts = {:"X-Algolia-UserToken" => "user123"}
search_params = {hitsPerPage: 50}

index.search("query", search_params, request_opts)

# After
opts = {
  headers: {:"X-Algolia-UserToken" => "user123"},
  hitsPerPage: 50
}
index.search("query", opts)

Besides moving all optional parameters, go through all method changes to see how they’ve changed.

New methods

The new client introduces some new methods. Most of these are helper methods: the underlying feature was already available, but required either deeper understanding or custom code.

set_personalization_strategy: set the Personalization strategy for an index.
get_personalization_strategy: get the Personalization strategy for an index.
Algolia::Account::Client.copy_index: copy in an index between Algolia applications.

List of method changes

`Client` methods

`multiple_queries`

The strategy parameter is no longer a string, but a key in the opts.

Ruby

queries = [
  {indexName: "index_name1", params: {query: "query", hitsPerPage: 2}},
  {indexName: "index_name2", params: {query: "another_query", hitsPerPage: 5}}
]

# Before
client.multiple_queries(queries, "stopIfEnoughMatches")

# After
client.multiple_queries(queries, {strategy: "stopIfEnoughMatches"})

`generate_secured_api_key`

This method moved to the Algolia::Search::Client class.

Ruby

# Before
secured_api_key = Algolia.generate_secured_api_key(
  "api_key",
  {
    validUntil: now - (10 * 60)
  }
)

# After
secured_api_key = Algolia::Search::Client.generate_secured_api_key(
  "api_key",
  {
    validUntil: now - (10 * 60)
  }
)

`add_api_key`

acl is now a single parameter. The other parameters have been moved to the opts.

Ruby

# Before
client.add_api_key({acl: ["search"], description: "A description", indexes: ["index"]})

# After
client.add_api_key(
  ["search"],
  {
    description: "A description",
    indexes: ["index"]
  }
)

`update_api_key`

This method is now a member of the Algolia::Search::Client class.

Ruby

# Before
Algolia.update_api_key("api_key", {maxHitsPerQuery: 42})

# After
client.update_api_key("api_key", {maxHitsPerQuery: 42})

`get_secured_api_key_remaining_validity`

This method moved to the Algolia::Search::Client class.

Ruby

# Before
Algolia.get_secured_api_key_remaining_validity("api_key")

# After
Algolia::Search::Client.get_secured_api_key_remaining_validity("api_key")

`list_user_ids`

The page and hitsPerPage parameters are now part of the opts hash.

Ruby

# Before
page = 0
hits_per_page = 20
client.list_user_ids(page, hits_per_page)

# After
client.list_user_ids({hitsPerPage: 20, page: 0})

`search_user_ids`

The clusterName, page, and hitsPerPage parameters are now part of the opts hash.

Ruby

# Before
page = 0
hits_per_page = 12
client.search_user_ids("query", "my-cluster", page, hits_per_page)

# After
client.search_user_ids("query", {clusterName: "my-cluster", hitsPerPage: 12, page: 0})

`get_logs`

The offset, length, and type parameters are now part of the opts hash.

Ruby

# Before
offset = 5
length = 100
puts(client.get_logs(offset, length, "all"))

# After
client.get_logs({offset: 5, length: 10, type: "all"})

`Index` methods

`search`

searchParameters and opts are combined in a single parameter.

Ruby

# Before
request_opts = {:"X-Algolia-UserToken" => "user123"}
search_params = {hitsPerPage: 50}

index.search("query", search_params, request_opts)

# After
opts = {
  headers: {:"X-Algolia-UserToken" => "user123"},
  hitsPerPage: 50
}
index.search("query", opts)

`search_for_facet_values`

searchParameters and opts are combined in a single parameter.

Ruby

# Before
request_opts = {:"X-Algolia-UserToken" => "user123"}
search_params = {hitsPerPage: 50}

index.search_for_facet_values("category", "phone", search_params, request_opts)

# After
opts = {
  headers: {:"X-Algolia-UserToken" => "user123"},
  hitsPerPage: 50
}
index.search_for_facet_values("category", "phone", opts)

`find_object`

The method takes a lambda, proc, or block as the first argument (anything that responds to call), and the opts as the second.

Ruby

# Before
index.find_object({query: "query", paginate: true}) { |hit| hit[:title].include?("algolia") }

# After
index.find_object(-> (hit) { hit[:title].include?("algolia") }, {query: "query", paginate: true})

`get_object_position`

The class name has changed, but the method remains the same.

Ruby

# Before
position = Algolia::Index.get_object_position(results, "object")

# After
position = Algolia::Search::Index.get_object_position(results, "object")

`add_object` and `add_objects`

These methods are removed in favor of save_object and save_objects.

`partial_update_object`

The createIfNotExists flag is now part of the opts parameter. It defaults to false in version 2. (It was true in version 1.) You only need to specify the objectID in the record to be updated, not as an argument when using the method. createIfNotExists is now part of the opts parameter.

Ruby

obj = {objectID: "1234", prop: "value"}

# Before
create_if_not_exists = true
index.partial_update_object(obj, obj[:objectID], create_if_not_exists)

# After
index.partial_update_object(obj, {createIfNotExists: true})

`partial_update_objects`

The createIfNotExists flag is now part of the opts parameter. It defaults to false in version 2. (It was true in version 1.)

Ruby

# Before
create_if_not_exists = true
index.partial_update_objects(objects, create_if_not_exists)

# After
index.partial_update_objects(objects, {createIfNotExists: true})

`clear_index`

Renamed to clear_objects.

Ruby

# Before
index.clear_index

# After
index.clear_objects

`get_object` and `get_objects`

The attributesToRetrieve parameter is now part of the opts.

Ruby

# Before
index.get_object("1234", ["title"])
index.get_objects([1, 2, 3], ["title"])

# After
index.get_object("1234", {attributesToRetrieve: ["title"]})
index.get_objects([1, 2, 3], {attributesToRetrieve: ["title"]})

`delete_index`

Instead of calling the delete_index method on the client, you should call the delete method directly on the index object.

Ruby

# Before
client.delete_index("foo")

# After
index.delete

`browse`

Renamed to browse_objects.

Ruby

# Before
request_opts = {:"X-Algolia-UserToken" => "user123"}
index.browse({query: "query"}, nil, request_opts) do |hit|
  puts(hit)
end

# After
opts = {
  query: "query",
  headers: {:"X-Algolia-UserToken" => "user123"}
}
index.browse_objects(opts) do |hit|
  puts(hit)
end

`save_synonym`

You only need to specify the objectID in the synonym to be saved, not as an argument when using the method.

Ruby

# Before
forward_to_replicas = true
index.save_synonym("one", {objectID: "one", type: "synonym", synonyms: %w[one two]}, forward_to_replicas)

# After
index.save_synonym({objectID: "one", type: "synonym", synonyms: %w[one two]}, {forwardToReplicas: true})

`batch_synonyms`

Renamed to save_synonyms. The forwardToReplicas and replaceExistingSynonyms parameters are now part of the opts hash.

Ruby

# Before
forward_to_replicas = true
replace_existing_synonyms = true
index.batch_synonyms(synonyms, forward_to_replicas, replace_existing_synonyms)
# After
index.save_synonyms(synonyms, {forwardToReplicas: true, replaceExistingSynonyms: true})

`export_synonyms`

Renamed to browse_synonyms.

Ruby

# Before
synonyms = index.export_synonyms

# After
synonyms = index.browse_synonyms

`save_rule`

You only need to specify the objectID in the rule to be saved, not as an argument when using the method.

Ruby

# Before
index.save_rule(
  "unique-id",
  {
    objectID: "unique-id",
    conditions: [{anchoring: "is", pattern: "pattern"}],
    consequence: {
      params: {
        query: {
          edits: [
            {type: "remove", delete: "pattern"}
          ]
        }
      }
    }
  }
)

# After
index.save_rule(
  {
    objectID: "unique-id",
    conditions: [{anchoring: "is", pattern: "pattern"}],
    consequence: {
      params: {
        query: {
          edits: [
            {type: "remove", delete: "pattern"}
          ]
        }
      }
    }
  }
)

`batch_rules`

Renamed to save_rules. The forwardToReplicas and clearExistingRules parameters should now be part of the opts.

Ruby

# Before
forward_to_replicas = true
clear_existing_rules = true
index.batch_rules(rules, forward_to_replicas, clear_existing_rules)

# After
index.save_rules(rules, {forwardToReplicas: true, clearExistingRules: true})

`delete_rule`

The forwardToReplicas parameter is now part of the opts.

Ruby

# Before
forward_to_replicas = true
index.delete_rule("rule-id", forward_to_replicas)

# After
index.delete_rule("rule-id", {forwardToReplicas: true})

`clear_rules`

The forwardToReplicas parameter is now part of the opts.

Ruby

# Before
forward_to_replicas = true
index.clear_rules(forward_to_replicas)

# After
index.clear_rules({forwardToReplicas: true})

`export_rules`

Renamed to browse_rules.

Ruby

# Before
index.export_rules

# After
index.browse_rules

​Upgrade from version 1 to version 2

​Upgrade the library

​Class names

​Client instantiation

​Instantiate with configuration

​Optional parameters

​New methods

​List of method changes

​Client methods

​multiple_queries

​generate_secured_api_key

​add_api_key

​update_api_key

​get_secured_api_key_remaining_validity

​list_user_ids

​search_user_ids

​get_logs

​Index methods

​search

​search_for_facet_values

​find_object

​get_object_position

​add_object and add_objects

​partial_update_object

​partial_update_objects

​clear_index

​get_object and get_objects

​delete_index

​browse

​save_synonym

​batch_synonyms

​export_synonyms

​save_rule

​batch_rules

​delete_rule

​clear_rules

​export_rules

Upgrade from version 1 to version 2

Upgrade the library

Class names

Client instantiation

Instantiate with configuration

Optional parameters

New methods

List of method changes

`Client` methods

`multiple_queries`

`generate_secured_api_key`

`add_api_key`

`update_api_key`

`get_secured_api_key_remaining_validity`

`list_user_ids`

`search_user_ids`

`get_logs`

`Index` methods

`search`

`search_for_facet_values`

`find_object`

`get_object_position`

`add_object` and `add_objects`

`partial_update_object`

`partial_update_objects`

`clear_index`

`get_object` and `get_objects`

`delete_index`

`browse`

`save_synonym`

`batch_synonyms`

`export_synonyms`

`save_rule`

`batch_rules`

`delete_rule`

`clear_rules`

`export_rules`