Module: Algolia

Defined in:
lib/algolia/error.rb,
lib/algolia/index.rb,
lib/algolia/client.rb,
lib/algolia/version.rb,
lib/algolia/webmock.rb,
lib/algolia/insights.rb,
lib/algolia/protocol.rb,
lib/algolia/analytics.rb,
lib/algolia/account_client.rb

Defined Under Namespace

Modules: Protocol Classes: AccountClient, AlgoliaError, AlgoliaObjectNotFoundError, AlgoliaProtocolError, Analytics, Client, Index, Insights, UserInsights, ValidUntilNotFoundError, WebMock

Constant Summary collapse

WAIT_TASK_DEFAULT_TIME_BEFORE_RETRY = 
100
VERSION = 
"1.27.5"
@@client =

A singleton client Always use Algolia.client to retrieve the client object.

nil

Class Method Summary collapse

Class Method Details

.add_api_key(object, request_options = {}, max_queries_per_IP_per_hour = 0, max_hits_per_query = 0, indexes = nil) ⇒ Object

Create a new user key

Deprecated call was add_api_key(acl, validity, max_queries_per_IP_per_hour, max_hits_per_query, indexes)

ACL can contain an array with those strings:
  - search: allow to search (https and http)
  - addObject: allows to add/update an object in the index (https only)
  - deleteObject : allows to delete an existing object (https only)
  - deleteIndex : allows to delete index content (https only)
  - settings : allows to get index settings (https only)
  - editSettings : allows to change index settings (https only)

@param object can be two different parameters:
      The list of parameters for this key. Defined by a NSDictionary that
      can contains the following values:
        - acl: array of string
        - indexes: array of string
        - validity: int
        - referers: array of string
        - description: string
        - max_hits_per_query: integer
        - queryParameters: string
        - max_queries_per_IP_per_hour: integer
@param request_options contains extra parameters to send with your query - Default = {}



1022
1023
1024
 
# File 'lib/algolia/client.rb', line 1022

def Algolia.add_api_key(object, request_options = {}, max_queries_per_IP_per_hour = 0, max_hits_per_query = 0, indexes = nil)
  Algolia.client.add_api_key(object, request_options, max_queries_per_IP_per_hour, max_hits_per_query, indexes)
end

.add_user_key(object, request_options = {}, max_queries_per_IP_per_hour = 0, max_hits_per_query = 0, indexes = nil) ⇒ Object

Deprecated



1029
1030
1031
 
# File 'lib/algolia/client.rb', line 1029

def Algolia.add_user_key(object, request_options = {}, max_queries_per_IP_per_hour = 0, max_hits_per_query = 0, indexes = nil)
  Algolia.client.add_api_key(object, request_options, max_queries_per_IP_per_hour, max_hits_per_query, indexes)
end

.batch(requests, request_options = {}) ⇒ Object

Send a batch request targeting multiple indices



1094
1095
1096
 
# File 'lib/algolia/client.rb', line 1094

def Algolia.batch(requests, request_options = {})
  Algolia.client.batch(requests, request_options)
end

.batch!(requests, request_options = {}) ⇒ Object

Send a batch request targeting multiple indices and wait the end of the indexing



1101
1102
1103
 
# File 'lib/algolia/client.rb', line 1101

def Algolia.batch!(requests, request_options = {})
  Algolia.client.batch!(requests, request_options)
end

.client ⇒ Object 



1124
1125
1126
1127
1128
1129
 
# File 'lib/algolia/client.rb', line 1124

def Algolia.client
  if !@@client
    raise AlgoliaError, 'API not initialized'
  end
  @@client
end

.copy_index(src_index, dst_index, scope = nil, request_options = {}) ⇒ Object

Copy an existing index.

Parameters:

  • src_index —

    the name of index to copy.

  • dst_index —

    the new index name that will contains a copy of src_index_name (destination will be overriten if it already exist).

  • scope (defaults to: nil) —

    the optional list of scopes to copy (all if not specified).

  • request_options (defaults to: {}) —

    contains extra parameters to send with your query



856
857
858
 
# File 'lib/algolia/client.rb', line 856

def Algolia.copy_index(src_index, dst_index, scope = nil, request_options = {})
  Algolia.client.copy_index(src_index, dst_index, scope, request_options)
end

.copy_index!(src_index, dst_index, scope = nil, request_options = {}) ⇒ Object

Copy an existing index and wait until the copy has been processed.

Parameters:

  • src_index —

    the name of index to copy.

  • dst_index —

    the new index name that will contains a copy of src_index_name (destination will be overriten if it already exist).

  • scope (defaults to: nil) —

    the optional list of scopes to copy (all if not specified).

  • request_options (defaults to: {}) —

    contains extra parameters to send with your query



868
869
870
 
# File 'lib/algolia/client.rb', line 868

def Algolia.copy_index!(src_index, dst_index, scope = nil, request_options = {})
  Algolia.client.copy_index!(src_index, dst_index, scope, request_options)
end

.copy_rules(src_index, dst_index, request_options = {}) ⇒ Object

Copy an existing index rules.

Parameters:

  • src_index —

    the name of index to copy.

  • dst_index —

    the new index name that will contains a copy of src_index_name rules (destination rules will be overriten if it already exist).

  • request_options (defaults to: {}) —

    contains extra parameters to send with your query



923
924
925
 
# File 'lib/algolia/client.rb', line 923

def Algolia.copy_rules(src_index, dst_index, request_options = {})
  Algolia.client.copy_rules(src_index, dst_index, request_options)
end

.copy_rules!(src_index, dst_index, request_options = {}) ⇒ Object

Copy an existing index rules and wait until the copy has been processed.

Parameters:

  • src_index —

    the name of index to copy.

  • dst_index —

    the new index name that will contains a copy of src_index_name rules (destination rules will be overriten if it already exist).

  • request_options (defaults to: {}) —

    contains extra parameters to send with your query



934
935
936
 
# File 'lib/algolia/client.rb', line 934

def Algolia.copy_rules!(src_index, dst_index, request_options = {})
  Algolia.client.copy_rules!(src_index, dst_index, request_options)
end

.copy_settings(src_index, dst_index, request_options = {}) ⇒ Object

Copy an existing index settings.

Parameters:

  • src_index —

    the name of index to copy.

  • dst_index —

    the new index name that will contains a copy of src_index_name settings (destination settings will be overriten if it already exist).

  • request_options (defaults to: {}) —

    contains extra parameters to send with your query



879
880
881
 
# File 'lib/algolia/client.rb', line 879

def Algolia.copy_settings(src_index, dst_index, request_options = {})
  Algolia.client.copy_settings(src_index, dst_index, request_options)
end

.copy_settings!(src_index, dst_index, request_options = {}) ⇒ Object

Copy an existing index settings and wait until the copy has been processed.

Parameters:

  • src_index —

    the name of index to copy.

  • dst_index —

    the new index name that will contains a copy of src_index_name settings (destination settings will be overriten if it already exist).

  • request_options (defaults to: {}) —

    contains extra parameters to send with your query



890
891
892
 
# File 'lib/algolia/client.rb', line 890

def Algolia.copy_settings!(src_index, dst_index, request_options = {})
  Algolia.client.copy_settings!(src_index, dst_index, request_options)
end

.copy_synonyms(src_index, dst_index, request_options = {}) ⇒ Object

Copy an existing index synonyms.

Parameters:

  • src_index —

    the name of index to copy.

  • dst_index —

    the new index name that will contains a copy of src_index_name synonyms (destination synonyms will be overriten if it already exist).

  • request_options (defaults to: {}) —

    contains extra parameters to send with your query



901
902
903
 
# File 'lib/algolia/client.rb', line 901

def Algolia.copy_synonyms(src_index, dst_index, request_options = {})
  Algolia.client.copy_synonyms(src_index, dst_index, request_options)
end

.copy_synonyms!(src_index, dst_index, request_options = {}) ⇒ Object

Copy an existing index synonyms and wait until the copy has been processed.

Parameters:

  • src_index —

    the name of index to copy.

  • dst_index —

    the new index name that will contains a copy of src_index_name synonyms (destination synonyms will be overriten if it already exist).

  • request_options (defaults to: {}) —

    contains extra parameters to send with your query



912
913
914
 
# File 'lib/algolia/client.rb', line 912

def Algolia.copy_synonyms!(src_index, dst_index, request_options = {})
  Algolia.client.copy_synonyms!(src_index, dst_index, request_options)
end

.delete_api_key(key, request_options = {}) ⇒ Object

Delete an existing user key



1073
1074
1075
 
# File 'lib/algolia/client.rb', line 1073

def Algolia.delete_api_key(key, request_options = {})
  Algolia.client.delete_api_key(key, request_options)
end

.delete_index(name, request_options = {}) ⇒ Object

Delete an index



941
942
943
 
# File 'lib/algolia/client.rb', line 941

def Algolia.delete_index(name, request_options = {})
  Algolia.client.delete_index(name, request_options)
end

.delete_index!(name, request_options = {}) ⇒ Object

Delete an index and wait until the deletion has been processed.



948
949
950
 
# File 'lib/algolia/client.rb', line 948

def Algolia.delete_index!(name, request_options = {})
  Algolia.client.delete_index!(name, request_options)
end

.delete_user_key(key, request_options = {}) ⇒ Object

Deprecated



1087
1088
1089
 
# File 'lib/algolia/client.rb', line 1087

def Algolia.delete_user_key(key, request_options = {})
  Algolia.client.delete_api_key(key, request_options)
end

.destroy ⇒ Object

Used mostly for testing. Lets you delete the api key global vars.



1118
1119
1120
1121
1122
 
# File 'lib/algolia/client.rb', line 1118

def Algolia.destroy
  @@client.destroy unless @@client.nil?
  @@client = nil
  self
end

.disable_rate_limit_forward ⇒ Object

Disable IP rate limit enabled with enableRateLimitForward() function



741
742
743
 
# File 'lib/algolia/client.rb', line 741

def Algolia.disable_rate_limit_forward
  Algolia.client.disable_rate_limit_forward
end

.enable_rate_limit_forward(admin_api_key, end_user_ip, rate_limit_api_key) ⇒ Object

Allow to use IP rate limit when you have a proxy between end-user and Algolia. This option will set the X-Forwarded-For HTTP header with the client IP and the X-Forwarded-API-Key with the API Key having rate limits.

Parameters:

  • admin_api_key —

    the admin API Key you can find in your dashboard

  • end_user_ip —

    the end user IP (you can use both IPV4 or IPV6 syntax)

  • rate_limit_api_key —

    the API key on which you have a rate limit



734
735
736
 
# File 'lib/algolia/client.rb', line 734

def Algolia.enable_rate_limit_forward(admin_api_key, end_user_ip, rate_limit_api_key)
  Algolia.client.enable_rate_limit_forward(admin_api_key, end_user_ip, rate_limit_api_key)
end

.generate_secured_api_key(private_api_key, tag_filters_or_params, user_token = nil) ⇒ Object

Generate a secured and public API Key from a list of tagFilters and an optional user token identifying the current user

Parameters:

  • private_api_key —

    your private API Key

  • tag_filters —

    the list of tags applied to the query (used as security)

  • user_token (defaults to: nil) —

    an optional token identifying the current user



760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
 
# File 'lib/algolia/client.rb', line 760

def Algolia.generate_secured_api_key(private_api_key, tag_filters_or_params, user_token = nil)
  if tag_filters_or_params.is_a?(Hash) && user_token.nil?
    encoded_params = Hash[tag_filters_or_params.map { |k, v| [k.to_s, v.is_a?(Array) ? v.to_json : v] }]
    query_str = Protocol.to_query(encoded_params)
    hmac = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), private_api_key, query_str)
    Base64.encode64("#{hmac}#{query_str}").gsub("\n", '')
  else
    tag_filters = if tag_filters_or_params.is_a?(Array)
      tag_filters = tag_filters_or_params.map { |t| t.is_a?(Array) ? "(#{t.join(',')})" : t }.join(',')
    else
      tag_filters_or_params
    end
    raise ArgumentError.new('Attribute "tag_filters" must be a list of tags') if !tag_filters.is_a?(String)
    OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), private_api_key, "#{tag_filters}#{user_token.to_s}")
  end
end

.get_api_key(key, request_options = {}) ⇒ Object

Get ACL of a user key

Parameters:

  • request_options (defaults to: {}) —

    contains extra parameters to send with your query



985
986
987
 
# File 'lib/algolia/client.rb', line 985

def Algolia.get_api_key(key, request_options = {})
  Algolia.client.get_api_key(key, request_options)
end

.get_logs(options = nil, length = nil, type = nil) ⇒ Object

Return last logs entries.

Parameters:

  • offset —

    Specify the first entry to retrieve (0-based, 0 is the most recent log entry).

  • length (defaults to: nil) —

    Specify the maximum number of entries to retrieve starting at offset. Maximum allowed value: 1000.

  • type (defaults to: nil) —

    Specify the type of entries you want to retrieve - default: “all”

  • request_options —

    contains extra parameters to send with your query



960
961
962
 
# File 'lib/algolia/client.rb', line 960

def Algolia.get_logs(options = nil, length = nil, type = nil)
  Algolia.client.get_logs(options, length, type)
end

.get_secured_api_key_remaining_validity(secured_api_key) ⇒ Integer

Returns the remaining validity time for the given API key in seconds

Parameters:

  • secured_api_key (String) —

    the secured API key to check

Returns:

  • (Integer) —

    remaining validity in seconds



784
785
786
787
788
789
790
791
792
793
794
795
796
797
 
# File 'lib/algolia/client.rb', line 784

def Algolia.get_secured_api_key_remaining_validity(secured_api_key)
  now = Time.now.to_i
  decoded_key = Base64.decode64(secured_api_key)
  regex = 'validUntil=(\d+)'
  matches = decoded_key.match(regex)

  if matches === nil
    raise ValidUntilNotFoundError.new('The SecuredAPIKey doesn\'t have a validUntil parameter.')
  end

  valid_until = matches[1].to_i

  valid_until - now
end

.get_task_status(index_name, taskID, request_options = {}) ⇒ Object 



1112
1113
1114
 
# File 'lib/algolia/client.rb', line 1112

def Algolia.get_task_status(index_name, taskID, request_options = {})
  Algolia.client.get_task_status(index_name, taskID, request_options = {})
end

.get_user_key(key, request_options = {}) ⇒ Object

Deprecated



992
993
994
 
# File 'lib/algolia/client.rb', line 992

def Algolia.get_user_key(key, request_options = {})
  Algolia.client.get_user_key(key, request_options)
end

.init(options = {}) ⇒ Object

Initialize the singleton instance of Client which is used by all API methods



708
709
710
711
712
713
714
715
716
 
# File 'lib/algolia/client.rb', line 708

def Algolia.init(options = {})
  application_id = ENV['ALGOLIA_APP_ID'] || ENV['ALGOLIA_API_ID'] || ENV['ALGOLIA_APPLICATION_ID']
  api_key = ENV['ALGOLIA_REST_API_KEY'] || ENV['ALGOLIA_API_KEY']

  defaulted = { :application_id => application_id, :api_key => api_key }
  defaulted.merge!(options)

  @@client = Client.new(defaulted)
end

.list_api_keys(request_options = {}) ⇒ Object

List all existing user keys with their associated ACLs

Parameters:

  • request_options (defaults to: {}) —

    contains extra parameters to send with your query



969
970
971
 
# File 'lib/algolia/client.rb', line 969

def Algolia.list_api_keys(request_options = {})
  Algolia.client.list_api_keys(request_options)
end

.list_indexes(request_options = {}) ⇒ Object

List all existing indexes return an Answer object with answer in the form

{"items": [{ "name": "contacts", "createdAt": "2013-01-18T15:33:13.556Z"},
           {"name": "notes", "createdAt": "2013-01-18T15:33:13.556Z"}]}

Parameters:

  • request_options (defaults to: {}) —

    contains extra parameters to send with your query



822
823
824
 
# File 'lib/algolia/client.rb', line 822

def Algolia.list_indexes(request_options = {})
  Algolia.client.list_indexes(request_options)
end

.list_user_keys(request_options = {}) ⇒ Object

Deprecated



976
977
978
 
# File 'lib/algolia/client.rb', line 976

def Algolia.list_user_keys(request_options = {})
  Algolia.client.list_api_keys(request_options)
end

.move_index(src_index, dst_index, request_options = {}) ⇒ Object

Move an existing index.

Parameters:

  • src_index —

    the name of index to copy.

  • dst_index —

    the new index name that will contains a copy of src_index_name (destination will be overriten if it already exist).

  • request_options (defaults to: {}) —

    contains extra parameters to send with your query



833
834
835
 
# File 'lib/algolia/client.rb', line 833

def Algolia.move_index(src_index, dst_index, request_options = {})
  Algolia.client.move_index(src_index, dst_index, request_options)
end

.move_index!(src_index, dst_index, request_options = {}) ⇒ Object

Move an existing index and wait until the move has been processed

Parameters:

  • src_index —

    the name of index to copy.

  • dst_index —

    the new index name that will contains a copy of src_index_name (destination will be overriten if it already exist).

  • request_options (defaults to: {}) —

    contains extra parameters to send with your query



844
845
846
 
# File 'lib/algolia/client.rb', line 844

def Algolia.move_index!(src_index, dst_index, request_options = {})
  Algolia.client.move_index!(src_index, dst_index, request_options)
end

.multiple_get_objects(requests, request_options = {}) ⇒ Object

This method allows to get objects (records) via objectID across multiple indexes with one API call



810
811
812
 
# File 'lib/algolia/client.rb', line 810

def Algolia.multiple_get_objects(requests, request_options = {})
  Algolia.client.multiple_get_objects(requests, request_options)
end

.multiple_queries(queries, options = nil, strategy = nil) ⇒ Object

This method allows to query multiple indexes with one API call



802
803
804
 
# File 'lib/algolia/client.rb', line 802

def Algolia.multiple_queries(queries, options = nil, strategy = nil)
  Algolia.client.multiple_queries(queries, options, strategy)
end

.restore_api_key(key, request_options = {}) ⇒ Object

Restore an existing api key



1080
1081
1082
 
# File 'lib/algolia/client.rb', line 1080

def Algolia.restore_api_key(key, request_options = {})
  Algolia.client.restore_api_key(key, request_options)
end

.set_extra_header(key, value) ⇒ Object

Allow to set custom headers



721
722
723
 
# File 'lib/algolia/client.rb', line 721

def Algolia.set_extra_header(key, value)
  Algolia.client.set_extra_header(key, value)
end

.update_api_key(key, object, request_options = {}, max_queries_per_IP_per_hour = 0, max_hits_per_query = 0, indexes = nil) ⇒ Object

Update a user key

Deprecated call was update_api_key(key, acl, validity, maxQueriesPerIPPerHour, max_hits_per_query, indexes)

ACL can contain an array with those strings:
  - search: allow to search (https and http)
  - addObject: allows to add/update an object in the index (https only)
  - deleteObject : allows to delete an existing object (https only)
  - deleteIndex : allows to delete index content (https only)
  - settings : allows to get index settings (https only)
  - editSettings : allows to change index settings (https only)

@param key API Key to update
@param object The list of parameters for this key.
       Defined by a Hash that can contain the following values:
        - acl: array of string
        - indexes: array of string
        - validity: int
        - referers: array of string
        - description: string
        - max_hits_per_query: integer
        - queryParameters: string
        - max_queries_per_IP_per_hour: integer
@param request_options contains extra parameters to send with your query - Default = {}



1059
1060
1061
 
# File 'lib/algolia/client.rb', line 1059

def Algolia.update_api_key(key, object, request_options = {}, max_queries_per_IP_per_hour = 0, max_hits_per_query = 0, indexes = nil)
  Algolia.client.update_api_key(key, object, request_options, max_queries_per_IP_per_hour, max_hits_per_query, indexes)
end

.update_user_key(key, object, request_options = {}, max_queries_per_IP_per_hour = 0, max_hits_per_query = 0, indexes = nil) ⇒ Object

Deprecated



1066
1067
1068
 
# File 'lib/algolia/client.rb', line 1066

def Algolia.update_user_key(key, object, request_options = {}, max_queries_per_IP_per_hour = 0, max_hits_per_query = 0, indexes = nil)
  Algolia.client.update_api_key(key, object, request_options, max_queries_per_IP_per_hour, max_hits_per_query, indexes)
end

.wait_task(index_name, taskID, time_before_retry = WAIT_TASK_DEFAULT_TIME_BEFORE_RETRY, request_options = {}) ⇒ Object

Wait until task is completed by the engine



1108
1109
1110
 
# File 'lib/algolia/client.rb', line 1108

def Algolia.wait_task(index_name, taskID, time_before_retry = WAIT_TASK_DEFAULT_TIME_BEFORE_RETRY, request_options = {})
  Algolia.client.wait_task(index_name, taskID, time_before_retry, request_options)
end

.with_rate_limits(end_user_ip, rate_limit_api_key, &block) ⇒ Object

Convenience method thats wraps enable_rate_limit_forward/disable_rate_limit_forward



748
749
750
 
# File 'lib/algolia/client.rb', line 748

def Algolia.with_rate_limits(end_user_ip, rate_limit_api_key, &block)
  Algolia.client.with_rate_limits(end_user_ip, rate_limit_api_key, &block)
end