API client / Getting started / Update

Update the Ruby API client

A

You should keep your Ruby API client up to date to benefit from improvements and bug fixes. Algolia’s Service Level Agreement only applies to the latest version of the API client.

The Ruby API client follows Semantic Versioning. You can check what the latest version of the API client is on the GitHub release page.

Upgrade from v1 to v2# A

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.

Upgrading the library# A

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

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

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: 'AJ0P3S7DWQ',
  api_key: '••••••••••••••••••••'
)
index = client.init_index('index_name')

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

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

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: 'AJ0P3S7DWQ',
  api_key: '••••••••••••••••••••',
  connect_timeout: 2,
  receive_timeout: 10,
})

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

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

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

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#

search#

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