meilisearch 0.30.0 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5efbe9d158037686df9b8bb37bf42e99646abeaae9bb8134a795507c84887c5d
-  data.tar.gz: 7552001f2cb4030e09588d0601e49ae0d82c5858a31ea491740374251bbf5fd8
+  metadata.gz: 10979c6d34127afb63d73049967287282428a19ae0d0da81e318ebecbdd5061a
+  data.tar.gz: 5ab882422d999ad86bba6b7b4278b511ca63e47292b9a02c2d3ee62adcecb1a0
 SHA512:
-  metadata.gz: ea80d3871ada8d4dcf224893f38ad7a972500df85aabd9100c0772bc9e9aaf3fec9bafa408628357e9d802bfa445307307905b04d4edc656cb8c9808ea307382
-  data.tar.gz: 742c90c3cbc9d931bf30b7d2d533e1dc577404b55ae4a7f2646a88e2b5a2388eda1f70db742ac3acf44721f22a137c1f1c93adab4fb7287475350850c9fe1e9f
+  metadata.gz: d9dfc97758734f2501107df819bb4a2a260af515acce221726a042dc193f3cd1abc3a7d7eaed0cdd218c549aad6b63fc6d661940fc7395fa6180a5d5293844c0
+  data.tar.gz: 370ceb4c95bfa7bc3df49a780edc030d22469898cc325eba7a00db6d2275a39c1af98e49cf77ea4779d9823768d7b79b851449930e9c73d8d526cec8948a1a3e

data/lib/meilisearch/client.rb

@@ -1,18 +1,51 @@
 # frozen_string_literal: true
 
 module Meilisearch
+  # Manages a connection to a Meilisearch server.
+  #   client = Meilisearch::Client.new(MEILISEARCH_URL, MASTER_KEY, options)
+  #
+  # @see #indexes Managing search indexes
+  # @see #keys Managing API keys
+  # @see #stats View usage statistics
+  # @see #tasks Managing ongoing tasks
+  # @see #health Health checking
+  # @see #create_dump
+  # @see #create_snapshot
   class Client < HTTPRequest
     include Meilisearch::TenantToken
     include Meilisearch::MultiSearch
 
     ### INDEXES
 
+    # Fetch indexes in instance, returning the raw server response.
+    #
+    # Unless you have a good reason to, {#indexes} should be used instead.
+    #
+    # @see #indexes
+    # @see https://www.meilisearch.com/docs/reference/api/indexes#list-all-indexes Meilisearch API reference
+    # @param options [Hash{Symbol => Object}] limit and offset options
+    # @return [Hash{String => Object}]
+    #   {index response object}[https://www.meilisearch.com/docs/reference/api/indexes#response]
     def raw_indexes(options = {})
       body = Utils.transform_attributes(options.transform_keys(&:to_sym).slice(:limit, :offset))
 
       http_get('/indexes', body)
     end
 
+    # Swap two indexes.
+    #
+    # Can be used as a convenient way to rebuild an index while keeping it operational.
+    #   client.index('a_swap').add_documents({})
+    #   client.swap_indexes(['a', 'a_swap'])
+    #
+    # Multiple swaps may be done with one request:
+    #   client.swap_indexes(['a', 'a_swap'], ['b', 'b_swap'])
+    #
+    # @see https://www.meilisearch.com/docs/reference/api/indexes#swap-indexes Meilisearch API reference
+    #
+    # @param options [Array<Array(String, String)>] the indexes to swap
+    # @return [Models::Task] the async task that swaps the indexes
+    # @raise [ApiError]
     def swap_indexes(*options)
       mapped_array = options.map { |arr| { indexes: arr } }
 
@@ -20,6 +53,13 @@ module Meilisearch
       Models::Task.new(response, task_endpoint)
     end
 
+    # Fetch indexes in instance.
+    #
+    # @see https://www.meilisearch.com/docs/reference/api/indexes#list-all-indexes Meilisearch API reference
+    # @param options [Hash{Symbol => Object}] limit and offset options
+    # @return [Hash{String => Object}]
+    #   {index response object}[https://www.meilisearch.com/docs/reference/api/indexes#response]
+    #   with results mapped to instances of {Index}
     def indexes(options = {})
       response = raw_indexes(options)
 
@@ -30,9 +70,23 @@ module Meilisearch
       response
     end
 
-    # Usage:
-    # client.create_index('indexUID')
-    # client.create_index('indexUID', primary_key: 'id')
+    # Create a new empty index.
+    #
+    #   client.create_index('indexUID')
+    #   client.create_index('indexUID', primary_key: 'id')
+    #
+    # Indexes are also created when accessed:
+    #
+    #   client.index('new_index').add_documents({})
+    #
+    # @see #index
+    # @see https://www.meilisearch.com/docs/reference/api/indexes#create-an-index Meilisearch API reference
+    #
+    # @param index_uid [String] the uid of the new index
+    # @param options [Hash{Symbol => Object}, nil] snake_cased options of {the endpoint}[https://www.meilisearch.com/docs/reference/api/indexes#create-an-index]
+    #
+    # @raise [ApiError]
+    # @return [Models::Task] the async task that creates the index
     def create_index(index_uid, options = {})
       body = Utils.transform_attributes(options.merge(uid: index_uid))
 
@@ -41,8 +95,14 @@ module Meilisearch
       Models::Task.new(response, task_endpoint)
     end
 
-    # Synchronous version of create_index.
-    # Waits for the task to be achieved, be careful when using it.
+    # Synchronous version of {#create_index}.
+    #
+    # @deprecated
+    #   use {Models::Task#await} on task returned from {#create_index}
+    #
+    #     client.create_index('foo').await
+    #
+    # Waits for the task to be achieved with a busy loop, be careful when using it.
     def create_index!(index_uid, options = {})
       Utils.soft_deprecate(
         'Client#create_index!',
@@ -52,42 +112,131 @@ module Meilisearch
       create_index(index_uid, options).await
     end
 
+    # Delete an index.
+    #
+    # @param index_uid [String] the uid of the index to be deleted
+    # @return [Models::Task] the async task deleting the index
     def delete_index(index_uid)
       index_object(index_uid).delete
     end
 
-    # Usage:
-    # client.index('indexUID')
+    # Get index with given uid.
+    #
+    # Indexes that don't exist are lazily created by Meilisearch.
+    #   index = client.index('index_uid')
+    #   index.add_documents({}) # index is created here if it did not exist
+    #
+    # @see Index
+    # @param index_uid [String] the uid of the index to get
+    # @return [Index]
     def index(index_uid)
       index_object(index_uid)
     end
 
+    # Shorthand for
+    #  client.index(index_uid).fetch_info
+    #
+    # @see Index#fetch_info
+    # @param index_uid [String] uid of the index
     def fetch_index(index_uid)
       index_object(index_uid).fetch_info
     end
 
+    # Shorthand for
+    #  client.index(index_uid).fetch_raw_info
+    #
+    # @see Index#fetch_raw_info
+    # @param index_uid [String] uid of the index
     def fetch_raw_index(index_uid)
       index_object(index_uid).fetch_raw_info
     end
 
     ### KEYS
 
+    # Get all API keys
+    #
+    # This and other key methods require that the Meilisearch instance have a
+    # {master key}[https://www.meilisearch.com/docs/learn/security/differences_master_api_keys#master-key]
+    # set.
+    #
+    # @see #create_key #create_key to create keys and set their scope
+    # @see #key #key to fetch one key
+    # @see https://www.meilisearch.com/docs/reference/api/keys#get-all-keys Meilisearch API reference
+    # @param limit [String, Integer, nil] limit the number of returned keys
+    # @param offset [String, Integer, nil] skip the first +offset+ keys,
+    #   useful for paging.
+    #
+    # @return [Hash{String => Object}] a {keys response}[https://www.meilisearch.com/docs/reference/api/keys#response]
     def keys(limit: nil, offset: nil)
       body = { limit: limit, offset: offset }.compact
 
       http_get '/keys', body
     end
 
+    # Get a specific API key.
+    #
+    #   # obviously this example uid will not correspond to a key on your server
+    #   # please replace it with your own key's uid
+    #   uid = '6062abda-a5aa-4414-ac91-ecd7944c0f8d'
+    #   client.key(uid)
+    #
+    # This and other key methods require that the Meilisearch instance have a
+    # {master key}[https://www.meilisearch.com/docs/learn/security/differences_master_api_keys#master-key]
+    # set.
+    #
+    # @see #keys #keys to get all keys in the instance
+    # @see #create_key #create_key to create keys and set their scope
+    # @see https://www.meilisearch.com/docs/reference/api/keys#get-one-key Meilisearch API reference
+    # @param uid_or_key [String] either the uuidv4 that is the key's
+    #   {uid}[https://www.meilisearch.com/docs/reference/api/keys#uid] or
+    #   a hash of the uid and the master key that is the key's
+    #   {key}[https://www.meilisearch.com/docs/reference/api/keys#key] field
+    #
+    # @return [Hash{String => Object}] a {key object}[https://www.meilisearch.com/docs/reference/api/keys#key-object]
     def key(uid_or_key)
       http_get "/keys/#{uid_or_key}"
     end
 
+    # Create a new API key.
+    #
+    #   require 'date_core'
+    #   ten_days_later = (DateTime.now + 10).rfc3339
+    #   client.create_key(actions: ['*'], indexes: ['*'], expires_at: ten_days_later)
+    #
+    # This and other key methods require that the Meilisearch instance have a
+    # {master key}[https://www.meilisearch.com/docs/learn/security/differences_master_api_keys#master-key]
+    # set.
+    #
+    # @see #update_key #update_key to edit an existing key
+    # @see #keys #keys to get all keys in the instance
+    # @see #key #key to fetch one key
+    # @see https://www.meilisearch.com/docs/reference/api/keys#create-a-key Meilisearch API reference
+    # @param key_options [Hash{Symbol => Object}] the key options of which the required are
+    #   - +:actions+ +Array+ of API actions allowed for key, +["*"]+ for all
+    #   - +:indexes+ +Array+ of indexes key can act on, +["*"]+ for all
+    #   - +:expires_at+ expiration datetime in
+    #     {RFC 3339}[https://www.ietf.org/rfc/rfc3339.txt] format, nil if the key never expires
+    #
+    # @return [Hash{String => Object}] a {key object}[https://www.meilisearch.com/docs/reference/api/keys#key-object]
     def create_key(key_options)
       body = Utils.transform_attributes(key_options)
 
       http_post '/keys', body
     end
 
+    # Update an existing API key.
+    #
+    # This and other key methods require that the Meilisearch instance have a
+    # {master key}[https://www.meilisearch.com/docs/learn/security/differences_master_api_keys#master-key]
+    # set.
+    #
+    # @see #create_key #create_key to create a new key
+    # @see #keys #keys to get all keys in the instance
+    # @see #key #key to fetch one key
+    # @see https://www.meilisearch.com/docs/reference/api/keys#update-a-key Meilisearch API reference
+    # @param key_options [Hash{Symbol => Object}] see {#create_key}
+    #
+    # @return [Hash{String => Object}] a {key object}[https://www.meilisearch.com/docs/reference/api/keys#key-object]
     def update_key(uid_or_key, key_options)
       body = Utils.transform_attributes(key_options)
       body = body.slice('description', 'name')
@@ -95,12 +244,34 @@ module Meilisearch
       http_patch "/keys/#{uid_or_key}", body
     end
 
+    # Delete an API key.
+    #
+    #   # obviously this example uid will not correspond to a key on your server
+    #   # please replace it with your own key's uid
+    #   uid = '6062abda-a5aa-4414-ac91-ecd7944c0f8d'
+    #   client.delete_key(uid)
+    #
+    # This and other key methods require that the Meilisearch instance have a
+    # {master key}[https://www.meilisearch.com/docs/learn/security/differences_master_api_keys#master-key]
+    # set.
+    #
+    # @see #keys #keys to get all keys in the instance
+    # @see #create_key #create_key to create keys and set their scope
+    # @see https://www.meilisearch.com/docs/reference/api/keys#delete-a-key Meilisearch API reference
+    # @param uid_or_key [String] either the uuidv4 that is the key's
+    #   {uid}[https://www.meilisearch.com/docs/reference/api/keys#uid] or
+    #   a hash of the uid and the master key that is the key's
+    #   {key}[https://www.meilisearch.com/docs/reference/api/keys#key] field
     def delete_key(uid_or_key)
       http_delete "/keys/#{uid_or_key}"
     end
 
     ### HEALTH
 
+    # Check if Meilisearch instance is healthy.
+    #
+    # @see #health
+    # @return [bool] whether or not the +/health+ endpoint raises any errors
     def healthy?
       http_get '/health'
       true
@@ -108,22 +279,51 @@ module Meilisearch
       false
     end
 
+    # Check health of Meilisearch instance.
+    #
+    # @see https://www.meilisearch.com/docs/reference/api/health#get-health Meilisearch API reference
+    # @return [Hash{String => Object}] the health report from the Meilisearch instance
     def health
       http_get '/health'
     end
 
     ### STATS
 
+    # Check version of Meilisearch server
+    #
+    # @see https://www.meilisearch.com/docs/reference/api/version#get-version-of-meilisearch Meilisearch API reference
+    # @return [Hash{String => String}] package version and last commit of Meilisearch server, see
+    #   {version object}[https://www.meilisearch.com/docs/reference/api/version#version-object]
     def version
       http_get '/version'
     end
 
+    # Get stats of all indexes in instance.
+    #
+    # @see Index#stats
+    # @see https://www.meilisearch.com/docs/reference/api/stats#get-stats-of-all-indexes Meilisearch API reference
+    # @return [Hash{String => Object}] see {stats object}[https://www.meilisearch.com/docs/reference/api/stats#stats-object]
     def stats
       http_get '/stats'
     end
 
     ### DUMPS
 
+    # Create a database dump.
+    #
+    # Dumps are "blueprints" which can be used to restore your database. Restoring
+    # a dump requires reindexing all documents and is therefore inefficient.
+    #
+    # Dumps are created by the Meilisearch server in the directory where the server is started
+    # under +dumps/+ by default.
+    #
+    # @see https://www.meilisearch.com/docs/learn/advanced/snapshots_vs_dumps
+    #   The difference between snapshots and dumps
+    # @see https://www.meilisearch.com/docs/learn/advanced/dumps
+    #   Meilisearch documentation on how to use dumps
+    # @see https://www.meilisearch.com/docs/reference/api/dump#create-a-dump
+    #   Meilisearch API reference
+    # @return [Models::Task] the async task that is creating the dump
     def create_dump
       response = http_post '/dumps'
       Models::Task.new(response, task_endpoint)
@@ -131,42 +331,151 @@ module Meilisearch
 
     ### SNAPSHOTS
 
+    # Create a database snapshot.
+    #
+    # Snapshots are exact copies of the Meilisearch database. As such they are pre-indexed
+    # and restoring one is a very efficient operation.
+    #
+    # Snapshots are not compatible between Meilisearch versions. Snapshot creation takes priority
+    # over other tasks.
+    #
+    # Snapshots are created by the Meilisearch server in the directory where the server is started
+    # under +snapshots/+ by default.
+    #
+    # @see https://www.meilisearch.com/docs/learn/advanced/snapshots_vs_dumps
+    #   The difference between snapshots and dumps
+    # @see https://www.meilisearch.com/docs/learn/advanced/snapshots
+    #   Meilisearch documentation on how to use snapshots
+    # @see https://www.meilisearch.com/docs/reference/api/snapshots#create-a-snapshot
+    #   Meilisearch API reference
+    # @return [Models::Task] the async task that is creating the snapshot
     def create_snapshot
       http_post '/snapshots'
     end
 
     ### TASKS
 
+    # Cancel tasks matching the filter.
+    #
+    # This route is meant to be used with options, please see the API reference.
+    #
+    # Operations in Meilisearch are done asynchronously using "tasks".
+    # Tasks report their progress and status.
+    #
+    # Warning: This does not return instances of {Models::Task}. This is a raw
+    # call to the Meilisearch API and the return is not modified.
+    #
+    # @see https://www.meilisearch.com/docs/reference/api/tasks#task-object The Task Object
+    # @see https://www.meilisearch.com/docs/reference/api/tasks#cancel-tasks Meilisearch API reference
+    # @param options [Hash{Symbol => Object}] task search options as snake cased symbols, see the API reference
+    # @return [Hash{String => Object}] a Meilisearch task that is canceling other tasks
     def cancel_tasks(options = {})
       task_endpoint.cancel_tasks(options)
     end
 
+    # Cancel tasks matching the filter.
+    #
+    # This route is meant to be used with options, please see the API reference.
+    #
+    # Operations in Meilisearch are done asynchronously using "tasks".
+    # Tasks report their progress and status.
+    #
+    # Warning: This does not return instances of {Models::Task}. This is a raw
+    # call to the Meilisearch API and the return is not modified.
+    #
+    # Tasks are run in batches, see {#batches}.
+    #
+    # @see https://www.meilisearch.com/docs/reference/api/tasks#task-object The Task Object
+    # @see https://www.meilisearch.com/docs/reference/api/tasks#cancel-tasks Meilisearch API reference
+    # @param options [Hash{Symbol => Object}] task search options as snake cased symbols, see the API reference
+    # @return [Hash{String => Object}] a Meilisearch task that is canceling other tasks
     def delete_tasks(options = {})
       task_endpoint.delete_tasks(options)
     end
 
+    # Get Meilisearch tasks matching the filters.
+    #
+    # Operations in Meilisearch are done asynchronously using "tasks".
+    # Tasks report their progress and status.
+    #
+    # Warning: This does not return instances of {Models::Task}. This is a raw
+    # call to the Meilisearch API and the return is not modified.
+    #
+    # @see https://www.meilisearch.com/docs/reference/api/tasks#task-object The Task Object
+    # @see https://www.meilisearch.com/docs/reference/api/tasks#get-tasks Meilisearch API reference
+    # @param options [Hash{Symbol => Object}] task search options as snake cased symbols, see the API reference
+    # @return [Hash{String => Object}] results of the task search, see API reference
     def tasks(options = {})
       task_endpoint.task_list(options)
     end
 
+    # Get one task.
+    #
+    # Operations in Meilisearch are done asynchronously using "tasks".
+    # Tasks report their progress and status.
+    #
+    # Warning: This does not return instances of {Models::Task}. This is a raw
+    # call to the Meilisearch API and the return is not modified.
+    #
+    # @see https://www.meilisearch.com/docs/reference/api/tasks#task-object The Task Object
+    # @see https://www.meilisearch.com/docs/reference/api/tasks#get-one-task Meilisearch API reference
+    # @param task_uid [String] uid of the requested task
+    # @return [Hash{String => Object}] a Meilisearch task object (see above)
     def task(task_uid)
       task_endpoint.task(task_uid)
     end
 
-    def wait_for_task(task_uid, timeout_in_ms = 5000, interval_in_ms = 50)
+    # Wait for a task in a busy loop.
+    #
+    # Try to avoid using it. Wrapper around {Task#wait_for_task}.
+    # @see Task#wait_for_task
+    def wait_for_task(
+      task_uid,
+      timeout_in_ms = Models::Task.default_timeout_ms,
+      interval_in_ms = Models::Task.default_interval_ms
+    )
       task_endpoint.wait_for_task(task_uid, timeout_in_ms, interval_in_ms)
     end
 
     ### BATCHES
 
+    # Get Meilisearch task batches matching the filters.
+    #
+    # Operations in Meilisearch are done asynchronously using "tasks".
+    # Tasks are run in batches.
+    #
+    # @see https://www.meilisearch.com/docs/reference/api/batches#batch-object The Batch Object
+    # @see https://www.meilisearch.com/docs/reference/api/batches#get-batches Meilisearch API reference
+    # @param options [Hash{Symbol => Object}] task search options as snake cased symbols, see the API reference
+    # @return [Hash{String => Object}] results of the batches search, see API reference
     def batches(options = {})
       http_get '/batches', options
     end
 
+    # Get a single Meilisearch task batch matching +batch_uid+.
+    #
+    # Operations in Meilisearch are done asynchronously using "tasks".
+    # Tasks are run in batches.
+    #
+    # @see https://www.meilisearch.com/docs/reference/api/batches#batch-object The Batch Object
+    # @see https://www.meilisearch.com/docs/reference/api/batches#get-one-batch Meilisearch API reference
+    # @param batch_uid [String] the uid of the request batch
+    # @return [Hash{String => Object}] a batch object, see above
     def batch(batch_uid)
       http_get "/batches/#{batch_uid}"
     end
 
+    ### EXPERIMENTAL FEATURES
+
+    def experimental_features
+      http_get '/experimental-features'
+    end
+
+    def update_experimental_features(expe_feat_changes)
+      expe_feat_changes = Utils.transform_attributes(expe_feat_changes)
+      http_patch '/experimental-features', expe_feat_changes
+    end
+
     private
 
     def index_object(uid, primary_key = nil)

data/lib/meilisearch/http_request.rb

@@ -10,8 +10,9 @@ module Meilisearch
     attr_reader :options, :headers
 
     DEFAULT_OPTIONS = {
-      timeout: 1,
-      max_retries: 0,
+      timeout: 10,
+      max_retries: 2,
+      retry_multiplier: 1.2,
       convert_body?: true
     }.freeze
 
@@ -22,14 +23,15 @@ module Meilisearch
       @headers = build_default_options_headers
     end
 
-    def http_get(relative_path = '', query_params = {})
+    def http_get(relative_path = '', query_params = {}, options = {})
       send_request(
         proc { |path, config| self.class.get(path, config) },
         relative_path,
         config: {
           query_params: query_params,
-          headers: remove_headers(@headers.dup, 'Content-Type'),
-          options: @options
+          headers: remove_headers(@headers.dup.merge(options[:headers] || {}), 'Content-Type'),
+          options: @options.merge(options),
+          method_type: :get
         }
       )
     end
@@ -42,45 +44,49 @@ module Meilisearch
           query_params: query_params,
           body: body,
           headers: @headers.dup.merge(options[:headers] || {}),
-          options: @options.merge(options)
+          options: @options.merge(options),
+          method_type: :post
         }
       )
     end
 
-    def http_put(relative_path = '', body = nil, query_params = nil)
+    def http_put(relative_path = '', body = nil, query_params = nil, options = {})
       send_request(
         proc { |path, config| self.class.put(path, config) },
         relative_path,
         config: {
           query_params: query_params,
           body: body,
-          headers: @headers,
-          options: @options
+          headers: @headers.dup.merge(options[:headers] || {}),
+          options: @options.merge(options),
+          method_type: :put
         }
       )
     end
 
-    def http_patch(relative_path = '', body = nil, query_params = nil)
+    def http_patch(relative_path = '', body = nil, query_params = nil, options = {})
       send_request(
         proc { |path, config| self.class.patch(path, config) },
         relative_path,
         config: {
           query_params: query_params,
           body: body,
-          headers: @headers,
-          options: @options
+          headers: @headers.dup.merge(options[:headers] || {}),
+          options: @options.merge(options),
+          method_type: :patch
         }
       )
     end
 
-    def http_delete(relative_path = '', query_params = nil)
+    def http_delete(relative_path = '', query_params = nil, options = {})
       send_request(
         proc { |path, config| self.class.delete(path, config) },
         relative_path,
         config: {
           query_params: query_params,
-          headers: remove_headers(@headers.dup, 'Content-Type'),
-          options: @options
+          headers: remove_headers(@headers.dup.merge(options[:headers] || {}), 'Content-Type'),
+          options: @options.merge(options),
+          method_type: :delete
         }
       )
     end
@@ -102,15 +108,23 @@ module Meilisearch
       data.delete_if { |k| keys.include?(k) }
     end
 
-    def send_request(http_method, relative_path, config: {})
-      config = http_config(config[:query_params], config[:body], config[:options], config[:headers])
+    def send_request(http_method, relative_path, config:)
+      attempts = 0
+      retry_multiplier = config.dig(:options, :retry_multiplier)
+      max_retries = config.dig(:options, :max_retries)
+      request_config = http_config(config[:query_params], config[:body], config[:options], config[:headers])
 
       begin
-        response = http_method.call(@base_url + relative_path, config)
+        response = http_method.call(@base_url + relative_path, request_config)
       rescue Errno::ECONNREFUSED, Errno::EPIPE => e
         raise CommunicationError, e.message
-      rescue Net::ReadTimeout, Net::OpenTimeout => e
-        raise TimeoutError, e.message
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        attempts += 1
+        raise TimeoutError, e.message unless attempts <= max_retries && safe_to_retry?(config[:method_type], e)
+
+        sleep(retry_multiplier**attempts)
+
+        retry
       end
 
       validate(response)
@@ -132,5 +146,10 @@ module Meilisearch
 
       response.parsed_response
     end
+
+    # Ensures the only retryable error is a timeout didn't reached the server
+    def safe_to_retry?(method_type, error)
+      method_type == :get || ([:post, :put, :patch, :delete].include?(method_type) && error.is_a?(Net::OpenTimeout))
+    end
   end
 end

data/lib/meilisearch/index.rb

@@ -145,6 +145,48 @@ module Meilisearch
     end
     alias add_or_update_documents update_documents
 
+    def update_documents_json(documents, primary_key = nil)
+      options = { convert_body?: false }
+      response = http_put "/indexes/#{@uid}/documents", documents, { primaryKey: primary_key }.compact, options
+
+      Models::Task.new(response, task_endpoint)
+    end
+    alias add_or_update_documents_json update_documents_json
+
+    def update_documents_ndjson(documents, primary_key = nil)
+      options = { headers: { 'Content-Type' => 'application/x-ndjson' }, convert_body?: false }
+      response = http_put "/indexes/#{@uid}/documents", documents, { primaryKey: primary_key }.compact, options
+
+      Models::Task.new(response, task_endpoint)
+    end
+    alias add_or_update_documents_ndjson update_documents_ndjson
+
+    def update_documents_csv(documents, primary_key = nil, delimiter = nil)
+      options = { headers: { 'Content-Type' => 'text/csv' }, convert_body?: false }
+
+      response = http_put "/indexes/#{@uid}/documents", documents, {
+        primaryKey: primary_key,
+        csvDelimiter: delimiter
+      }.compact, options
+
+      Models::Task.new(response, task_endpoint)
+    end
+    alias add_or_update_documents_csv add_documents_csv
+
+    def update_documents_ndjson_in_batches(documents, batch_size = 1000, primary_key = nil)
+      documents.lines.each_slice(batch_size).map do |batch|
+        update_documents_ndjson(batch.join, primary_key)
+      end
+    end
+
+    def update_documents_csv_in_batches(documents, batch_size = 1000, primary_key = nil, delimiter = nil)
+      lines = documents.lines
+      heading = lines.first
+      lines.drop(1).each_slice(batch_size).map do |batch|
+        update_documents_csv(heading + batch.join, primary_key, delimiter)
+      end
+    end
+
     def update_documents!(documents, primary_key = nil)
       Utils.soft_deprecate(
         'Index#update_documents!',
@@ -161,6 +203,20 @@ module Meilisearch
       end
     end
 
+    def add_documents_ndjson_in_batches(documents, batch_size = 1000, primary_key = nil)
+      documents.lines.each_slice(batch_size).map do |batch|
+        add_documents_ndjson(batch.join, primary_key)
+      end
+    end
+
+    def add_documents_csv_in_batches(documents, batch_size = 1000, primary_key = nil, delimiter = nil)
+      lines = documents.lines
+      heading = lines.first
+      lines.drop(1).each_slice(batch_size).map do |batch|
+        add_documents_csv(heading + batch.join, primary_key, delimiter)
+      end
+    end
+
     def add_documents_in_batches!(documents, batch_size = 1000, primary_key = nil)
       Utils.soft_deprecate(
         'Index#add_documents_in_batches!',
@@ -609,11 +665,15 @@ module Meilisearch
     end
 
     def update_proximity_precision(proximity_precision_attribute)
-      http_put("/indexes/#{@uid}/settings/proximity-precision", proximity_precision_attribute)
+      response = http_put("/indexes/#{@uid}/settings/proximity-precision", proximity_precision_attribute)
+
+      Models::Task.new(response, task_endpoint)
     end
 
     def reset_proximity_precision
-      http_delete("/indexes/#{@uid}/settings/proximity-precision")
+      response = http_delete("/indexes/#{@uid}/settings/proximity-precision")
+
+      Models::Task.new(response, task_endpoint)
     end
 
     ### SETTINGS - SEARCH CUTOFF MS
@@ -623,11 +683,15 @@ module Meilisearch
     end
 
     def update_search_cutoff_ms(search_cutoff_ms_attribute)
-      http_put("/indexes/#{@uid}/settings/search-cutoff-ms", search_cutoff_ms_attribute)
+      response = http_put("/indexes/#{@uid}/settings/search-cutoff-ms", search_cutoff_ms_attribute)
+
+      Models::Task.new(response, task_endpoint)
     end
 
     def reset_search_cutoff_ms
-      http_delete("/indexes/#{@uid}/settings/search-cutoff-ms")
+      response = http_delete("/indexes/#{@uid}/settings/search-cutoff-ms")
+
+      Models::Task.new(response, task_endpoint)
     end
 
     ### SETTINGS - LOCALIZED ATTRIBUTES
@@ -639,11 +703,15 @@ module Meilisearch
     def update_localized_attributes(new_localized_attributes)
       new_localized_attributes = Utils.transform_attributes(new_localized_attributes)
 
-      http_put("/indexes/#{@uid}/settings/localized-attributes", new_localized_attributes)
+      response = http_put("/indexes/#{@uid}/settings/localized-attributes", new_localized_attributes)
+
+      Models::Task.new(response, task_endpoint)
     end
 
     def reset_localized_attributes
-      http_delete("/indexes/#{@uid}/settings/localized-attributes")
+      response = http_delete("/indexes/#{@uid}/settings/localized-attributes")
+
+      Models::Task.new(response, task_endpoint)
     end
 
     ### SETTINGS - FACET SEARCH
@@ -653,11 +721,15 @@ module Meilisearch
     end
 
     def update_facet_search_setting(new_facet_search_setting)
-      http_put("/indexes/#{@uid}/settings/facet-search", new_facet_search_setting)
+      response = http_put("/indexes/#{@uid}/settings/facet-search", new_facet_search_setting)
+
+      Models::Task.new(response, task_endpoint)
     end
 
     def reset_facet_search_setting
-      http_delete("/indexes/#{@uid}/settings/facet-search")
+      response = http_delete("/indexes/#{@uid}/settings/facet-search")
+
+      Models::Task.new(response, task_endpoint)
     end
 
     ### SETTINGS - PREFIX SEARCH
@@ -667,11 +739,15 @@ module Meilisearch
     end
 
     def update_prefix_search(new_prefix_search_setting)
-      http_put("/indexes/#{@uid}/settings/prefix-search", new_prefix_search_setting)
+      response = http_put("/indexes/#{@uid}/settings/prefix-search", new_prefix_search_setting)
+
+      Models::Task.new(response, task_endpoint)
     end
 
     def reset_prefix_search
-      http_delete("/indexes/#{@uid}/settings/prefix-search")
+      response = http_delete("/indexes/#{@uid}/settings/prefix-search")
+
+      Models::Task.new(response, task_endpoint)
     end
 
     ### SETTINGS - EMBEDDERS
@@ -683,11 +759,15 @@ module Meilisearch
     def update_embedders(new_embedders)
       new_embedders = Utils.transform_attributes(new_embedders)
 
-      http_patch("/indexes/#{@uid}/settings/embedders", new_embedders)
+      response = http_patch("/indexes/#{@uid}/settings/embedders", new_embedders)
+
+      Models::Task.new(response, task_endpoint)
     end
 
     def reset_embedders
-      http_delete("/indexes/#{@uid}/settings/embedders")
+      response = http_delete("/indexes/#{@uid}/settings/embedders")
+
+      Models::Task.new(response, task_endpoint)
     end
   end
 end

data/lib/meilisearch/models/task.rb

@@ -5,6 +5,21 @@ require 'forwardable'
 module Meilisearch
   module Models
     class Task
+      DEFAULT_TIMEOUT_MS = 5000
+      DEFAULT_INTERVAL_MS = 50
+
+      class << self
+        attr_writer :default_timeout_ms, :default_interval_ms
+
+        def default_timeout_ms
+          @default_timeout_ms || DEFAULT_TIMEOUT_MS
+        end
+
+        def default_interval_ms
+          @default_interval_ms || DEFAULT_INTERVAL_MS
+        end
+      end
+
       extend Forwardable
 
       # Maintain backwards compatibility with task hash return type
@@ -96,7 +111,10 @@ module Meilisearch
         self
       end
 
-      def await(timeout_in_ms = 5000, interval_in_ms = 50)
+      def await(
+        timeout_in_ms = self.class.default_timeout_ms,
+        interval_in_ms = self.class.default_interval_ms
+      )
         refresh with: @task_endpoint.wait_for_task(uid, timeout_in_ms, interval_in_ms) unless finished?
 
         self

data/lib/meilisearch/multi_search.rb

@@ -2,10 +2,20 @@
 
 module Meilisearch
   module MultiSearch
-    def multi_search(data)
-      body = Utils.transform_attributes(data)
+    # Performs search on one or more indexes
+    #
+    # @param [Hash] federation_options
+    #   - `limit`: number of results in the merged list
+    #   - `offset`: number of results to skip in the merged list
+    def multi_search(data = nil, queries: [], federation: nil)
+      Utils.soft_deprecate('multi_search([])', 'multi_search(queries: [])') if data
 
-      http_post '/multi-search', queries: body
+      queries += data if data
+
+      queries = Utils.transform_attributes(queries)
+      federation = Utils.transform_attributes(federation)
+
+      http_post '/multi-search', queries: queries, federation: federation
     end
   end
 end

data/lib/meilisearch/task.rb

@@ -36,7 +36,19 @@ module Meilisearch
       http_delete '/tasks', Utils.parse_query(options, ALLOWED_CANCELATION_PARAMS)
     end
 
-    def wait_for_task(task_uid, timeout_in_ms = 5000, interval_in_ms = 50)
+    # Wait for a task with a busy loop.
+    #
+    # Not recommended, try to avoid interacting with Meilisearch synchronously.
+    # @param task_uid [String] uid of the task to wait on
+    # @param timeout_in_ms [Integer] the maximum amount of time to wait for a task
+    #   in milliseconds
+    # @param interval_in_ms [Integer] how long to stay parked in the busy loop
+    #   in milliseconds
+    def wait_for_task(
+      task_uid,
+      timeout_in_ms = Models::Task.default_timeout_ms,
+      interval_in_ms = Models::Task.default_interval_ms
+    )
       Timeout.timeout(timeout_in_ms.to_f / 1000) do
         loop do
           task = task(task_uid)

data/lib/meilisearch/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Meilisearch
-  VERSION = '0.30.0'
+  VERSION = '0.32.0'
 
   def self.qualified_version
     "Meilisearch Ruby (v#{VERSION})"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: meilisearch
 version: !ruby/object:Gem::Version
-  version: 0.30.0
+  version: 0.32.0
 platform: ruby
 authors:
 - Meili
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-01-10 00:00:00.000000000 Z
+date: 2025-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.17'
+        version: '0.22'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.17'
+        version: '0.22'
 description: An easy-to-use ruby client for Meilisearch API. See https://github.com/meilisearch/meilisearch
 email: bonjour@meilisearch.com
 executables: []