mongodb_meilisearch 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90bfdb172f8ff15ffe0d490cbfc03939de3f3b05881b830f0515807f35882e96
-  data.tar.gz: 1c680831f8b35d5ee540fab9e7ec47b3b093f02a5be054a1b0c393597930e556
+  metadata.gz: f57c18174244b2885536a990a2d602ce833e949dcf205112c78f30567a6eee6a
+  data.tar.gz: bb5bdd6c8cb90a6e1334c4606063a56b71515510f0f45c3e1ae2d817b4497163
 SHA512:
-  metadata.gz: f10fe61be5b67e4e5264abed8adabb41ecdb6a3e2cbdca2ae23f5979d552498a018bf327c682cc28e54b37ce16b9c50f74dca294eb55a0acbff5277a5f0389f0
-  data.tar.gz: 5d39d79ddf1bc213760959fdd4ebee1451cc2b2c1a6a48b1a24e6e74bd3dff688121e12d2dad8fc103c38db14d7766fdc2c6117b592cf2445eebfd2aaa6773b9
+  metadata.gz: cb3e4f69dad6365682470020e3acc864492c45d79de54fb65fbab6fb9eaacb0811d8af02414f4df324a9d0cf64278646e0eac3062e7aff1a9873aa2f264d0d64
+  data.tar.gz: 54aa4eea1cfe0b378e9ad93c719eb31a5c35c96c08ef842d975efb8391cf1b55b0ca53e9ca3d8daf98626a02c30ea817e9623c78de0b6ce14ade726473767304

data/.changelog_entries/1d952700c037533909615648b5f10582.json

@@ -0,0 +1 @@
+{"type":"Documented","tickets":[],"description":"README: improved example code.","tags":[]}

data/.changelog_entries/config.json

@@ -0,0 +1 @@
+{"git_add":true}

data/.rubocop.yml

@@ -1116,12 +1116,6 @@ Style/ComparableClamp:
 Style/ConcatArrayLiterals:
   Enabled: false
 
-Style/ConditionalAssignment:
-  Enabled: true
-  EnforcedStyle: assign_to_condition
-  SingleLineConditionsOnly: true
-  IncludeTernaryExpressions: true
-
 Style/ConstantVisibility:
   Enabled: false
 
@@ -1857,3 +1851,11 @@ Style/YodaExpression:
 Style/ZeroLengthPredicate:
   Enabled: false
 
+# this is horrible for readability
+# and maintainability
+Style/ConditionalAssignment:
+  Enabled: false
+
+# I'll nest how I wanna nest! :p
+RSpec/NestedGroups:
+  Enabled: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mongodb_meilisearch (1.0.0)
+    mongodb_meilisearch (1.1.0)
       meilisearch
       mongoid (~> 7.0)
       rails
@@ -131,6 +131,8 @@ GEM
     nio4r (2.5.9)
     nokogiri (1.15.3-arm64-darwin)
       racc (~> 1.4)
+    nokogiri (1.15.3-x86_64-linux)
+      racc (~> 1.4)
     parallel (1.23.0)
     parser (3.2.2.3)
       ast (~> 2.4.1)
@@ -220,6 +222,7 @@ GEM
 
 PLATFORMS
   arm64-darwin-22
+  x86_64-linux
 
 DEPENDENCIES
   debug

data/README.md

@@ -1,3 +1,14 @@
+# <!-- :TOC: -->
+- [MongodbMeilisearch](#mongodbmeilisearch)
+  - [Installation](#installation)
+  - [Usage](#usage)
+  - [Model Integration](#model-integration)
+  - [Indexes](#indexes)
+  - [Searching](#searching)
+  - [Development](#development)
+  - [License](#license)
+  - [Code of Conduct](#code-of-conduct)
+
 # MongodbMeilisearch
 
 A simple gem for integrating [Meilisearch](https://www.meilisearch.com) into Ruby† applications that are backed by [MongoDB](https://www.mongodb.com/).
@@ -35,7 +46,10 @@ SEARCH_ENABLED=true
 MEILISEARCH_API_KEY=<your api key here>
 MEILISEARCH_URL=http://127.0.0.1:7700
 
-# optional configuration
+```
+
+Optional configuration
+```bash
 MEILISEARCH_TIMEOUT=10
 MEILISEARCH_MAX_RETRIES=2
 ```
@@ -46,8 +60,8 @@ Add the following near the top of your model. Only the `extend` and `include` li
 This assumes your model also includes `Mongoid::Document`
 
 ```ruby
-  extend Search::ClassMethods
   include Search::InstanceMethods
+  extend Search::ClassMethods
 ```
 
 If you want Rails to automatically add, update, and delete records from the index, add the following to your model. 
@@ -65,19 +79,46 @@ You can override these methods if needed, but you're unlikely to want to.
 
 Assuming you've done the above a new index will be created with a name that
 corresponds to your model's  name, only in snake case. All of your models
-attributes will be indexed and [filterable](https://www.meilisearch.com/docs/learn/fine_tuning_results/filtering).
+fields will be indexed and [filterable](https://www.meilisearch.com/docs/learn/fine_tuning_results/filtering).
+
+
+### Example Rails Model
+
+Here's what it looks like when you put it all 
+together in a Rails model with the default behavior.
 
+```ruby
+class Person
+  include Mongoid::Document
+  extend Search::ClassMethods
+
+  if Search::Client.instance.enabled?
+    after_create  :add_to_search
+    after_update  :update_in_search
+    after_destroy :remove_from_search
+  end
+
+  # normal Mongoid attributes
+  field :name, type: String
+  field :description, type: String
+  field :age, type: Integer
+end
+```
+
+Note that that _unless you configure it otherwise_ the ids of `belongs_to` objects 
+will not be searchable. This is because they're random strings that no human's ever
+going to be searching for, and we don't want to waste RAM or storage.
 
 ### Going Beyond The Defaults 
 This module strives for sensible defaults, but you can override them with the
 following optional constants:
 
-* `PRIMARY_SEARCH_KEY` - a Symbol matching one of your model's attributes 
+- `PRIMARY_SEARCH_KEY` - a Symbol matching one of your model's attributes 
   that is guaranteed unique. This defaults to `_id`
-* `SEARCH_INDEX_NAME` - a String - useful if you want to have records from
+- `SEARCH_INDEX_NAME` - a String - useful if you want to have records from
   multiple classes come back in the same search results. This defaults to the
   underscored form of the current class name.
-* `SEARCH_OPTIONS` - a hash of key value pairs in JS style
+- `SEARCH_OPTIONS` - a hash of key value pairs in JS style
     - See  the [meilisearch search parameter docs](https://www.meilisearch.com/docs/reference/api/search#search-parameters) for details.
     - example from [meliesearch's `multi_param_spec`](https://github.com/meilisearch/meilisearch-ruby/blob/main/spec/meilisearch/index/search/multi_params_spec.rb)
   ```ruby
@@ -89,7 +130,7 @@ following optional constants:
         limit: 2
       }
     ```
-* `SEARCH_RANKING_RULES` - an array of strings that correspond to meilisearch rules
+- `SEARCH_RANKING_RULES` - an array of strings that correspond to meilisearch rules
   see [meilisearch ranking rules docs](https://www.meilisearch.com/docs/learn/core_concepts/relevancy#ranking-rules)
 You probably don't want to change this.
 
@@ -126,7 +167,7 @@ as `original_document_id`. This is useful if you want to be able to retrieve the
 You probably don't want to index _all_ the fields. For example, 
 unless you intend to allow users to sort by when a record was created, 
 there's no point in recording it's `created_at` in the search index. 
-It'll just waste bandwidth, memory, and disk space.
+It'll just waste bandwidth, memory, and disk space. 
 
 Define a `SEARCHABLE_ATTRIBUTES` constant with an array of strings to limit things. 
 By default these will _also_ be the fields you can filter on. Note that 
@@ -142,6 +183,15 @@ document's `BSON::ObjectId`.
   SEARCHABLE_ATTRIBUTES = searchable_attributes - [:created_at]
 ```
 
+#### Including Foreign Key data
+If, for example, your `Person` `belongs_to: group` 
+and you wanted that group's id to be searchable you would include `group_id`
+in the list. 
+
+If you don't specify any `SEARCHABLE_ATTRIBUTES`, the default list will
+exclude any fields that are `Mongoid::Fields::ForeignKey` objects.
+
+
 #### Getting Extra Specific
 If your searchable data needs to by dynamically generated instead of 
 just taken directly from the `Mongoid::Document`'s attributes you can
@@ -150,8 +200,8 @@ must return a hash, and that hash must include the following keys:
 - `"id"` - a string that uniquely identifies the record
 - `"object_class"` the name of the class that this record corresponds to.
 
-The value of `"object_class"` is usually just `self.class.name`. Additionally,
-this is something specific to this gem, and not Meilisearch itself.
+The value of `"object_class"` is usually just `self.class.name`. 
+This is something specific to this gem, and not Meilisearch itself.
 
 See `InstanceMethods#search_indexable_hash` for an example. 
 
@@ -176,7 +226,8 @@ Then call the following. If `FILTERABLE_ATTRIBUTE_NAMES` is defined it will use
 otherwise it will use whatever `.searchable_attributes` returns.
 
 ```ruby
-MyModel.set_filterable_attributes!
+MyModel.set_filterable_attributes! # synchronous 
+MyModel.set_filterable_attributes  # asynchronous
 ``` 
 
 This will cause Meilisearch to reindex all the records for that index. If you
@@ -185,14 +236,31 @@ on a background thread. Note that filtering is managed at the index level, not t
 record level. By setting filterable attributes you're giving Meilisearch
 guidance on what to do when indexing your data.
 
+Note that you will encounter problems in a shared index if you try and
+filter on a field that one of the contributing models doesn't have set
+as a filterable field, or doesn't have at all.
+
+### Sortable Fields
+
+Sortable fields work in essentially the same way as filterable fields.
+By default it's the same as your `FILTERABLE_ATTRIBUTE_NAMES` which, in turn, defaults to your `SEARCHABLE_ATTRIBUTES` You can
+override it by setting `SORTABLE_ATTRIBUTE_NAMES`. 
 
+Note that you will encounter problems in a shared index if you try and
+sort on a field that one of the contributing models doesn't have set
+as a sortable field, or doesn't have at all.
+
+```ruby
+MyModel.set_sortable_attributes! # synchronous 
+MyModel.set_sortable_attributes  # asynchronous
+``` 
 
 ### Indexing things
 **Important note**: By default anything you do that updates the search index (adding, removing, or changing) happens asynchronously. 
 
 Sometimes, especially when debugging something on the console, you want to
-update the index _synchronously_. The convention used in this codebase is that
-the synchronous methods  are the ones with the bang.  Similar to how mutating
+update the index _synchronously_. The convention used in this codebase - and in the meilisearch-ruby library we build on - is that
+the synchronous methods are the ones with the bang.  Similar to how mutating
 state is potentially dangerous and noted with a bang, using synchronous methods
 is potentially problematic for your users, and thus noted with a bang.
 
@@ -200,7 +268,12 @@ is potentially problematic for your users, and thus noted with a bang.
 For example: 
 ```ruby
 MyModel.reindex  # runs asyncronously
-# vs 
+
+```
+
+vs 
+
+```ruby
 MyModel.reindex! # runs synchronously
 ```
 
@@ -209,7 +282,9 @@ MyModel.reindex! # runs synchronously
 **Reindexing**  
 Calling `MyModel.reindex!` deletes all the existing records from the current index,
 and then reindexes all the records for the current model. It's safe to run this
-even if there aren't any records. 
+even if there aren't any records. In addition to re-indexing your models,
+it will update/set the "sortable" and "filterable" fields on the 
+relevant indexes.
 
 Note: reindexing behaves slightly differently than all the other methods.
 It runs semi-asynchronously by default. The Asynchronous form will first, 
@@ -303,8 +378,7 @@ E.g. `MyModel.search("search term", include_metadata: false)`
 Search results, ids only, for a class where `CLASS_PREFIXED_SEARCH_IDS=false`. 
 
 ```ruby
-Note.search('foo', ids_only: true)
-# returns 
+Note.search('foo', ids_only: true) # => returns 
 { 
   "matches" =>  [
     "64274a5d906b1d7d02c1fcc7",
@@ -328,8 +402,7 @@ Without `ids_only` you get full objects in a `matches` array.
 
 
 ```ruby
-Note.search('foo') # or Note.search('foo', ids_only: false)
-# returns 
+Note.search('foo') # or Note.search('foo', ids_only: false) # => returns 
 { 
   "matches" => [
     #<Note _id: 64274a5d906b1d7d02c1fcc7, created_at: 2023-03-15 00:00:00 UTC, updated_at: 2023-03-31 21:02:21.108 UTC, title: "A note from the past", body: "a body", type: "misc", context: "dachary">,
@@ -348,8 +421,7 @@ Note.search('foo') # or Note.search('foo', ids_only: false)
 If `Note` records shared an index with `Task` and they both had `CLASS_PREFIXED_SEARCH_ID=true` you'd get a result like this.
 
 ```ruby
-Note.search('foo')
-# returns 
+Note.search('foo') #=> returns 
 { 
   "matches" => [
       #<Note _id: 64274a5d906b1d7d02c1fcc7, created_at: 2023-03-15 00:00:00 UTC, updated_at: 2023-03-31 21:02:21.108 UTC, title: "A note from the past", body: "a body", type: "misc", context: "dachary">,

data/lib/mongodb_meilisearch/version.rb

@@ -5,5 +5,5 @@ module MongodbMeilisearch
   # @note This library will adhere to strict semantic versioning.
   # See https://semver.org/
   #
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/search/class_methods.rb

@@ -339,7 +339,12 @@ module Search
     # Please don't override this. Define SEARCHABLE_ATTRIBUTES instead.
     # @return [Array[Symbol]] an array of attribute names as symbols
     def default_searchable_attributes
-      attribute_names.map { |n| n.to_sym }
+      good_fields = []
+      fields.each { |name, obj|
+        next if name == "_type"
+        good_fields.push(name.to_sym) unless obj.is_a? Mongoid::Fields::ForeignKey
+      }
+      good_fields
     end
 
     # This returns the list from SEARCHABLE_ATTRIBUTES if defined,
@@ -373,28 +378,92 @@ module Search
     # @return [Array[Symbol]] an array of symbols corresponding to
     # filterable attribute names.
     def filterable_attributes
-      attributes = []
-      if constants.include?(:FILTERABLE_ATTRIBUTE_NAMES)
-        # the union operator is to guarantee no-one tries to create
-        # invalid filterable attributes
-        attributes = const_get(:FILTERABLE_ATTRIBUTE_NAMES).map(&:to_sym) & searchable_attributes
-      elsif !unfilterable?
-        attributes = searchable_attributes
-      end
-      attributes << "object_class" unless attributes.include? "object_class"
-      attributes
+      @_filterable_attributes ||= sort_or_filter_attributes(:filterable)
+    end
+
+    def sortable_attributes
+      @_sortable_attributes ||= sort_or_filter_attributes(:sortable)
+    end
+
+    # For more details on sortable attributes see the official
+    # Meilisearch docs
+    # https://www.meilisearch.com/docs/reference/api/settings#sortable-attributes
+    #
+    #
+    # @return [Array] - an array of attributes configured as sortable
+    # in the index.
+    def meilisearch_sortable_attributes
+      # Search::Client.instance.http_get(
+      search_index.http_get(
+        "/indexes/#{search_index}/settings/sortable-attributes"
+      )
+    end
+
+    def meilisearch_filterable_attributes
+      # Search::Client.instance.http_get(
+      search_index.http_get(
+        "/indexes/#{search_index}/settings/filterable-attributes"
+      )
     end
 
     # Updates the filterable attributes in the search index.
     # Note that this forces Meilisearch to rebuild your index,
     # which may take time. Best to run this in a background job
     # for large datasets.
-    def set_filterable_attributes!(new_attributes = filterable_attributes)
+    def set_filterable_attributes(new_attributes = filterable_attributes)
       search_index.update_filterable_attributes(new_attributes)
     end
 
+    def set_filterable_attributes!(new_attributes = filterable_attributes)
+      # meilisearch-ruby doesn't provide a synchronous version of this
+      task = set_filterable_attributes(new_attributes)
+      search_index.wait_for_task(task["taskUid"])
+    end
+
+    # Updates the sortable attributes in the search index.
+    # Note that this forces Meilisearch to rebuild your index,
+    # which may take time. Best to run this in a background job
+    # for large datasets.
+    def set_sortable_attributes(new_attributes = sortable_attributes)
+      search_index.update_sortable_attributes(new_attributes)
+    end
+
+    def set_sortable_attributes!(new_attributes = sortable_attributes)
+      # meilisearch-ruby doesn't provide a synchronous version of this
+      task = set_sortable_attributes(new_attributes)
+      search_index.wait_for_task(task["taskUid"])
+    end
+
     private
 
+    # @param [Symbol] which - either :sortable or :filterable
+    def sort_or_filter_attributes(which)
+      constant_symbol = (which == :sortable) ? :SORTABLE_ATTRIBUTE_NAMES : :FILTERABLE_ATTRIBUTE_NAMES
+
+      if which == :filterable && unfilterable? && constants.include?(constant_symbol)
+        raise "You can't define FILTERABLE_ATTRIBUTE_NAMES & UNFILTERABLE_IN_SEARCH on #{self.class.name}"
+      end
+      # with that out of the way...
+
+      attributes = []
+      # sortable == defined or filterable
+      # filterable == defined or search
+      if constants.include?(constant_symbol)
+        # the union operator is to guarantee no-one tries to create
+        # invalid filterable attributes
+        attributes = const_get(constant_symbol).map(&:to_sym) & searchable_attributes
+      elsif which == :filterable && !unfilterable?
+        attributes = searchable_attributes
+      elsif which == :sortable
+        # yes this is recursive...
+        attributes = filterable_attributes
+      end
+      # we need object_class even if you're unfilterable, because
+      # we need to be able to filter by object_class in shared indexes.
+      attributes << :object_class unless attributes.include? :object_class
+      attributes
+    end
+
     def lookup_matches_by_class!(results, primary_key)
       # matches_by_class contains a hash of
       # "FooModel" => [<array of ids>]
@@ -523,7 +592,13 @@ module Search
       end
       add_documents(documents, async: async) if documents.size != 0
 
-      set_filterable_attributes!
+      if async
+        set_filterable_attributes
+        set_sortable_attributes
+      else
+        set_filterable_attributes!
+        set_sortable_attributes!
+      end
     end
   end
 end

data/lib/search/client.rb

@@ -13,8 +13,8 @@ module Search
         max_retries = ENV.fetch("MEILISEARCH_MAX_RETRIES", 2).to_i
         if url.present? && api_key.present?
           @client = MeiliSearch::Client.new(url, api_key,
-            timeout: timeout,
-            max_retries: max_retries)
+                                            timeout: timeout,
+                                            max_retries: max_retries)
         else
           Rails.logger.warn("UNABLE TO CONFIGURE SEARCH. Check env vars.")
           @client = nil

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mongodb_meilisearch
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - masukomi
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-22 00:00:00.000000000 Z
+date: 2023-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -143,6 +143,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".changelog_entries/1d952700c037533909615648b5f10582.json"
+- ".changelog_entries/config.json"
 - ".env"
 - ".idea/.gitignore"
 - ".idea/modules.xml"