mongodb_meilisearch 1.3.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff219e5de4c77b4b06515946701f57eee82588691ec7931d963a70011409c79a
-  data.tar.gz: c51b7f234431417abe62fdd5365a106b4d493fe9e49b7802726cdd61a519db48
+  metadata.gz: 0c07c25d10efdfee292401ba54dacb34aee8abd153226a3618a2c88de96661dc
+  data.tar.gz: 40ec770c86ab522f3cf49ff950230a8f82f6527d4a3b33842f8d56c12f47067a
 SHA512:
-  metadata.gz: b21b329983c8ac89de3e8543cccb021e63a7d1411b0cb464885ea3019fe815f7f72de8f408da1bc18d38cc2ebeac929f5491ec643ee3ea5e8a102dde3c582aae
-  data.tar.gz: 4c44d1ae3784917566bd6a1a2bb3993a718fe57d5cf97e7e9af21587a3587fda1d1c77764606ad21dd06b9c8e107eff82e7173d8d019ecd2e18dad46094a19a9
+  metadata.gz: db89325982a30521bec7fcaee27f0da61a177b7738591dbf0b95c36666f3a02e94a85e3403a7c2b81a92d0396839b1344dc7c63a4a4ae937793c743bcbb26e4f
+  data.tar.gz: 05415b71991b53ff28ab4c10e5c3b9ea27ef7399f1c91d1e0444974469b9649d24191ec0438a91045438c95207fa4dcf6f4c4ea545008e5d30b52574daf5752b

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mongodb_meilisearch (1.3.0)
+    mongodb_meilisearch (2.0.0)
       meilisearch
       mongoid (~> 7.0)
       rails

data/README.org

@@ -0,0 +1,621 @@
+#+OPTIONS: toc:2
+* Table of Contents :TOC:
+- [[#mongodbmeilisearch][MongodbMeilisearch]]
+  - [[#installation][Installation]]
+  - [[#usage][Usage]]
+  - [[#model-integration][Model Integration]]
+  - [[#indexes][Indexes]]
+  - [[#searching][Searching]]
+  - [[#upgrading][Upgrading]]
+  - [[#development][Development]]
+  - [[#license][License]]
+  - [[#code-of-conduct][Code of Conduct]]
+- [[#footnotes][Footnotes]]
+
+* MongodbMeilisearch
+A simple gem for integrating
+[[https://www.meilisearch.com][Meilisearch]] into Ruby applications
+that are backed by [[https://www.mongodb.com/][MongoDB]].
+
+** Installation
+Install the gem and add to the application's Gemfile by executing:
+
+#+begin_example
+$ bundle add mongodb_meilisearch
+#+end_example
+
+If bundler is not being used to manage dependencies, install the gem by
+executing:
+
+#+begin_example
+$ gem install mongodb_meilisearch
+#+end_example
+
+** Usage
+A high level overview
+
+*** Pre-Requisites
+- [[https://www.meilisearch.com][Meilisearch]]
+- [[https://www.mongodb.com/][MongoDB]]
+- Some models that =include Mongoid::Document=
+
+*** Configuration
+**** Background
+Meilisearch uses 3 different API keys.
+- A Master API Key
+- An Administrative API key
+- A Search API key
+
+The Master API key should be used when starting Meilisearch,[fn:macos] but should /never/ be used when searching or administering [[https://www.meilisearch.com/docs/learn/security/basic_security][for security reasons]].
+
+When you start it with a master key, it will create default Search & Administrative API Keys.[fn:default_keys] These ~mongodb_meilisearch~ uses these for searching & administering respectively.
+
+**** Details
+=MEILI_MASTER_KEY= is the environment variable Meilisearch uses for setting its master key at startup if it isn't provided via command line arguments.
+
+=MEILISEARCH_SEARCH_KEY= & =MEILISEARCH_ADMIN_KEY= are for Search & administration respectively. Administration is /everything/ that isn't search, including things like adding new records to the index.
+
+I recommend you define the Search & Administration keys. If you provide both of those the =MEILI_MASTER_KEY= will /not/ be required, /or used/ if present. If you only know the master key, there are details below for how to obtain the others.
+
+Define the following variables in your environment (or =.env= file if
+you're using [[https://github.com/bkeepers/dotenv][dotenv]]). The url below is the default one Meilisearch
+uses when run locally. Change it if you're running it on a different box or have otherwise changed the default location setup.
+
+#+begin_src sh
+SEARCH_ENABLED=true
+MEILI_MASTER_KEY=<your search master key>
+MEILISEARCH_SEARCH_KEY=<your search api key here>
+MEILISEARCH_ADMIN_KEY=<your admin api key here>
+MEILISEARCH_URL=http://127.0.0.1:7700
+#+end_src
+
+Optional configuration
+
+#+begin_src sh
+MEILISEARCH_TIMEOUT=10
+MEILISEARCH_MAX_RETRIES=2
+#+end_src
+
+
+👋 Environment variables starting with =MEILI_= are [[https://www.meilisearch.com/docs/learn/configuration/instance_options][ones defined by Meilisearch]]. The ones starting with =MEILISEARCH_= are specific to this library.
+
+***** Finding your Search & Admin keys
+Meilisearch doesn't make it easy to find out what your default search & administration API keys are, and I haven't found a way to define them yourself.
+
+Fortunately for you, this library has an easy way, and you've got this library. 😉
+
+#+begin_src ruby
+Search::Client.instance.get_default_keys("your master key here")
+#+end_src
+
+This will return a hash with the keys you'll need.
+
+#+begin_src ruby
+{:search=>"your search api key",
+ :admin=>"your admin api key"}
+#+end_src
+
+Use those keys in your environment. The next time the =Search::Client= is initialized it'll use them.
+
+** Model Integration
+Add the following near the top of your model. Only the =extend= and
+=include= lines are required. This assumes your model also includes
+=Mongoid::Document=
+
+#+begin_src ruby
+  include Search::InstanceMethods
+  extend Search::ClassMethods
+#+end_src
+
+If you want Rails to automatically add, update, and delete records from
+the index, add the following to your model.
+
+You can override these methods if needed, but you're unlikely to want
+to.
+
+#+begin_src ruby
+  # enabled?() is controlled by the SEARCH_ENABLED environment variable
+  if Search::Client.instance.enabled?
+    after_create  :add_to_search
+    after_update  :update_in_search
+    after_destroy :remove_from_search
+  end
+#+end_src
+
+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 fields will be indexed and
+[[https://www.meilisearch.com/docs/learn/fine_tuning_results/filtering][filterable]].
+
+*** Example Rails Model
+Here's what it looks like when you put it all together in a Rails model
+with the default behavior.
+
+#+begin_src 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
+#+end_src
+
+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 that is guaranteed unique. This defaults to =_id=
+- =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
+  - See the
+    [[https://www.meilisearch.com/docs/reference/api/search#search-parameters][meilisearch search parameter docs]] for details.
+  - example from
+    [[https://github.com/meilisearch/meilisearch-ruby/blob/main/spec/meilisearch/index/search/multi_params_spec.rb][meliesearch's multi_param_spec]]
+
+  #+begin_src ruby
+      {
+        attributesToCrop: ['title'],
+        cropLength: 2,
+        filter: 'genre = adventure',
+        attributesToHighlight: ['title'],
+        limit: 2
+      }
+  #+end_src
+
+- =SEARCH_RANKING_RULES= - an array of strings that correspond to
+  meilisearch rules see
+  [[https://www.meilisearch.com/docs/learn/core_concepts/relevancy#ranking-rules][meilisearch ranking rules docs]] You probably don't want to change this.
+
+** Indexes
+Searching is limited to records that have been added to a given index.
+This means, if you want to perform one search and get back records from
+multiple models you'll need to add them to the same index.
+
+In order to do that add the =SEARCH_INDEX_NAME= constant to the model
+whose search stuff you want to end up in the same index. You can name
+this just about anything. The important thing is that all the models
+that share this index have the same =SEARCH_INDEX_NAME= constant
+defined. You may want to just add it to a module they all import.
+
+#+begin_src ruby
+  SEARCH_INDEX_NAME='general_search'
+#+end_src
+
+If multiple models are using the same index, you should also add
+=CLASS_PREFIXED_SEARCH_IDS=true=. This causes the =id= field to be
+=<ClassName>_<_id>= For example, a =Note= record might have an index of
+="Note_64274543906b1d7d02c1fcc6"=. If undefined this will default to
+=false=. This is not needed if you can absolutely guarantee that there
+will be no overlap in ids amongst all the models using a shared index.
+
+#+begin_src ruby
+  CLASS_PREFIXED_SEARCH_IDS=true
+#+end_src
+
+Setting =CLASS_PREFIXED_SEARCH_IDS= to =true= will also cause the
+original Mongoid =_id= field to be indexed as =original_document_id=.
+This is useful if you want to be able to retrieve the original record
+from the database.
+
+*** Searchable Data
+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.
+
+Define a =SEARCHABLE_ATTRIBUTES= constant with an array of strings to
+limit things. These are the field names, and/or names of methods you
+wish to have indexed.
+
+By default these will /also/ be the fields you can filter on.
+
+Note that Meilisearch requires there to be an =id= field and it must be
+a string. If you don't define one it will use string version of the
+=_id= your document's =BSON::ObjectId=.
+
+#+begin_src ruby
+  # explicitly define the fields you want to be searchable
+  # this should be an array of symbols
+  SEARCHABLE_ATTRIBUTES = %w[title body]
+  # OR explicitly define the fields you DON'T want searchable 
+  SEARCHABLE_ATTRIBUTES = searchable_attributes - [:created_at]
+#+end_src
+
+**** 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 or
+existing methods you can define a =search_indexable_hash= method on your
+class.
+
+Before you do, please note that as of v1.1 your =SEARCHABLE_ATTRIBUTES=
+constant can contain fields and method names in its array of values.
+Making a method for each thing dynamically generated thing you want in
+the search and then including it in SEARCHABLE_ATTRIBUTES is going to be
+the easiest way of accomplishing this.
+
+Your =search_indexable_hash= 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=. This is
+something specific to this gem, and not Meilisearch itself.
+
+See =InstanceMethods#search_indexable_hash= for an example.
+
+**** Filterable Fields
+If you'd like to only be able to filter on a subset of those then you
+can define =FILTERABLE_ATTRIBUTE_NAMES= but it /must/ be a subset of
+=SEARCHABLE_ATTRIBUTES=. This is enforced by the gem to guarantee no
+complaints from Meilisearch. These must be symbols.
+
+If you have no direct need for filterable results, set
+=UNFILTERABLE_IN_SEARCH=true= in your model. This will save on index
+size and speed up indexing, but you won't be able to filter search
+results, and that's half of what makes Meilisearch so great. It should
+be noted, that even if this /is/ set to =true= this gem will still add
+="object_class"= as a filterable attribute.
+
+This is the magic that allows you to have an index shared by multiple
+models and still be able to retrieve results specifically for one.
+
+If you decide to re-enable filtering you can remove that constant, or
+set it to false. Then call the following. If
+=FILTERABLE_ATTRIBUTE_NAMES= is defined it will use that, otherwise it
+will use whatever =.searchable_attributes= returns.
+
+#+begin_src ruby
+MyModel.set_filterable_attributes! # synchronous 
+MyModel.set_filterable_attributes  # asynchronous
+#+end_src
+
+This will cause Meilisearch to reindex all the records for that index.
+If you have a large number of records this could take a while. Consider
+running it on a background thread. Note that filtering is managed at the
+index level, not the individual 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.
+
+#+begin_src ruby
+MyModel.set_sortable_attributes! # synchronous 
+MyModel.set_sortable_attributes  # asynchronous
+#+end_src
+
+*** 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 - 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.
+
+For example:
+
+#+begin_src ruby
+MyModel.reindex  # runs asyncronously
+#+end_src
+
+vs
+
+#+begin_src ruby
+MyModel.reindex! # runs synchronously
+#+end_src
+
+**** Reindexing, Adding, Updating, and Deleting
+*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. 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, attempt to /synchronously/ delete all the records from the
+index. If that fails an exception will be raised. Otherwise you'd think
+everything was fine when actually it had failed miserably. If you call
+=.reindex!= it will be entirely synchronous.
+
+Note: adding, updating, and deleting should happen automatically if
+you've defined =after_create=, =after_update=, and =after_destroy= as
+instructed above. You'll mostly only want to use these when manually
+mucking with things in the console.
+
+*Adding*
+Be careful to not add documents that are already in the index.
+
+- Add everything: =MyClass.add_all_to_search=
+- Add a specific instance: =my_instance.add_to_search=
+- Add a specific subset of documents:
+  =MyClass.add_documents(documents_hashes)= IMPORTANT:
+  =documents_hashes= must be an array of hashes that were each generated
+  via =search_indexable_hash=
+
+*Updating*
+- Update everything: call =reindex=
+- Update a specific instance: =my_instance.update_in_search=
+- Update a specific subset of documents: =MyClass.update_documents(documents_hashes)= IMPORTANT: =documents_hashes= must be an array of hashes that
+  were generated via =search_indexable_hash= The =PRIMARY_SEARCH_KEY=
+  (=_id= by default) will be used to find records in the index to update.
+
+*Deleting*
+- Delete everything: =MyClass.delete_all_documents!=
+- Delete a specific record: =my_instance.remove_from_search=
+- Delete the index: =MyClass.delete_index!=
+  WARNING: if you think you should use this, /you're probably mistaken/.
+
+**** Indexes
+By default every model gets its own search index. This means that
+=Foo.search("some text")= will only search =Foo= objects. To have a
+search cross objects you'll need to use a "Shared Index" (see below).
+
+The name of the index isn't important when not using shared indexes. By
+default a model's index is the snake cased form of the class name. For
+example, data for =MyWidget= models will be stored in the =my_widget=
+index.
+
+**** Shared indexes
+Imagine you have a =Note= and a =Comment= model, sharing an index so
+that you can perform a single search and have search results for both
+models that are ranked by relevance.
+
+In this case both models would define a =SEARCH_INDEX_NAME= constant
+with the same value. You might want to just put this, and the other
+search stuff in a common module that they all =include=.
+
+Then, when you search you can say =Note.search("search term")= and it
+will /only/ bring back results for =Note= records. If you want to
+include results that match =Comment= records too, you can set the
+optional =filtered_by_class= parameter to =false=.
+
+For example: =Note.search("search term", filtered_by_class: false)= will
+return all matching =Note= results, as well as results for /all/ the
+other models that share the same index as =Note=.
+
+⚠ Models sharing the same index must share the same primary key field as
+well. This is a known limitation of the system.
+
+** Searching
+To get a list of all the matching objects in the order returned by the
+search engine run =MyModel.search("search term")= Note that this will
+restrict the results to records generated by the model you're calling
+this on. If you have an index that contains data from multiple models
+and wish to include all of them in the results pass in the optional
+=filtered_by_class= parameter with a =false= value. E.g.
+=MyModel.search("search term", filtered_by_class: false)=
+
+Searching returns a hash, with the class name of the results as the key
+and an array of String ids, or =Mongoid::Document= objects as the value.
+By default it assumes you want =Mongoid::Document= objects. The returned
+hash /also/ includes a key of ="search_result_metadata"= which includes
+the metadata provided by Meilisearch regarding your request. You'll need
+this for pagination if you have lots of results. To /exclude/ the
+metadata pass =include_metadata: false= as an option. E.g.
+=MyModel.search("search term", include_metadata: false)=
+
+*** Useful Keyword Parameters
+- =ids_only=
+  - only return matching ids. These will be an array under the
+    ="matches"= key.
+  - defaults to =false=
+- =filtered_by_class=
+  - limit results to the class you initiated the search from. E.g.
+    =Note.search("foo")= will only return results from the =Note= class
+    even if there are records from other classes in the same index.
+  - defaults to =true=
+- =include_metadata=
+  - include the metadata about the search results provided by
+    Meilisearch. If true (default) there will be a
+    ="search_result_metadata"= key, with a hash of the Meilisearch
+    metadata.
+  - You'll likely need this in order to support pagination, however if
+    you just want to return a single page worth of data, you can set
+    this to =false= to discard it.
+  - defaults to =true=
+
+*** Example Search Results
+Search results, ids only, for a class where
+=CLASS_PREFIXED_SEARCH_IDS=false=.
+
+#+begin_src ruby
+Note.search('foo', ids_only: true) # => returns 
+{ 
+  "matches" =>  [
+    "64274a5d906b1d7d02c1fcc7",
+    "643f5e1c906b1d60f9763071",
+    "64483e63906b1d84f149717a"
+  ],
+  "search_result_metadata" => {
+          "query"=>query_string, 
+          "processingTimeMs"=>1, 
+          "limit"=>50,
+          "offset"=>0, 
+          "estimatedTotalHits"=>33, 
+          "nbHits"=>33
+  }
+}
+#+end_src
+
+If =CLASS_PREFIXED_SEARCH_IDS=true= the above would have ids like
+="Note_64274a5d906b1d7d02c1fcc7"=
+
+Without =ids_only= you get full objects in a =matches= array.
+
+#+begin_src ruby
+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">,
+    #<Note _id: 643f5e1c906b1d60f9763071, created_at: 2023-04-18 00:00:00 UTC, updated_at: 2023-04-19 03:21:00.41 UTC, title: "offline standup ", body: "onother body", type: "misc", context: "WORK">,
+    #<Note _id: 64483e63906b1d84f149717a, created_at: 2023-04-25 00:00:00 UTC, updated_at: 2023-04-26 11:23:38.125 UTC, title: "Standup Notes (for wed)", body: "very full bodied", type: "misc", context: "WORK">
+  ],
+  "search_result_metadata" => {
+          "query"=>query_string, "processingTimeMs"=>1, "limit"=>50,
+          "offset"=>0, "estimatedTotalHits"=>33, "nbHits"=>33
+  }
+}
+#+end_src
+
+If =Note= records shared an index with =Task= and they both had
+=CLASS_PREFIXED_SEARCH_ID=true= you'd get a result like this.
+
+#+begin_src ruby
+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">,
+      #<Note _id: 643f5e1c906b1d60f9763071, created_at: 2023-04-18 00:00:00 UTC, updated_at: 2023-04-19 03:21:00.41 UTC, title: "offline standup ", body: "onother body", type: "misc", context: "WORK">,
+      #<Task _id: 64483e63906b1d84f149717a, created_at: 2023-04-25 00:00:00 UTC, updated_at: 2023-04-26 11:23:38.125 UTC, title: "Do the thing", body: "very full bodied", type: "misc", context: "WORK">
+  ],
+  "search_result_metadata" => {
+          "query"=>query_string, "processingTimeMs"=>1, "limit"=>50,
+          "offset"=>0, "estimatedTotalHits"=>33, "nbHits"=>33
+  }
+  
+}
+#+end_src
+
+*** Custom Search Options
+To invoke any of Meilisearch's custom search options (see
+[[https://www.meilisearch.com/docs/reference/api/search][their
+documentation]]). You can pass them in via an options hash.
+
+=MyModel.search("search term", options: <my custom options>)=
+
+Currently the Meilisearch-ruby gem can convert keys from snake case to
+camel case. For example =hits_per_page= will become =hitsPerPage=.
+Meilisearch ultimately wants camel case (=camelCase=) parameter keys,
+/but/ =meilisearch-ruby= wants snake case (=snake_case=).
+
+Follow Meilisearch's documentation to see what's available and what type
+of options to pass it, but convert them to snake case first. Note that
+your options keys and values must all be simple JSON values.
+
+If for some reason that still isn't enough, you can work with the
+meilisearch-ruby index directly via
+=Search::Client.instance.index(search_index_name)=
+
+**** Pagination
+This gem has no specific pagination handling, as there are multiple
+libraries for handling pagination in Ruby. Here's an example of how to
+get started with [[https://github.com/ddnexus/pagy][Pagy]].
+
+#+begin_src ruby
+current_page_number = 1
+max_items_per_page = 10
+
+search_results = Note.search('foo')
+
+Pagy.new(
+    count: search_results["search_result_metadata"]["nbHits"], 
+    page: current_page_number, 
+    items: max_items_per_page
+)
+#+end_src
+
+** Upgrading
+*** From v1.x
+primary difference between v1.x and v2 is that =mongodb_meilisearch= no longer uses the Meilisearch master key [[https://www.meilisearch.com/docs/learn/security/basic_security][for security reasons]]. The /only/ thing it will use it for is to look up the default search API key and / or the default administrative API key.
+
+It now initializes 2 =Meilisearch::Client= objects: one for searching, one for administration, and all of the internal methods that interact with an index have been rewritten to interact with it via the correct client.
+
+
+Practically speaking, there are 3 significant differences from v1.x
+
+1. =MEILISEARCH_API_KEY= is no longer supported. It has been replaced with the official Meilisearch environment variable for the same purpose: =MEILI_MASTER_KEY=
+2. The master key is only used when an API key for search and / or administration is not provided. It is recommended that you provide =MEILISEARCH_SEARCH_KEY= & =MEILISEARCH_ADMIN_KEY= for those purposes. See "Finding your Search & Admin keys" above for more details.
+3. =Search::Client.instance.client= has been replaced with 2 clients with specific purposes
+   - =Search::Client::instance.search_client=
+   - =Search::Client::instance.admin_client=
+4. =ClassMethods.search_index= has been replaced with
+   - =ClassMethods.searchable_index=
+   - =ClassMethods.administratable_index=
+
+** Development
+To contribute to this gem.
+
+- Run =bundle install= to install all the dependencies.
+- run =lefthook install= to set up
+  [[https://github.com/evilmartians/lefthook][lefthook]] This will do
+  things like make sure the tests still pass, and run rubocop before you
+  commit.
+- Start hacking.
+- Add RSpec tests.
+- Add your name to CONTRIBUTORS.md
+- Make PR.
+
+NOTE: by contributing to this repository you are offering to transfer
+copyright to the current maintainer of the repository.
+
+To install this gem onto your local machine, run
+=bundle exec rake install=. To release a new version, update the version
+number in =version.rb=, and then run =bundle exec rake release=, which
+will create a git tag for the version, push git commits and the created
+tag, and push the =.gem= file to [[https://rubygems.org][rubygems.org]].
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/masukomi/mongodb_meilisearch. This project is
+intended to be a safe, welcoming space for collaboration, and
+contributors are expected to adhere to the
+[[https://github.com/masukomi/mongodb_meilisearch/blob/main/CODE_OF_CONDUCT.md][code of conduct]].
+
+** License
+The gem is available as open source under the terms of the
+[[https://github.com/masukomi/mongodb_meilisearch/blob/main/LICENSE.txt][Server Side Public License]]. For those unfamiliar, the short version is that
+if you use it in a server side app you need to share all the code for
+that app and its infrastructure. It's like AGPL on steroids. Commercial
+licenses are available if you want to use this in a commercial setting
+but not share all your source.
+
+** Code of Conduct
+Everyone interacting in this project's codebases, issue trackers, chat
+rooms and mailing lists is expected to follow the
+[[https://github.com/masukomi/mongodb_meilisearch/blob/main/CODE_OF_CONDUCT.md][code
+of conduct]].
+
+* Footnotes
+[fn:macos] MacOS users I have not found a way to successfully automatically Meilisearch with launchctl (brew services uses this) that allows it to see the ~MEILI_MASTER_KEY~ environment variable. As such, I can /not/ recommend using launchctl for running Meilisearch. Running it without a master key only works in development mode, and introduces complications.
+
+[fn:default_keys] Using the master key you can access the [[https://www.meilisearch.com/docs/reference/api/keys][/keys]] endpoint in Meilisearch to retrieve the default Search & Administrative API keys

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.3.0"
+  VERSION = "2.0.0"
 end