typesensual 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9231d4598d045c7089f290474867722966f4c4e720cc34a8de0ef960b5ac650a
-  data.tar.gz: 6b9400c0f282f3df2b3bec0f310f453b3383ddd05846894a1390176db60b206e
+  metadata.gz: 16c9d2bb0a45de749680a833abf874d3f42da4190ea66b88e5d1f19a8f2d902c
+  data.tar.gz: d4f9dc200a97e182929b8cdc6fbb48edc1da69e6444137e2f7f670197742fa2a
 SHA512:
-  metadata.gz: 7ebec05f05e05762734582d0b5080844a567002313aff70b4009642da0aeb20874fbe7a12e9b523dcc2f702bf0b98c24342f3f23dcf751582b42399f21542114
-  data.tar.gz: 709890ec4af5c9da8b680910c865d4900d0eae090cd9cc471bfb50c0860e486854cbcb01ee934aac1bfa124da6722771b2154d2a80b7a911416876ff9598257e
+  metadata.gz: 7d3130f6ac4d1b5d2722c4a6020fab73dc6ce1b91b7095e0f91de2d50723a60c5edb5434f651f874182c868a22e4015b12aa0eed097270562bc2bd291640a2af
+  data.tar.gz: c1fc489fab6f2c1fc29f57a0662883115b37b1790a02eab0db6193be53fbf4174de8e464b937f42b54ee2c3098d57abc8dc529f5d081728cb63861c75b302242

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    typesensual (0.1.0)
+    typesensual (0.3.0)
       activesupport (>= 6.1.5)
       paint (>= 2.0.0)
       typesense (>= 0.13.0)
@@ -9,7 +9,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.0.5)
+    activesupport (7.0.7)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
@@ -22,11 +22,11 @@ GEM
     ethon (0.16.0)
       ffi (>= 1.15.0)
     ffi (1.15.5)
-    i18n (1.13.0)
+    i18n (1.14.1)
       concurrent-ruby (~> 1.0)
     json (2.6.3)
-    minitest (5.18.0)
-    oj (3.14.3)
+    minitest (5.19.0)
+    oj (3.16.0)
     paint (2.3.0)
     parallel (1.23.0)
     parser (3.2.2.1)
@@ -79,7 +79,7 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.4)
-    typesense (0.14.1)
+    typesense (0.15.0)
       oj (~> 3.11)
       typhoeus (~> 1.4)
     typhoeus (1.4.0)
@@ -91,8 +91,10 @@ GEM
     yard (0.9.34)
 
 PLATFORMS
+  ruby
   x86_64-darwin-19
   x86_64-darwin-22
+  x86_64-linux
 
 DEPENDENCIES
   commonmarker

data/README.md

@@ -50,6 +50,14 @@ Typesensual.configure do |config|
 end
 ```
 
+Alternatively you can configure with env variables:
+
+```env
+TYPESENSUAL_NODES=http://node1:8108,http://node2:8108,http://node3:8108
+TYPESENSUAL_API_KEY=xyz
+TYPESENSUAL_ENV=test
+```
+
 ### Creating your first index
 
 Once the client is configured, you can create your first index. This is done by creating a subclass
@@ -57,7 +65,7 @@ of `Typesensual::Index` and defining your schema and how to load the data. For e
 following index might be used to index movies from an ActiveRecord model:
 
 ```ruby
-# app/indices/movie_index.rb
+# app/indices/movies_index.rb
 class MoviesIndex < Typesensual::Index
   # The schema of the collection
   schema do
@@ -70,24 +78,7 @@ class MoviesIndex < Typesensual::Index
     field 'genres', type: 'string[]', facet: true
   end
 
-  def index_one(id)
-    movie = Movie.find(id).includes(:genres)
-
-    {
-      id: movie.id,
-      title: movie.title,
-      release_date: {
-        year: movie.release_date.year,
-        month: movie.release_date.month,
-        day: movie.release_date.day
-      },
-      average_rating: movie.average_rating,
-      user_count: movie.user_count,
-      genres: movie.genres.map(&:name)
-    }
-  end
-
-  def index_many(ids)
+  def index(ids)
     Movies.where(id: ids).includes(:genres).find_each do |movie|
       yield {
         id: movie.id,
@@ -106,6 +97,20 @@ class MoviesIndex < Typesensual::Index
 end
 ```
 
+### Integrating with your model
+
+If you use ActiveRecord, there's a set of premade callbacks you can use:
+
+```ruby
+class Movie < ApplicationRecord
+  after_commit MoviesIndex.ar_callbacks, on: %i[create update destroy]
+end
+```
+
+You're free to use these callbacks as-is, or you can use them as a starting point for your own
+integration. They're just calling `MoviesIndex.index_one` and `MoviesIndex.remove_one` under the
+hood, so you can do the same in your own callbacks or outside of ActiveRecord.
+
 ### Loading data into your index
 
 Once you have defined your index, you can load data into it and update the alias to point to the

data/lib/tasks/typesensual.rake

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require 'typesensual/rake_helper'
+
 namespace :typesensual do
   desc 'List typesensual indices and their collections'
   task list: :environment do
-    Typesensual::RakeHelper.list_collections
+    Typesensual::RakeHelper.list
   end
 
   desc 'Update the alias for an index'
@@ -21,4 +23,12 @@ namespace :typesensual do
       model: args[:model]
     )
   end
+
+  desc 'Delete a version of an index'
+  task :drop_version, %i[index version] => :environment do |_, args|
+    Typesensual::RakeHelper.drop_version(
+      index: args[:index],
+      version: args[:version]
+    )
+  end
 end

data/lib/typesensual/callbacks.rb

@@ -2,9 +2,8 @@
 
 class Typesensual
   class Callbacks
-    def initialize(index, should_update: ->(_record) { true })
+    def initialize(index)
       @index = index
-      @should_update = should_update
     end
 
     def after_create_commit(record)
@@ -12,7 +11,7 @@ class Typesensual
     end
 
     def after_update_commit(record)
-      @should_update.call(record) && @index.index_one(record.id)
+      @index.index_one(record.id)
     end
 
     def after_destroy_commit(record)

data/lib/typesensual/collection.rb

@@ -181,9 +181,22 @@ class Typesensual
       typesense_collection.documents[id.to_s].delete
     end
 
+    # Remove multiple documents from typesense based on a filter
+    #
+    # @param filter_by [String] the filter to use to remove documents
+    # @return [void]
+    def remove_many!(filter_by:)
+      typesense_collection.documents.delete(filter_by: filter_by)
+    end
+
+    # Search for documents in typesense
+    #
+    # @param query [String] the query to search for
+    # @param query_by [String] the fields to search by
+    # @return [Search] the search object
     def search(query:, query_by:)
       Search.new(
-        collection: typesense_collection,
+        collection: self,
         query: query,
         query_by: query_by
       )

data/lib/typesensual/config.rb

@@ -2,21 +2,31 @@
 
 class Typesensual
   class Config
-    attr_accessor :nodes, :api_key
-    attr_writer :env, :client
+    attr_writer :env, :client, :nodes, :api_key
 
     def initialize(&block)
       yield self if block
     end
 
     def env
-      @env ||= (defined?(Rails) ? Rails.env : nil)
+      @env ||= ENV.fetch('TYPESENSUAL_ENV', (defined?(Rails) ? Rails.env : nil))
     end
 
     def client
       @client ||= Typesense::Client.new(connection_options)
     end
 
+    def nodes
+      @nodes ||= ENV['TYPESENSUAL_NODES']&.split(',')&.map do |node|
+        node_uri = URI.parse(node)
+        { port: node_uri.port, host: node_uri.host, protocol: node_uri.scheme }
+      end
+    end
+
+    def api_key
+      @api_key ||= ENV.fetch('TYPESENSUAL_API_KEY', nil)
+    end
+
     private
 
     def connection_options

data/lib/typesensual/field.rb

@@ -43,7 +43,7 @@ class Typesensual
     end
 
     def to_h
-      @field.to_h.merge!(
+      @field.to_h.merge(
         'name' => name,
         'locale' => locale
       ).compact!

data/lib/typesensual/index.rb

@@ -21,6 +21,16 @@ class Typesensual
   class Index
     include StateHelpers
 
+    class << self
+      delegate :search, to: :collection
+    end
+
+    def self.inherited(subclass)
+      super
+      # Copy the schema from the parent class to the subclass
+      subclass.instance_variable_set(:@schema, @schema&.dup)
+    end
+
     # Get or set the name for this index
     #
     # @overload index_name(value)
@@ -94,7 +104,9 @@ class Typesensual
     #
     # See {Schema} for more information
     def self.schema(&block)
-      @schema = Typesensual::Schema.new(&block)
+      @schema ||= Typesensual::Schema.new
+      @schema.instance_eval(&block) if block
+      @schema
     end
 
     # Updates the alias to point to the given collection name
@@ -122,28 +134,25 @@ class Typesensual
       update_alias!(collection)
     end
 
-    # The method to implement to index *one* record.
-    #
-    # @return [Hash] the document to upsert in Typesense
-    def index_one(_id); end
-
     def self.index_one(id, collection: self.collection)
-      collection.insert_one!(new.index_one(id))
+      new.index([id]) do |record|
+        collection.insert_one!(record)
+      end
     end
 
     # The method to implement to index *many* records
-    # Unlike {#index_one}, this method should yield successive records to index
+    # This method should yield successive records to index
     #
     # @yield [Hash] a document to upsert in Typesense
-    def index_many(ids)
+    def index(ids)
       ids.each do |id|
-        yield index_one(id)
+        yield({ id: id })
       end
     end
 
     def self.index_many(ids, collection: self.collection, batch_size: 100)
       collection.insert_many!(
-        new.enum_for(:index_many, ids),
+        new.enum_for(:index, ids),
         batch_size: batch_size
       )
     end

data/lib/typesensual/rake_helper.rb

@@ -98,6 +98,25 @@ class Typesensual
           created_at: new_coll.created_at.strftime('%Y-%m-%d %H:%M:%S')
         )
       end
+
+      # Drop a version of an index
+      #
+      # @param index [String] The name of the index to remove a version from
+      # @param version [String] The version to remove
+      # @example
+      #   rake typesensual:drop_version[FooIndex,1]
+      def drop_version(index:, version:, output: $stdout)
+        index = index.safe_constantize
+        collection = index.collection_for(version: version)
+
+        collection.delete!
+
+        output.printf(
+          "==> Dropped version %<version>s of %<index>s\n",
+          version: version,
+          index: index.name
+        )
+      end
     end
   end
 end

data/lib/typesensual/schema.rb

@@ -4,8 +4,21 @@ require 'typesensual/field'
 
 class Typesensual
   class Schema
+    # Duplicate fields from the original
+    def initialize_copy(original)
+      %w[
+        @fields
+        @token_separators
+        @symbols_to_index
+        @default_sorting_field
+        @enable_nested_fields
+      ].each do |var|
+        instance_variable_set(var, original.instance_variable_get(var).dup)
+      end
+    end
+
     def initialize(&block)
-      instance_eval(&block)
+      instance_eval(&block) unless block.nil?
     end
 
     def field(name, type: 'auto', locale: nil, facet: nil, index: nil, optional: nil)

data/lib/typesensual/search/grouped_hit.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+class Typesensual
+  class Search
+    class GroupedHit
+      # {
+      #   "group_key": [
+      #     "420",
+      #     "69"
+      #   ],
+      #   "hits": {
+      #     ...
+      #   },
+      #   "found": 3
+      # }
+      # @param group [Hash] the Typesense hit hash
+      #   * `group_key` [Array<any>] the grouping keys
+      #   * `hits` [Hash] the Hits for the group
+      #   * `found` [Integer] the number of hits in the group
+      def initialize(group)
+        @group = group
+      end
+
+      def count
+        @group['found']
+      end
+
+      def hits
+        @group['hits'].map { |hit| Hit.new(hit) }
+      end
+
+      def group_key
+        @group['group_key']
+      end
+    end
+  end
+end

data/lib/typesensual/search/hit.rb

@@ -19,7 +19,7 @@ class Typesensual
       #   },
       #   "text_match": 130916
       # }
-      # @param collection [Hash] the Typesense hit hash
+      # @param hit [Hash] the Typesense hit hash
       #   * `highlights` [Array<Hash>] the highlights for the hit
       #   * `document` [Hash] the matching document
       #   * `text_match` [Integer] the text matching score

data/lib/typesensual/search/results.rb

@@ -11,6 +11,10 @@ class Typesensual
         @results['hits'].map { |hit| Hit.new(hit) }
       end
 
+      def grouped_hits
+        @results['grouped_hits'].map { |hit| GroupedHit.new(hit) }
+      end
+
       def count
         @results['found']
       end

data/lib/typesensual/search.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 require 'typesensual/search/hit'
+require 'typesensual/search/grouped_hit'
 require 'typesensual/search/results'
 
 class Typesensual
   class Search
+    include StateHelpers
+
     # Initialize a new search object for a collection
     #
     # @param collection [Typesensual::Collection] the Typesensual collection object
@@ -20,6 +23,7 @@ class Typesensual
       @facet_query = []
       @include_fields = []
       @exclude_fields = []
+      @group_by = []
       @params = {}
 
       @collection = collection
@@ -106,6 +110,11 @@ class Typesensual
       self
     end
 
+    def group_by(*fields)
+      @group_by += fields.map(&:to_s)
+      self
+    end
+
     # Set additional parameters to pass to the search
     # @param values [Hash] the parameters to set
     def set(values)
@@ -114,6 +123,7 @@ class Typesensual
     end
 
     # Generate the query document
+    # @return [Hash] the query document
     def query
       {
         collection: @collection.name,
@@ -125,13 +135,59 @@ class Typesensual
         facet_by: @facet_by&.join(','),
         facet_query: @facet_query&.join(','),
         include_fields: @include_fields&.join(','),
-        exclude_fields: @exclude_fields&.join(',')
+        exclude_fields: @exclude_fields&.join(','),
+        group_by: @group_by&.join(',')
       }.merge(@params).reject { |_, v| v.blank? }
     end
 
     # Load the results from the search query
+    # @return [Typesensual::Search::Results] the results of the search
     def load
       Results.new(@collection.typesense_collection.documents.search(query))
     end
+
+    # Perform multiple searches in one request. There are two variants of this method, one which
+    # takes a list of anonymous queries and one which takes a hash of named queries. Named queries
+    # will probably be more readable for more than a couple of queries, but anonymous queries can be
+    # destructured directly.
+    #
+    # Both versions accept either a Search instance or a hash of search parameters.
+    #
+    # @overload multi(*searches)
+    #   Perform an array of search queries in a single request. The return values are guaranteed to
+    #   be in the same order as the provided searches.
+    #
+    #   @param searches [<Typesensual::Search, Hash>] the searches to perform
+    #   @return [<Typesensual::Search::Results>] the results of the searches
+    #
+    # @overload multi(searches)
+    #   Perform multiple named search queries in a single request. The results will be keyed by the
+    #   same names as the provided searches.
+    #
+    #   @param searches [{Object => Typesensual::Search, Hash>] the searches to perform
+    #   @return [{Object => Typesensual::Search::Results}] the results of the searches
+    def self.multi(*searches)
+      # If we have one argument and it's a hash, we're doing named searches
+      if searches.count == 1 && searches.first.is_a?(Hash)
+        keys = searches.first.keys
+        searches = searches.first.values
+      end
+
+      results = client.multi_search.perform({
+        searches: searches.flatten.map(&:query)
+      })
+
+      # Wrap our results in Result objects
+      wrapped_results = results['results'].map do |result|
+        Results.new(result)
+      end
+
+      # If we're doing named searches, re-key the results
+      if keys
+        keys.zip(wrapped_results).to_h
+      else
+        wrapped_results
+      end
+    end
   end
 end

data/lib/typesensual/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Typesensual
-  VERSION = '0.1.0'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: typesensual
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Emma Lejeck
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-07-23 00:00:00.000000000 Z
+date: 2023-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -80,6 +80,7 @@ files:
 - lib/typesensual/rake_helper.rb
 - lib/typesensual/schema.rb
 - lib/typesensual/search.rb
+- lib/typesensual/search/grouped_hit.rb
 - lib/typesensual/search/hit.rb
 - lib/typesensual/search/results.rb
 - lib/typesensual/state_helpers.rb