meilisearch 0.23.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a02358b002d9f3a7b6f256140a01a8e3a55e90bab3b6a43889e8a23010bb0b4a
-  data.tar.gz: e2f28298a8041755692c333bb778b5996226bc7889ab2d58dab9d9cae7a350e7
+  metadata.gz: e182244659129f40ceff661d8e117af391a68aa1cf5fed79f198fc715863ba4e
+  data.tar.gz: 17f9fd0b3b529829f1bd3d4d39cb3444532ec2cc14b0aebaeac00bae6f217d9b
 SHA512:
-  metadata.gz: 0f4d24797d09a8176788fad8708d7dd9ac962b24d53db21a16d68ea16568935f9dc72e2c0160b50e516a45b7c2547e7afc8f0e4fc3534659daf3ec22f5b68d37
-  data.tar.gz: 93f401846f98f6b388eb251fe804d862ed64d45ea346944364284da47f8c4d511a082746afde481ba6f7d8742a4d95693dd7e086c219cc9ba64e6a55fb15bd66
+  metadata.gz: 6aefe0097ef3f3c1785f1498ade5508ac77fca3e5aef025931d7ec34e12462419721cd2b7a1ee9d8c5037a36fa0dedd3aeabb35b473a400e05b9880401495149
+  data.tar.gz: 5b9949303254ca87e378904dadbbf0f7fc77a113cbda175dfb7bb950b674ed09742d411c0fb45cbc3a5626c6c16ebd1549e402b76504016b1e9567e28ba4e084

data/README.md

@@ -6,16 +6,20 @@
 
 <h4 align="center">
   <a href="https://github.com/meilisearch/meilisearch">Meilisearch</a> |
+  <a href="https://www.meilisearch.com/cloud?utm_campaign=oss&utm_source=github&utm_medium=meilisearch-ruby">Meilisearch Cloud</a> |
   <a href="https://docs.meilisearch.com">Documentation</a> |
   <a href="https://discord.meilisearch.com">Discord</a> |
   <a href="https://roadmap.meilisearch.com/tabs/1-under-consideration">Roadmap</a> |
   <a href="https://www.meilisearch.com">Website</a> |
-  <a href="https://docs.meilisearch.com/faq">FAQ</a>
+  <a href="https://www.meilisearch.com/docs/faq">FAQ</a>
 </h4>
 
 <p align="center">
   <a href="https://badge.fury.io/rb/meilisearch"><img src="https://badge.fury.io/rb/meilisearch.svg" alt="Latest Stable Version"></a>
   <a href="https://github.com/meilisearch/meilisearch-ruby/actions"><img src="https://github.com/meilisearch/meilisearch-ruby/workflows/Tests/badge.svg" alt="Test"></a>
+  <a href="https://app.codecov.io/gh/meilisearch/meilisearch-ruby/tree/main" >
+    <img src="https://codecov.io/gh/meilisearch/meilisearch-ruby/branch/main/graph/badge.svg?token=9J7LRP11IR"/>
+  </a>
   <a href="https://github.com/meilisearch/meilisearch-ruby/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-informational" alt="License"></a>
   <a href="https://ms-bors.herokuapp.com/repositories/6"><img src="https://bors.tech/images/badge_small.svg" alt="Bors enabled"></a>
 </p>
@@ -26,9 +30,10 @@
 
 **Meilisearch** is an open-source search engine. [Learn more about Meilisearch.](https://github.com/meilisearch/meilisearch)
 
-## Table of Contents <!-- omit in toc -->
+## Table of Contents <!-- omit in TOC -->
 
 - [📖 Documentation](#-documentation)
+- [⚡ Supercharge your Meilisearch experience](#-supercharge-your-meilisearch-experience)
 - [🔧 Installation](#-installation)
 - [🚀 Getting started](#-getting-started)
 - [🤖 Compatibility with Meilisearch](#-compatibility-with-meilisearch)
@@ -39,9 +44,13 @@
 
 This readme contains all the documentation you need to start using this Meilisearch SDK.
 
-For general information on how to use Meilisearch—such as our API reference, tutorials, guides, and in-depth articles—refer to our [main documentation website](https://docs.meilisearch.com/).
+For general information on how to use Meilisearch—such as our API reference, tutorials, guides, and in-depth articles—refer to our [main documentation website](https://www.meilisearch.com/docs/).
 
 
+## ⚡ Supercharge your Meilisearch experience
+
+Say goodbye to server deployment and manual updates with [Meilisearch Cloud](https://www.meilisearch.com/cloud?utm_campaign=oss&utm_source=github&utm_medium=meilisearch-ruby). Get started with a 14-day free trial! No credit card required.
+
 ## 🔧 Installation
 
 This package requires Ruby version 2.6.0 or later.
@@ -60,12 +69,12 @@ gem 'meilisearch'
 
 ### Run Meilisearch <!-- omit in toc -->
 
-There are many easy ways to [download and run a Meilisearch instance](https://docs.meilisearch.com/reference/features/installation.html#download-and-launch).
+There are many easy ways to [download and run a Meilisearch instance](https://www.meilisearch.com/docs/learn/getting_started/quick_start#setup-and-installation).
 
-For example, using the `curl` command in your [Terminal](https://itconnect.uw.edu/learn/workshops/online-tutorials/web-publishing/what-is-a-terminal/):
+For example, using the `curl` command in your [Terminal](https://itconnect.uw.edu/learn/workshops/online-tutorials/what-is-a-terminal/):
 
 ```sh
-#Install Meilisearch
+# Install Meilisearch
 curl -L https://install.meilisearch.com | sh
 
 # Launch Meilisearch
@@ -98,7 +107,7 @@ documents = [
 index.add_documents(documents) # => { "uid": 0 }
 ```
 
-With the `uid`, you can check the status (`enqueued`, `processing`, `succeeded` or `failed`) of your documents addition using the [task](https://docs.meilisearch.com/reference/api/tasks.html#get-task).
+With the `uid`, you can check the status (`enqueued`, `canceled`, `processing`, `succeeded` or `failed`) of your documents addition using the [task](https://www.meilisearch.com/docs/reference/api/tasks#get-tasks).
 
 💡 To customize the `Client`, for example, increasing the default timeout, please check out [this section](https://github.com/meilisearch/meilisearch-ruby/wiki/Client-Options) of the Wiki.
 
@@ -125,7 +134,7 @@ Output:
 
 #### Custom search <!-- omit in toc -->
 
-All the supported options are described in the [search parameters](https://docs.meilisearch.com/reference/features/search_parameters.html) section of the documentation.
+All the supported options are described in the [search parameters](https://www.meilisearch.com/docs/reference/api/search#search-parameters) section of the documentation.
 
 ```ruby
 index.search(
@@ -168,7 +177,7 @@ index.update_filterable_attributes([
 
 You only need to perform this operation once.
 
-Note that Meilisearch will rebuild your index whenever you update `filterableAttributes`. Depending on the size of your dataset, this might take time. You can track the process using the [tasks](https://docs.meilisearch.com/reference/api/tasks.html#get-task)).
+Note that Meilisearch will rebuild your index whenever you update `filterableAttributes`. Depending on the size of your dataset, this might take time. You can track the process using the [tasks](https://www.meilisearch.com/docs/reference/api/tasks#get-tasks)).
 
 Then, you can perform the search:
 
@@ -198,6 +207,82 @@ JSON output:
 }
 ```
 
+#### Display ranking details at search
+
+JSON output:
+
+```json
+{
+  "hits": [
+    {
+      "id": 15359,
+      "title": "Wonder Woman",
+      "_rankingScoreDetails": {
+        "words": {
+          "order": 0,
+          "matchingWords": 2,
+          "maxMatchingWords": 2,
+          "score": 1.0
+        },
+        "typo": {
+          "order": 1,
+          "typoCount": 0,
+          "maxTypoCount": 2,
+          "score": 1.0
+        },
+        "proximity": {
+          "order": 2,
+          "score": 1.0
+        },
+        "attribute": {
+          "order": 3,
+          "attributeRankingOrderScore": 0.8181818181818182,
+          "queryWordDistanceScore": 1.0,
+          "score": 0.8181818181818182
+        },
+        "exactness": {
+          "order": 4,
+          "matchType": "exactMatch",
+          "score": 1.0
+        }
+      }
+    }
+  ]
+}
+```
+
+You can enable it by querying PATCH /experimental-features with { "scoreDetails": true }
+
+This feature is only available with Meilisearch v1.3 and newer (optional).
+
+#### Custom Search With attributes on at search time  <!-- omit in toc -->
+
+[Customize attributes to search on at search time](https://www.meilisearch.com/docs/reference/api/search#customize-attributes-to-search-on-at-search-time).
+
+you can perform the search :
+
+```ruby
+index.search('wonder', { attributes_to_search_on: ['genres'] })
+```
+
+
+JSON output:
+
+```json
+{
+  "hits":[],
+  "query":"wonder",
+  "processingTimeMs":0,
+  "limit":20,
+  "offset":0,
+  "estimatedTotalHits":0,
+  "nbHits":0
+}
+```
+
+This feature is only available with Meilisearch v1.3 and newer (optional).
+
+
 ## 🤖 Compatibility with Meilisearch
 
 This package guarantees compatibility with [version v1.x of Meilisearch](https://github.com/meilisearch/meilisearch/releases/latest), but some features may not be present. Please check the [issues](https://github.com/meilisearch/meilisearch-ruby/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+label%3Aenhancement) for more info.
@@ -206,12 +291,12 @@ This package guarantees compatibility with [version v1.x of Meilisearch](https:/
 
 The following sections in our main documentation website may interest you:
 
-- **Manipulate documents**: see the [API references](https://docs.meilisearch.com/reference/api/documents.html) or read more about [documents](https://docs.meilisearch.com/learn/core_concepts/documents.html).
-- **Search**: see the [API references](https://docs.meilisearch.com/reference/api/search.html) or follow our guide on [search parameters](https://docs.meilisearch.com/reference/features/search_parameters.html).
-- **Manage the indexes**: see the [API references](https://docs.meilisearch.com/reference/api/indexes.html) or read more about [indexes](https://docs.meilisearch.com/learn/core_concepts/indexes.html).
-- **Configure the index settings**: see the [API references](https://docs.meilisearch.com/reference/api/settings.html) or follow our guide on [settings parameters](https://docs.meilisearch.com/reference/features/settings.html).
+- **Manipulate documents**: see the [API references](https://www.meilisearch.com/docs/reference/api/documents) or read more about [documents](https://www.meilisearch.com/docs/learn/core_concepts/documents).
+- **Search**: see the [API references](https://www.meilisearch.com/docs/reference/api/search) or follow our guide on [search parameters](https://www.meilisearch.com/docs/reference/api/search#search-parameters).
+- **Manage the indexes**: see the [API references](https://www.meilisearch.com/docs/reference/api/indexes) or read more about [indexes](https://www.meilisearch.com/docs/learn/core_concepts/indexes).
+- **Configure the index settings**: see the [API references](https://www.meilisearch.com/docs/reference/api/settings) or follow our guide on [settings parameters](https://www.meilisearch.com/docs/reference/api/settings).
 
-📖 Also, check out the [Wiki](https://github.com/meilisearch/meilisearch-ruby/wiki) of this repository to know what this SDK provdes!
+📖 Also, check out the [Wiki](https://github.com/meilisearch/meilisearch-ruby/wiki) of this repository to know what this SDK provides!
 
 ## ⚙️ Contributing
 

data/lib/meilisearch/client.rb

@@ -31,7 +31,7 @@ module MeiliSearch
 
     # Usage:
     # client.create_index('indexUID')
-    # client.create_index('indexUID', primaryKey: 'id')
+    # client.create_index('indexUID', primary_key: 'id')
     def create_index(index_uid, options = {})
       body = Utils.transform_attributes(options.merge(uid: index_uid))
 

data/lib/meilisearch/error.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 module MeiliSearch
-  class ApiError < StandardError
+  class Error < StandardError
+  end
+
+  class ApiError < Error
     # :http_code    # e.g. 400, 404...
     # :http_message # e.g. Bad Request, Not Found...
     # :http_body    # The response body received from the MeiliSearch API
@@ -45,7 +48,7 @@ module MeiliSearch
     end
   end
 
-  class CommunicationError < StandardError
+  class CommunicationError < Error
     attr_reader :message
 
     def initialize(message)
@@ -54,7 +57,7 @@ module MeiliSearch
     end
   end
 
-  class TimeoutError < StandardError
+  class TimeoutError < Error
     attr_reader :message
 
     def initialize(message = nil)
@@ -64,8 +67,8 @@ module MeiliSearch
   end
 
   module TenantToken
-    class ExpireOrInvalidSignature < StandardError; end
-    class InvalidApiKey < StandardError; end
-    class InvalidSearchRules < StandardError; end
+    class ExpireOrInvalidSignature < MeiliSearch::Error; end
+    class InvalidApiKey < MeiliSearch::Error; end
+    class InvalidSearchRules < MeiliSearch::Error; end
   end
 end

data/lib/meilisearch/index.rb

@@ -63,8 +63,24 @@ module MeiliSearch
     alias get_document document
     alias get_one_document document
 
+    # Public: Retrieve documents from a index.
+    #
+    # options - The hash options used to refine the selection (default: {}):
+    #           :limit  - Number of documents to return (optional).
+    #           :offset - Number of documents to skip (optional).
+    #           :fields - Array of document attributes to show (optional).
+    #           :filter - Filter queries by an attribute's value.
+    #                     Available ONLY with Meilisearch v1.2 and newer (optional).
+    #
+    # Returns the documents results object.
     def documents(options = {})
-      http_get "/indexes/#{@uid}/documents", Utils.parse_query(options, [:limit, :offset, :fields])
+      Utils.version_error_handler(__method__) do
+        if options.key?(:filter)
+          http_post "/indexes/#{@uid}/documents/fetch", Utils.filter(options, [:limit, :offset, :fields, :filter])
+        else
+          http_get "/indexes/#{@uid}/documents", Utils.parse_query(options, [:limit, :offset, :fields])
+        end
+      end
     end
     alias get_documents documents
 
@@ -153,11 +169,24 @@ module MeiliSearch
       responses
     end
 
-    def delete_documents(documents_ids)
-      if documents_ids.is_a?(Array)
-        http_post "/indexes/#{@uid}/documents/delete-batch", documents_ids
-      else
-        delete_document(documents_ids)
+    # Public: Delete documents from an index
+    #
+    # options: A Hash or an Array containing documents_ids or a hash with filter:.
+    #   filter: - A hash containing a filter that should match documents.
+    #             Available ONLY with Meilisearch v1.2 and newer (optional)
+    #
+    # Returns a Task object.
+    def delete_documents(options = {})
+      Utils.version_error_handler(__method__) do
+        if options.is_a?(Hash) && options.key?(:filter)
+          http_post "/indexes/#{@uid}/documents/delete", options
+        else
+          # backwards compatibility:
+          # expect to be a array or/number/string to send alongside as documents_ids.
+          options = [options] unless options.is_a?(Array)
+
+          http_post "/indexes/#{@uid}/documents/delete-batch", options
+        end
       end
     end
     alias delete_multiple_documents delete_documents
@@ -191,9 +220,13 @@ module MeiliSearch
 
     ### SEARCH
 
+    # options: A Hash
+    #   show_ranking_score - To see the ranking scores for returned documents
+    #   attributes_to_search_on - Customize attributes to search on at search time.
     def search(query, options = {})
-      parsed_options = Utils.transform_attributes({ q: query.to_s }.merge(options.compact))
+      attributes = { q: query.to_s }.merge(options.compact)
 
+      parsed_options = Utils.transform_attributes(attributes)
       response = http_post "/indexes/#{@uid}/search", parsed_options
 
       response['nbHits'] ||= response['estimatedTotalHits'] unless response.key?('totalPages')
@@ -201,6 +234,15 @@ module MeiliSearch
       response
     end
 
+    ### FACET SEARCH
+
+    def facet_search(name, query = '', **options)
+      options.merge!(facet_name: name, facet_query: query)
+      options = Utils.transform_attributes(options)
+
+      http_post("/indexes/#{@uid}/facet-search", options)
+    end
+
     ### TASKS
 
     def task_endpoint
@@ -428,5 +470,49 @@ module MeiliSearch
     def reset_faceting
       http_delete("/indexes/#{@uid}/settings/faceting")
     end
+
+    ### SETTINGS - DICTIONARY
+
+    def dictionary
+      http_get("/indexes/#{@uid}/settings/dictionary")
+    end
+
+    def update_dictionary(dictionary_attributes)
+      attributes = Utils.transform_attributes(dictionary_attributes)
+      http_put("/indexes/#{@uid}/settings/dictionary", attributes)
+    end
+
+    def reset_dictionary
+      http_delete("/indexes/#{@uid}/settings/dictionary")
+    end
+    ### SETTINGS - SEPARATOR TOKENS
+
+    def separator_tokens
+      http_get("/indexes/#{@uid}/settings/separator-tokens")
+    end
+
+    def update_separator_tokens(separator_tokens_attributes)
+      attributes = Utils.transform_attributes(separator_tokens_attributes)
+      http_put("/indexes/#{@uid}/settings/separator-tokens", attributes)
+    end
+
+    def reset_separator_tokens
+      http_delete("/indexes/#{@uid}/settings/separator-tokens")
+    end
+
+    ### SETTINGS - NON SEPARATOR TOKENS
+
+    def non_separator_tokens
+      http_get("/indexes/#{@uid}/settings/non-separator-tokens")
+    end
+
+    def update_non_separator_tokens(non_separator_tokens_attributes)
+      attributes = Utils.transform_attributes(non_separator_tokens_attributes)
+      http_put("/indexes/#{@uid}/settings/non-separator-tokens", attributes)
+    end
+
+    def reset_non_separator_tokens
+      http_delete("/indexes/#{@uid}/settings/non-separator-tokens")
+    end
   end
 end

data/lib/meilisearch/utils.rb

@@ -9,6 +9,7 @@ module MeiliSearch
       when Array
         body.map { |item| transform_attributes(item) }
       when Hash
+        warn_on_non_conforming_attribute_names(body)
         parse(body)
       else
         body
@@ -23,8 +24,12 @@ module MeiliSearch
         end
     end
 
+    def self.filter(original_options, allowed_params = [])
+      original_options.transform_keys(&:to_sym).slice(*allowed_params)
+    end
+
     def self.parse_query(original_options, allowed_params = [])
-      only_allowed_params = original_options.transform_keys(&:to_sym).slice(*allowed_params)
+      only_allowed_params = filter(original_options, allowed_params)
 
       Utils.transform_attributes(only_allowed_params).then do |body|
         body.transform_values do |v|
@@ -33,6 +38,36 @@ module MeiliSearch
       end
     end
 
-    private_class_method :parse
+    def self.message_builder(current_message, method_name)
+      "#{current_message}\nHint: It might not be working because maybe you're not up " \
+        "to date with the Meilisearch version that `#{method_name}` call requires."
+    end
+
+    def self.version_error_handler(method_name)
+      yield if block_given?
+    rescue MeiliSearch::ApiError => e
+      message = message_builder(e.http_message, method_name)
+
+      raise MeiliSearch::ApiError.new(e.http_code, message, e.http_body)
+    rescue StandardError => e
+      raise e.class, message_builder(e.message, method_name)
+    end
+
+    def self.warn_on_non_conforming_attribute_names(body)
+      return if body.nil?
+
+      non_snake_case = body.keys.grep_v(/^[a-z0-9_]+$/)
+      return if non_snake_case.empty?
+
+      message = <<~MSG
+        Attributes will be expected to be snake_case in future versions of Meilisearch Ruby.
+
+        Non-conforming attributes: #{non_snake_case.join(', ')}
+      MSG
+
+      warn(message)
+    end
+
+    private_class_method :parse, :message_builder
   end
 end

data/lib/meilisearch/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module MeiliSearch
-  VERSION = '0.23.0'
+  VERSION = '0.26.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.23.0
+  version: 0.26.0
 platform: ruby
 authors:
 - Meili
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-03 00:00:00.000000000 Z
+date: 2023-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty