db_text_search 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 874e1b8761af33f55c19c2a67c12dea616a80bc4
-  data.tar.gz: a874ec1e3e6160ef2e5ad01f14020966b43f7cf9
+  metadata.gz: 2c4d97cd16283ff2c47726a56e36fee85c3eb922
+  data.tar.gz: 06b3ca789b57a423f9ffc33840903e8028377263
 SHA512:
-  metadata.gz: 81aae784b663e11355935fe800aefb4a377bbfa2c9adca47114ecc3ff7040cfd53361b2b809655b328b76bd085f04d49535da9b1143b4777789ea4a8394b6cdc
-  data.tar.gz: f6496edfa09ee256d0ef65f95ce87a3a365c3e5095b4f4d62c544bdf7f93c95698bacefe3a4179081ee77dad8f992e6e6f14ede94a11160647d64ae25acd511d
+  metadata.gz: e1ef0f9d45289ed1623f73cded6a2bd3c2f7ad88928364af7b7e94077eb79bcb93c5842c9f772e64b003d5039c64d3028242395d4263ad7574ebdf41e7854231
+  data.tar.gz: 027a5ebcfc61f1d017aee0bd61b66e7327132667085556d60fe3453b92f266093bad59e9f248dde4ec9ff1e6539716a468b3e8805f9a3f8957cf3335c592acb6

data/CHANGES.md

@@ -1,3 +1,7 @@
+## v0.1.2
+
+Tightened the API. Improved documentation.
+
 ## v0.1.1
 
 Initial release.

data/README.md

@@ -81,7 +81,7 @@ DbTextSearch::FullTextSearch.new(Post.published, :content).find(%w(love kaori))
 
 #### MySQL
 
-A `FULLTEXT` index, and a `MATCH AGAINST` query.
+A `FULLTEXT` index, and a `MATCH AGAINST` query. MySQL v5.6.4+ is required.
 
 #### PostgreSQL
 

data/lib/db_text_search/case_insensitive_eq/abstract_adapter.rb

@@ -2,6 +2,8 @@ require 'db_text_search/query_building'
 module DbTextSearch
   class CaseInsensitiveEq
     # A base class for CaseInsensitiveStringFinder adapters.
+    # @abstract
+    # @api private
     class AbstractAdapter
       include ::DbTextSearch::QueryBuilding
 
@@ -25,7 +27,8 @@ module DbTextSearch
       # @param table_name [String, Symbol]
       # @param column_name [String, Symbol]
       # @param options [Hash] passed down to ActiveRecord::ConnectionAdapters::SchemaStatements#add_index.
-      # @return (see ActiveRecord::ConnectionAdapters::SchemaStatements#add_index)
+      # @option options name [String] index name
+      # @option options unique [Boolean] default: false
       # @abstract
       def self.add_index(connection, table_name, column_name, options = {})
         fail 'abstract'

data/lib/db_text_search/case_insensitive_eq/collate_nocase_adapter.rb

@@ -1,25 +1,23 @@
 require 'db_text_search/case_insensitive_eq/abstract_adapter'
 module DbTextSearch
   class CaseInsensitiveEq
+    # Provides case-insensitive string-in-set querying via COLLATE NOCASE.
+    # @api private
     class CollateNocaseAdapter < AbstractAdapter
       # (see AbstractAdapter#find)
       def find(values)
         conn = @scope.connection
-        @scope.where <<-SQL.strip
-          #{quoted_scope_column} COLLATE NOCASE IN (#{values.map { |v| conn.quote(v.to_s) }.join(', ')})
-        SQL
+        @scope.where "#{quoted_scope_column} COLLATE NOCASE IN (#{values.map { |v| conn.quote(v.to_s) }.join(', ')})"
       end
 
       # (see AbstractAdapter.add_index)
       def self.add_index(connection, table_name, column_name, options = {})
         # TODO: Switch to the native Rails solution once it's landed, as the current one requires SQL dump format.
         # https://github.com/rails/rails/pull/18499
-        options.assert_valid_keys(:name, :unique)
-        index_name = options[:name] || options[:name] || "#{column_name}_nocase"
-        connection.exec_query <<-SQL.strip
-          CREATE #{'UNIQUE ' if options[:unique]}INDEX #{index_name} ON #{connection.quote_table_name(table_name)}
-            (#{connection.quote_column_name(column_name)} COLLATE NOCASE);
-        SQL
+        options              = options.dup
+        options[:name]       ||= "#{column_name}_nocase"
+        options[:expression] = "(#{connection.quote_column_name(column_name)} COLLATE NOCASE)"
+        connection.exec_query quoted_create_index(connection, table_name, **options)
       end
     end
   end

data/lib/db_text_search/case_insensitive_eq/insensitive_column_adapter.rb

@@ -1,6 +1,8 @@
 require 'db_text_search/case_insensitive_eq/abstract_adapter'
 module DbTextSearch
   class CaseInsensitiveEq
+    # Provides case-insensitive string-in-set querying for case-insensitive columns.
+    # @api private
     class InsensitiveColumnAdapter < AbstractAdapter
       # (see AbstractAdapter#find)
       def find(values)

data/lib/db_text_search/case_insensitive_eq/lower_adapter.rb

@@ -1,13 +1,13 @@
 require 'db_text_search/case_insensitive_eq/abstract_adapter'
 module DbTextSearch
   class CaseInsensitiveEq
+    # Provides case-insensitive string-in-set querying by applying the database LOWER function.
+    # @api private
     class LowerAdapter < AbstractAdapter
       # (see AbstractAdapter#find)
       def find(values)
         conn = @scope.connection
-        @scope.where <<-SQL.strip
-          LOWER(#{quoted_scope_column}) IN (#{values.map { |v| "LOWER(#{conn.quote(v.to_s)})" }.join(', ')})
-        SQL
+        @scope.where "LOWER(#{quoted_scope_column}) IN (#{values.map { |v| "LOWER(#{conn.quote(v.to_s)})" }.join(', ')})"
       end
 
       # (see AbstractAdapter.add_index)
@@ -15,21 +15,19 @@ module DbTextSearch
         if connection.adapter_name =~ /postgres/i
           # TODO: Switch to native Rails support once it lands.
           # https://github.com/rails/rails/pull/18499
-          index_name = options[:name] || "#{table_name}_#{column_name}_lower"
-          if defined?(SchemaPlus)
-            connection.add_index(table_name, column_name, options.merge(
-                name: index_name, expression: "LOWER(#{connection.quote_column_name(column_name)})"))
+          options              = options.dup
+          options[:name]       ||= "#{table_name}_#{column_name}_lower"
+          options[:expression] = "(LOWER(#{connection.quote_column_name(column_name)}))"
+          if defined?(::SchemaPlus)
+            connection.add_index(table_name, column_name, options)
           else
-            options.assert_valid_keys(:name, :unique)
-            connection.exec_query <<-SQL.strip
-              CREATE #{'UNIQUE ' if options[:unique]}INDEX #{index_name} ON #{connection.quote_table_name(table_name)}
-                (LOWER(#{connection.quote_column_name(column_name)}));
-            SQL
+            connection.exec_query quoted_create_index(connection, table_name, **options)
           end
         elsif connection.adapter_name =~ /mysql/i
-          fail 'MySQL case-insensitive index creation for case-sensitive columns is not supported.'
+          fail ArgumentError.new('MySQL case-insensitive index creation for case-sensitive columns is not supported.')
         else
-          fail "Cannot create a case-insensitive index for case-sensitive column on #{connection.adapter_name}."
+          fail ArgumentError.new(
+              "Cannot create a case-insensitive index for case-sensitive column on #{connection.adapter_name}.")
         end
       end
     end

data/lib/db_text_search/case_insensitive_eq.rb

@@ -5,14 +5,15 @@ require 'db_text_search/case_insensitive_eq/collate_nocase_adapter'
 module DbTextSearch
   # Provides case-insensitive string-in-set querying, and CI index creation.
   class CaseInsensitiveEq
-    # (see AbstractAdapter)
+    # @param scope [ActiveRecord::Relation, Class<ActiveRecord::Base>]
+    # @param column [Symbol] name
     def initialize(scope, column)
       @adapter = self.class.adapter_class(scope.connection, scope.table_name, column).new(scope, column)
       @scope   = scope
     end
 
     # @param value_or_values [String, Array<String>]
-    # @return (see AbstractAdapter#find)
+    # @return [ActiveRecord::Relation]
     def find(value_or_values)
       values = Array(value_or_values)
       return @scope.none if values.empty?
@@ -23,14 +24,14 @@ module DbTextSearch
     # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter]
     # @param table_name [String, Symbol]
     # @param column_name [String, Symbol]
-    # @param options [Hash]
+    # @param options [Hash] passed to ActiveRecord::ConnectionAdapters::SchemaStatements#add_index
     def self.add_ci_text_column(connection, table_name, column_name, options = {})
       case connection.adapter_name.downcase
         when /mysql/
           connection.add_column(table_name, column_name, :text, options)
         when /postgres/
           connection.enable_extension 'citext'
-          if ActiveRecord::VERSION::MAJOR >= 4 && ActiveRecord::VERSION::MINOR >= 2
+          if ActiveRecord::VERSION::STRING >= '4.2.0'
             connection.add_column(table_name, column_name, :citext, options)
           else
             connection.add_column(table_name, column_name, 'CITEXT', options)
@@ -42,11 +43,18 @@ module DbTextSearch
             connection.add_column(table_name, column_name, 'TEXT COLLATE NOCASE', options)
           end
         else
-          fail "Unsupported adapter #{connection.adapter_name}"
+          fail ArgumentError.new("Unsupported adapter #{connection.adapter_name}")
       end
     end
 
-    # (see AbstractAdapter.add_index)
+    # Add an index for case-insensitive string search.
+    #
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter]
+    # @param table_name [String, Symbol]
+    # @param column_name [String, Symbol]
+    # @param options [Hash]
+    # @option options name [String] index name
+    # @option options unique [Boolean] default: false
     def self.add_index(connection, table_name, column_name, options = {})
       adapter_class(connection, table_name, column_name).add_index(connection, table_name, column_name, options)
     end
@@ -55,6 +63,7 @@ module DbTextSearch
     # @param table_name [String, Symbol]
     # @param column_name [String, Symbol]
     # @return [Class<AbstractAdapter>]
+    # @api private
     def self.adapter_class(connection, table_name, column_name)
       if connection.adapter_name.downcase =~ /sqlite/
         # Always use COLLATE NOCASE for SQLite, as we can't check if the column is case-sensitive.
@@ -81,7 +90,7 @@ module DbTextSearch
         when /postgres/
           column.sql_type !~ /citext/i
         else
-          fail "Unsupported adapter #{connection.adapter_name}"
+          fail ArgumentError.new("Unsupported adapter #{connection.adapter_name}")
       end
     end
   end

data/lib/db_text_search/full_text_search/abstract_adapter.rb

@@ -1,9 +1,10 @@
 module DbTextSearch
   class FullTextSearch
     # A base class for FullTextSearch adapters.
+    # @abstract
+    # @api private
     class AbstractAdapter
       include ::DbTextSearch::QueryBuilding
-      DEFAULT_PG_TS_CONFIG = %q('english')
 
       # @param scope [ActiveRecord::Relation, Class<ActiveRecord::Base>]
       # @param column [Symbol] name
@@ -13,17 +14,10 @@ module DbTextSearch
       end
 
       # @param terms [Array<String>]
+      # @param pg_ts_config [String] a pg text search config
       # @return [ActiveRecord::Relation]
-      def find(terms)
-        @scope.where(*where_args(terms))
-      end
-
-      # @param terms [Array<String>]
-      # @param options [Hash]
-      # @option options pg_ts_config [String] a pg text search config. Default: 'english'
-      # @return [query fragment, binds]
       # @abstract
-      def where_args(terms, options = {})
+      def find(terms, pg_ts_config:)
         fail 'abstract'
       end
 
@@ -32,19 +26,12 @@ module DbTextSearch
       # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter]
       # @param table_name [String, Symbol]
       # @param column_name [String, Symbol]
-      # @param options [Hash] passed down to ActiveRecord::ConnectionAdapters::SchemaStatements#add_index.
-      # @return (see ActiveRecord::ConnectionAdapters::SchemaStatements#add_index)
+      # @param name [String, Symbol] index name
+      # @param pg_ts_config [String] for Postgres, the TS config to use; ignored for non-postgres.
       # @abstract
-      def self.add_index(connection, table_name, column_name, options = {})
+      def self.add_index(connection, table_name, column_name, name:, pg_ts_config:)
         fail 'abstract'
       end
-
-      protected
-
-      def parse_search_options(options = {})
-        options.assert_valid_keys(:pg_ts_config)
-        options.reverse_merge(pg_ts_config: DEFAULT_PG_TS_CONFIG)
-      end
     end
   end
 end

data/lib/db_text_search/full_text_search/mysql_adapter.rb

@@ -1,18 +1,21 @@
 require 'db_text_search/full_text_search/abstract_adapter'
 module DbTextSearch
   class FullTextSearch
+    # Provides basic FTS support for MySQL.
+    #
+    # Runs a `MATCH AGAINST` query against a `FULLTEXT` index.
+    #
+    # @note MySQL v5.6.4+ is required.
+    # @api private
     class MysqlAdapter < AbstractAdapter
-      # (see AbstractAdapter#where_args)
-      def where_args(terms, options = {})
-        parse_search_options(options)
-        conn = @scope.connection
-        ["MATCH (#{conn.quote_table_name(@scope.table_name)}.#{conn.quote_column_name(@column)}) AGAINST (?)",
-         terms.uniq.join(' ')]
+      # (see AbstractAdapter#find)
+      def find(terms, pg_ts_config:)
+        @scope.where("MATCH (#{quoted_scope_column}) AGAINST (?)", terms.uniq.join(' '))
       end
 
       # (see AbstractAdapter.add_index)
-      def self.add_index(connection, table_name, column_name, options = {})
-        connection.add_index table_name, column_name, options.merge(type: :fulltext)
+      def self.add_index(connection, table_name, column_name, name:, pg_ts_config:)
+        connection.add_index table_name, column_name, name: name, type: :fulltext
       end
     end
   end

data/lib/db_text_search/full_text_search/postgres_adapter.rb

@@ -1,24 +1,23 @@
 require 'db_text_search/full_text_search/abstract_adapter'
 module DbTextSearch
   class FullTextSearch
+    # Provides basic FTS support for PostgreSQL.
+    #
+    # Runs a `@@ plainto_tsquery` query against a `gist(to_tsvector(...))` index.
+    #
+    # @see DbTextSearch::FullTextSearch::DEFAULT_PG_TS_CONFIG
+    # @api private
     class PostgresAdapter < AbstractAdapter
-      # (see AbstractAdapter#where_args)
-      def where_args(terms, options = {})
-        options      = parse_search_options(options)
-        pg_ts_config = options[:pg_ts_config]
-        ["to_tsvector(#{pg_ts_config}, #{quoted_scope_column}::text) @@ plainto_tsquery(#{pg_ts_config}, ?)",
-         terms.uniq.join(' ')]
+      # (see AbstractAdapter#find)
+      def find(terms, pg_ts_config:)
+        @scope.where("to_tsvector(#{pg_ts_config}, #{quoted_scope_column}) @@ plainto_tsquery(#{pg_ts_config}, ?)",
+                     terms.uniq.join(' '))
       end
 
       # (see AbstractAdapter.add_index)
-      def self.add_index(connection, table_name, column_name, options = {})
-        options.assert_valid_keys(:name, :pg_ts_config)
-        pg_ts_config    = options[:pg_ts_config] || DEFAULT_PG_TS_CONFIG
-        index_name      = options[:name] || "#{table_name}_#{column_name}_fts"
-        connection.exec_query <<-SQL.strip
-          CREATE INDEX #{index_name} ON #{connection.quote_table_name(table_name)}
-            USING gist(to_tsvector(#{pg_ts_config}, #{connection.quote_column_name column_name}))
-        SQL
+      def self.add_index(connection, table_name, column_name, name:, pg_ts_config:)
+        expression = "USING gist(to_tsvector(#{pg_ts_config}, #{connection.quote_column_name column_name}))"
+        connection.exec_query quoted_create_index(connection, table_name, name: name, expression: expression)
       end
     end
   end

data/lib/db_text_search/full_text_search/sqlite_adapter.rb

@@ -1,19 +1,24 @@
 require 'db_text_search/full_text_search/abstract_adapter'
 module DbTextSearch
   class FullTextSearch
+    # Provides very basic FTS support for SQLite.
+    #
+    # Runs a `LIKE %term%` query for each term, joined with `AND`.
+    # Cannot use an index.
+    #
+    # @note .add_index is a no-op.
+    # @api private
     class SqliteAdapter < AbstractAdapter
-      # (see AbstractAdapter.where_args)
-      def where_args(terms, options = {})
-        parse_search_options(options)
+      # (see AbstractAdapter#find)
+      def find(terms, pg_ts_config:)
         quoted_col = quoted_scope_column
-        term_args = terms.map(&:downcase).uniq.map do |term|
-          ["#{quoted_col} COLLATE NOCASE LIKE ?", "%#{sanitize_sql_like term}%"]
+        terms.map(&:downcase).uniq.inject(@scope) do |scope, term|
+          scope.where("#{quoted_col} COLLATE NOCASE LIKE ?", "%#{sanitize_sql_like term}%")
         end
-        [term_args.map(&:first).join(' AND '), *term_args.map(&:second)]
       end
 
       # (see AbstractAdapter.add_index)
-      def self.add_index(connection, table_name, column_name, options = {})
+      def self.add_index(connection, table_name, column_name, name:, pg_ts_config:)
         # A no-op, as we just use LIKE for sqlite.
       end
     end

data/lib/db_text_search/full_text_search.rb

@@ -3,31 +3,45 @@ require 'db_text_search/full_text_search/mysql_adapter'
 require 'db_text_search/full_text_search/sqlite_adapter'
 
 module DbTextSearch
-  # Provides case-insensitive string-in-set querying, and CI index creation.
+  # Provides basic full-text search for a list of terms, and FTS index creation.
   class FullTextSearch
-    # (see AbstractAdapter)
+    # The default Postgres text search config.
+    DEFAULT_PG_TS_CONFIG = %q('english')
+
+    # @param scope [ActiveRecord::Relation, Class<ActiveRecord::Base>]
+    # @param column [Symbol] name
     def initialize(scope, column)
       @adapter = self.class.adapter_class(scope.connection, scope.table_name, column).new(scope, column)
       @scope   = scope
     end
 
     # @param term_or_terms [String, Array<String>]
-    # @return (see AbstractAdapter#find)
-    def find(term_or_terms)
-      values = Array(term_or_terms)
+    # @param pg_ts_config [String] for Postgres, the TS config to use; ignored for non-postgres.
+    # @return [ActiveRecord::Relation]
+    def find(term_or_terms, pg_ts_config: DEFAULT_PG_TS_CONFIG)
+      values  = Array(term_or_terms)
       return @scope.none if values.empty?
-      @adapter.find(values)
+      @adapter.find(values, pg_ts_config: pg_ts_config)
     end
 
-    # (see AbstractAdapter.add_index)
-    def self.add_index(connection, table_name, column_name, options = {})
-      adapter_class(connection, table_name, column_name).add_index(connection, table_name, column_name, options)
+    # Add an index for full text search.
+    #
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter]
+    # @param table_name [String, Symbol]
+    # @param column_name [String, Symbol]
+    # @param name [String, Symbol] index name
+    # @param pg_ts_config [String] for Postgres, the TS config to use; ignored for non-postgres.
+    def self.add_index(connection, table_name, column_name, name: "#{table_name}_#{column_name}_fts",
+        pg_ts_config: DEFAULT_PG_TS_CONFIG)
+      adapter_class(connection, table_name, column_name)
+          .add_index(connection, table_name, column_name, name: name, pg_ts_config: pg_ts_config)
     end
 
     # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter]
     # @param _table_name [String, Symbol]
     # @param _column_name [String, Symbol]
     # @return [Class<AbstractAdapter>]
+    # @api private
     def self.adapter_class(connection, _table_name, _column_name)
       case connection.adapter_name
         when /mysql/i
@@ -37,7 +51,7 @@ module DbTextSearch
         when /sqlite/i
           SqliteAdapter
         else
-          fail "unknown adapter #{connection.adapter_name}"
+          fail ArgumentError.new("Unsupported adapter #{connection.adapter_name}")
       end
     end
   end

data/lib/db_text_search/query_building.rb

@@ -1,22 +1,43 @@
 module DbTextSearch
+  # Common methods for building SQL that use @scope and @column instance variables.
+  # @api private
   module QueryBuilding
+    def self.included(base) # :nodoc:
+      base.extend ClassMethods
+    end
+
     protected
 
+    # @return [String] SQL-quoted scope table name.
     def quoted_scope_table
       @scope.connection.quote_table_name(@scope.table_name)
     end
 
+    # @return [String] SQL-quoted column (without the table name).
     def quoted_column
       @scope.connection.quote_column_name(@column)
     end
 
+    # @return [String] SQL-quoted column fully-qualified with the scope table name.
     def quoted_scope_column
       "#{quoted_scope_table}.#{quoted_column}"
     end
 
+    # @return [String] SQL-quoted string suitable for use in a LIKE statement, with % and _ escaped.
     def sanitize_sql_like(string, escape_character = "\\")
       pattern = Regexp.union(escape_character, '%', '_')
       string.gsub(pattern) { |x| [escape_character, x].join }
     end
+
+    # Common methods for building SQL
+    # @api private
+    module ClassMethods
+      protected
+
+      # @return [String] a CREATE INDEX statement
+      def quoted_create_index(connection, table_name, name:, expression:, unique: false)
+        "CREATE #{'UNIQUE ' if unique}INDEX #{name} ON #{connection.quote_table_name(table_name)} #{expression}"
+      end
+    end
   end
 end

data/lib/db_text_search/version.rb

@@ -1,3 +1,4 @@
 module DbTextSearch
-  VERSION = '0.1.1'
+  # Gem version
+  VERSION = '0.1.2'
 end

data/lib/db_text_search.rb

@@ -5,5 +5,10 @@ require 'db_text_search/version'
 require 'db_text_search/case_insensitive_eq'
 require 'db_text_search/full_text_search'
 
+# DbTextSearch provides a unified interface on top of ActiveRecord for SQLite, MySQL, and PostgreSQL to do:
+# * Case-insensitive string-in-set querying, and CI index creation.
+# * Basic full-text search for a list of terms, and FTS index creation.
+# @see DbTextSearch::CaseInsensitiveEq
+# @see DbTextSearch::FullTextSearch
 module DbTextSearch
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: db_text_search
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Gleb Mazovetskiy
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-03-29 00:00:00.000000000 Z
+date: 2016-03-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -170,3 +170,4 @@ specification_version: 4
 summary: A unified interface on top of ActiveRecord for SQLite, MySQL, and PostgreSQL
   for case-insensitive string search and basic full-text search.
 test_files: []
+has_rdoc: