Skip to content

Latest commit

 

History

History
603 lines (473 loc) · 13.2 KB

upgrade_guide.md

File metadata and controls

603 lines (473 loc) · 13.2 KB
Raw

Upgrading to v2 of the Ruby API client

Gem

First, you'll have to include the new version in your Gemfile. To do so, change the following:

- gem 'algoliasearch'
+ gem 'algolia', git: 'https://github.com/algolia/algoliasearch-client-ruby.git', tag: 'v2.0.0-beta.1'

Then, you'll need to change your current require statements:

- require 'algoliasearch'
+ require 'algolia'

Class names

All classes have been namespaced. The mostly 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

Initialize the client and index

There's a slight change in how you initialize the client. The index initialization didn't change.

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

# After
client = Algolia::Search::Client.create('APP_ID', 'API_KEY')
index = client.init_index('index_name')
# or
search_config = Algolia::Search::Config.new(application_id: app_id, api_key: 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 wish to change that for strings, use the following configuration

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)

Search parameters and request options

The search parameters and request options are still optional, but they are combined into a single hash instead of two. For example:

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

Methods

Client

set_extra_header

The set_extra_header method has been moved from the Client to the Algolia::BaseConfig class. You have to define your extra headers on Client instantiation.

# Before
client.set_extra_header('admin', 'admin-key')

# After
# `Algolia::Search::Config` inherits from `Algolia::BaseConfig` 
config = Algolia::Search::Config.new(app_id: 'APP_ID', api_key: 'API_KEY')
config.set_extra_header('admin', 'admin-key')

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

multiple_queries

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

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' })

copy_settings

No change.

list_indexes

No change.

copy_index

No change.

move_index

No change.

generate_secured_api_key

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

# 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 still the first parameter. The other parameters have been moved to the requestOptions.

# 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 moved to the Algolia::Search::Client class.

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

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

delete_api_key

No change.

restore_api_key

No change.

get_api_key

No change.

list_api_keys

No change.

get_secured_api_key_remaining_validity

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

# Before
Algolia.get_secured_api_key_remaining_validity('api_key')

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

copy_synonyms

No change.

assign_user_id

No change.

assign_user_ids

Newly added method to add multiple userIDs to a cluster.

user_ids = ['1','2','3']

# Before
user_ids.each { |id| client.assign_user_id(id, 'my-cluster')}

# After
client.assign_user_ids(user_ids, 'my-cluster')

get_top_user_id

No change.

get_user_id

No change.

list_clusters

No change.

list_user_ids

The page and hitsPerPage parameters are now part of the requestOptions.

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

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

remove_user_id

No change.

search_user_ids

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

# 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', hitPerPage: 12, page: 0 })

pending_mappings

New method to check the status of your clusters' migration or user creation.

client.pending_mappings?({ retrieveMappings: true })

get_logs

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

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

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

copy_rules

No change.

Index

search

searchParameters and requestOptions are a single parameter now.

# 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 requestOptions are a single parameter now.

# 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 requestOptions as the second

# 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 classname has changed, not the method itself.

# 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 have been removed in favor of save_object and save_objects.

save_object and save_objects

No change.

partial_update_object

The objectID parameter is removed. create_if_not_exists is now part of the requestOptions parameter.

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

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

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

delete_object and delete_objects

No change.

replace_all_objects

No change.

delete_by

No change.

clear_index

Renamed to clear_objects.

# Before
index.clear_index

# After
index.clear_objects

get_object and get_objects

The attributesToRetrieve parameter is now part of the requestOptions.

# 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'] })

multiple_get_objects

No change.

batch

No change.

get_settings

No change.

set_settings

No change.

delete_index

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

# Before
client.delete_index('foo')

# After
index.delete

browse

Renamed to browse_objects.

# 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

index.exists?

No change.

save_synonym

The objectID parameter has been removed, and should be part of the synonym hash.

# 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. forwardToReplicas and replaceExistingSynonyms parmameters are now part of requestOptions.

# 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 })

delete_synonym

No change.

clear_synonyms

No change.

get_synonym

No change.

search_synonyms

No change.

replace_all_synonyms

No change.

export_synonyms

Renamed to browse_synonyms.

# Before
synonyms = index.export_synonyms

# After
synonyms = index.browse_synonyms

save_rule

The objectID parameter has been removed, and should be part of the Rule object.

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

# After
index.save_rule({
  objectID: 'unique-id',
  condition: { 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 requestOptions.

# 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 })

get_rule

No change.

delete_rule

The forwardToReplicas parameter is now part of the requestOptions.

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

# Before
forward_to_replicas = true
index.clear_rules(forward_to_replicas)

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

search_rules

No change.

replace_all_rules

No change.

export_rules

Renamed to browse_rules.

AnalyticsClient

add_ab_test

No change.

get_ab_test

No change.

get_ab_tests

No change.

stop_ab_test

No change.

delete_ab_test

No change.

InsightsClient

clicked_object_ids_after_search

No change.

clicked_object_ids

No change.

clicked_filters

No change.

converted_object_ids_after_search

No change.

converted_object_ids

No change.

converted_filters

No change.

viewed_object_ids

No change.

viewed_filters

No change.

RecommendationClient

set_personalization_strategy

This new method is available on the Algolia::Recommendation::Client class.

set_personalization_strategy

This new method is available on the Algolia::Recommendation::Client class.

Configuring timeouts

You can configure timeouts by passing a custom Algolia::Search::Config object to the constructor of your client.

# Before
client = Algolia::Client.new({
  application_id: 'app_id',
  api_key: 'api_key',
  connect_timeout: 2,
  receive_timeout: 10,
})

# After
search_config = Algolia::Search::Config.new(application_id: 'app_id', api_key: 'api_key', read_timeout: 10, connect_timeout: 2)
client = Algolia::Search::Client.create_with_config(search_config)