API Reference / API Methods / Upgrade guides for the Ruby API client

Upgrade guides for the Ruby API client

Upgrade from v1 to v2

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 versions 2.2 and up.

Estimated upgrade time: 20-30 minutes.

Upgrading the library

In your Gemfile, remove the algoliasearch gem, and replace it with the algolia gem.

Copy 
1
2

- gem 'algoliasearch'
+ gem 'algolia'

Then, run the following command to install all dependencies:

Copy 
$

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:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# Before
client = Algolia::Client.new(
   application_id: 'YourApplicationID',
   api_key: 'YourAdminAPIKey'
)
index = client.init_index('index_name')

# After - Option 1
client = Algolia::Search::Client.create('YourApplicationID', 'YourAdminAPIKey')
index = client.init_index('index_name')

# After - Option 2
search_config = Algolia::Search::Config.new(application_id: 'YourApplicationID', api_key: 'YourAdminAPIKey')
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:

Copy 
1
2

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)

Instantiating 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 relied on set_extra_headers method, or configured timeouts by passing options to the client during initialization, you need to change your code to use a configuration object.

For example:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

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

# After
search_config = Algolia::Search::Config.new(application_id: 'YourApplicationID', api_key: 'YourAdminAPIKey', 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:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12

# 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, it’s recommended to 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.

List of method changes

Client methods

multiple_queries

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

Copy 
1
2
3
4
5
6
7
8
9
10

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

We’ve moved this method to the Algolia::Search::Client class.

Copy 
1
2
3
4
5
6
7
8
9

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

Copy 
1
2
3
4
5
6
7
8

# 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

We’ve moved this method to the Algolia::Search::Client class.

Copy 
1
2
3
4
5

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

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

get_secured_api_key_remaining_validity

We’ve moved this method to the Algolia::Search::Client class.

Copy 
1
2
3
4
5

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

Copy 
1
2
3
4
5
6
7

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

Copy 
1
2
3
4
5
6
7

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

Copy 
1
2
3
4
5
6
7

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

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

Index methods

We’ve combined searchParameters and opts into a single parameter.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12

# 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

We’ve combined searchParameters and opts into a single parameter.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12

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

Copy 
1
2
3
4
5

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

Copy 
1
2
3
4
5

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

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

add_object and add_objects

We removed these methods in favor of save_object and save_objects.

partial_update_object

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.

Copy 
1
2
3
4
5
6
7
8

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 create_if_not_exists parameter is now part of the opts parameter.

Copy 
1
2
3
4
5
6

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

Copy 
1
2
3
4
5

# Before
index.clear_index

# After
index.clear_objects

get_object and get_objects

The attributesToRetrieve parameter is now part of the opts.

Copy 
1
2
3
4
5
6
7

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

Copy 
1
2
3
4
5

# Before
client.delete_index('foo')

# After
index.delete

browse

Renamed to browse_objects.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

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

Copy 
1
2
3
4
5
6

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

Copy 
1
2
3
4
5
6

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

Copy 
1
2
3
4
5

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

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

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

Copy 
1
2
3
4
5
6
7

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

Copy 
1
2
3
4
5
6

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

Copy 
1
2
3
4
5
6

# Before
forward_to_replicas = true
index.clear_rules(forward_to_replicas)

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

export_rules

Renamed to browse_rules.

Copy 
1
2
3
4
5

# Before
index.export_rules

# After
index.browse_rules

Did you find this page helpful?

Ruby v2