CloudSesame 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b03fae31220d970463fd33113b6a59c9ab0e7954
-  data.tar.gz: 91253e2158baac1a5927f9391c10af5dd2ce3184
+  metadata.gz: a4760f588f53d52c647ac43ab20eb4e2f1fc0cee
+  data.tar.gz: 0ab550a8cdadd3cf77002a4b39c7b556c782a479
 SHA512:
-  metadata.gz: 8167fb00a861a2d9a9fd9796aae670e43dc17d1ec88d895a137935336b32f921d16e3155b44a2d940caa3b723af40d627ac14a797ca125986d3e9287482dd2a4
-  data.tar.gz: 6eb69016ada8ff183a69219284d7ea9408b648182c4b6b15bc00450b09b7a25b591273dec100530d22fa0e0885bd56e0cd862f8f6cc9d0c9f3f089cd70a5e634
+  metadata.gz: 85982cd6bccb2d8a74da708ce5e30000916dab8d8e97bdd23ec77b056e3fa451b2f4e4bfa92bd69f7b5d53092bb12b304245e6bdfe204af667938863796f8d40
+  data.tar.gz: 10c0e7f35306648b13fa936e4baaaf9aefc2d06b220c3dec8aac399b79d6750906c50efa1106921d60a38b02a57a167ebd72f8e68a124f5482065a616bb23588

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    CloudSesame (0.2.1)
+    CloudSesame (0.2.2)
       aws-sdk (~> 2)
 
 GEM

data/README.md

@@ -2,56 +2,251 @@
 Light and Flexible CloudSearch Query Interface
 
 #Install
-* In terminal
-	```gem install CloudSesame```
-* In Gemfile
-	```gem 'CloudSesame```
-
-#Setup 
-
-2. Initalize the gem 
-* Inside the Rails `config/initializers` folder, create a file called `cloud_sesame.rb`
-* In the file, enter in your AWS credentials
+* In terminal type:
+```
+gem install CloudSesame
+```
+* Or add this line to the application in Gemfile:
+```
+gem 'CloudSesame
+```
 
+#Setup AWS Credentials
+*Create a initializer file, example: `config/initializers/cloud_sesame.rb`
 ```
 require 'cloud_sesame'
+
 CloudSesame::Domain::Client.configure do |config|
 	config.access_key = ENV['AWS_ACCESS_KEY_ID']
 	config.secret_key = ENV['AWS_SECRET_ACCESS_KEY']
 end
 ```
+#Usage
+##1. Mix CloudSesame into any class or model
+```
+class Product < ActiveRecord::Base
+	include CloudSesame
+	
+	# call `define_cloudsearch` to setup your CloudSearch config, default size (optional), fields, and scopes (optional)
+	define_cloudsearch do 
+	
+		# REQUIRED: class specific config
+		config.endpoint = ENV['AWS_PRODUCT_SEARCH_ENDPOINT']
+		config.region 	= ENV['AWS_PRODUCT_SEARCH_REGION']
+		
+		# default query size is 10
+		default_size <integer>
+		
+		# turn on sloppy query with distance
+		define_sloppiness 3
+		
+		# turn on fuzzy search
+		define_fuzziness {
+			max_fuzziness <integer> # => maximum fuzziness per word, DEFAULT: 3
+			min_char_size <integer>	# => minimum word size to trigger fuzziness, DEFAULT: 6
+			fuzzy_percent <float>	# => [(word.size * fuzzy_percent).round, max_fuzziness].min, DEFAULT: 0.17
+		}
+		
+		# field config
+		field :product_name,	query: { weight: <integer> }	# => query_options[:fields] = ["product_name^<integer>"]
+		field :description,		query: true						# => query_options[:fields] = ["description"]
+		
+		field :currency,		facet: true				# => enable facet
+		field :discount,	 	facet: { 				# => enable facet with buckets
+			buckets: %w([10,100] [25,100] [50,100] [70,100]), 
+			method: 'interval' 
+		}
+		field :manufacturer,	facet: { size: 50 }		# => enable facet with max size
+		field :category,		facet: { 				# => enable facet with sorting
+			sort: 'bucket', size: 10_000 
+		}
+		
+		field :created_at
+		
+		# scope examples
+		
+		# INPUT: "puma", 
+		# OUPUT: query="shoes", filter_query="(and manufacturer:'puma')"
+		scope :shoes_by_brand, ->(brand = nil) { query("shoes").and { manufacturer brand } if brand }
+		
+		# INPUT: 1
+		# OUPUT: filter_query="(and created_at:{'2016-01-17T00:00:00Z',})"
+		scope :created_in, ->(days = nil) { and { created_at r.gt(Date.today - days) } if days }
+		
+	end
+end
+```
+##2. Inheriting from another class or model
+```
+# Inheriting Definitions from another class
+class ExclusiveProduct < Product
 
-3. Setup your searchable model
-
-* `include CloudSesame`
-* call `define_cloudsearch` to setup your CloudSearch config, default size (optional), fields, and scopes (optional).
-
-```
-class Product
-  include CloudSesame  
-  
-  define_cloudsearch do 
-    config.endpoint = ENV[AWS_ENDPOINT]
-    config.region = END[AWS_REGION]
-    
-    default_size 100  #will default to 10 if not defined
-    
-    field :description, query: true 
-    field :name, query: { weight: 2 }
-    field :currency, facet: true 
-    field :manufacturer, facet: { size: 50 }
-    field :price, facet: { buckets: %w([0, 25], [25, 50], [50, 100]), method: 'interval'}
-    
-    scope :puma_shoes, -> { query("shoes").and { manufacturer "Puma" } } 
-    scope :puma_shoes do 
-      query("shoes").and { manufacturer "Puma" } 
-    end
-
-  end
+	# load previous define cloudsearch definition
+	load_definition_from Product
+	
+	# call define_cloudsearch again to override config 
+	# or map field to a different name
+	define_cloudsearch {
+		field :name, as: :product_name		# => it will use name as product_name's alias, so user can query with
+											# NewProduct.cloudsearch.name("shoes") instead of .product_name("shoes")
+											# but the output will still be filter_query="product_name:'shoes'"
+	}
 end
 ```
 
-4. How to define search fields 
-* to add a field to query_options, set `query: true` 
-* to add a field to query_options with a weight, set `query: { weight: <any integer> }`
-* to add a field to filter_query, set `facet : true`
+##3. Query DSL
+
+###Simple Query
+```
+# Simple Query String
+Product.cloudsearch.query("shoes")				
+# OUTPUT: "shoes"
+
+Product.cloudsearch.query("shoes -puma")			
+# OUTPUT: "shoes -puma"
+
+# With Sloppy Query
+Product.cloudsearch.query("shoes")					
+# OUTPUT: "(shoes|\"shoes\"~3)"
+
+Product.cloudsearch.query("shoes -puma")			
+# OUTPUT: "(shoes -puma|\"shoes -puma\"~3)"
+
+# With Fuzzy Search
+Product.cloudsearch.query("white shoes")			
+# OUTPUT: "(shoes|(white~3+shoes~3))"
+
+Product.cloudsearch.query("white shoes -puma")		
+# OUTPUT: "(shoes -puma|(white~3+shoes~3+-puma))"
+```
+
+###Pagination
+```
+Product.cloudsearch.page(3).size(100)				
+# OUTPUT: { start: 200, size: 100 }
+
+Product.cloudsearch.start(99).size(100)				
+# OUTPUT: { start: 99, size: 100 }
+```
+
+###Sorting
+```
+Product.cloudsearch.sort(name: :desc)				
+# OUTPUT: { sort: "name desc" }
+
+Product.cloudsearch.sort(name: :desc, price: :asc)	
+# OUTPUT: { sort: "name desc,price asc" }
+```
+
+###Return
+```
+Product.cloudsearch.all_fields						
+# OUTPUT: { return: "_all_fields" }
+
+Product.cloudsearch.no_fields						
+# OUTPUT: { return: "_no_fields" }
+
+Product.cloudsearch.score							
+# OUTPUT: { return: "_score" }
+```
+
+###Scope
+```
+Product.coudsearch.shoes_by_brand("puma")			
+# OUTPUT: { query:"shoes" filter_query:"(and manufacturer:'puma')" }
+
+Product.cloudsearch.created_in(7)					
+# OUTPUT: { filter_query:"(and created_at:{Date.today - 7,}) }
+
+Product.cloudsearch.or { 							
+	created_in(7)									
+	discount 25..100							
+}	
+# OUTPUT: { filter_query:"(or (and created_at:{Date.today - 7,}) discount:{25,100] }
+```
+
+###AND & OR Block
+```
+Product.cloudsearch.and { ... }					
+# OUTPUT: "(and ...)"
+
+Product.cloudsearch.and {						
+	or! { ... }									
+	or! { ... }									 
+}
+# OUTPUT: "(and (or ...) (or ...))"
+# NOTE: AND & OR are a ruby syntax, can not be used directly,
+# so aliased them to (and!, all) and (or!, any)
+
+Product.cloudsearch.and.not { ... }				
+# OUTPUT: "(not (and ...))"
+
+Product.cloudsearch.or { and!.not { ...} }		
+# OUTPUT: "(or (not (and ...)))"
+```
+
+###Field Methods
+* field can be set by calling #<field_name> *values
+```
+Product.cloudsearch.name("shoes")				
+# OUTPUT: "name:'shoes'"
+
+Product.cloudsearch.name "shoes", "sneaker"
+# OUTPUT: name:'shoes' name:'sneaker'
+
+Product.cloudsearch.name("shoes").price(100)	
+# OUTPUT: "(and name:'shoes' price:100)"
+
+Product.cloudsearch.and { name "shoes"; price 25..100 }
+# OUTPUT: "(and name:'shoes' price:[25,100])"
+```
+* #not, #prefix (#start_with, #begin_with), #near can be chained after #<field_name> and takes multiple values
+```
+Product.cloudsearch.and { name.not "shoes"; ... }
+# OUTPUT: "(and (not name:'shoes') ...)"
+
+Product.cloudsearch.and { name.start_with "shoes" }
+# OUTPUT: "(and (prefix field='name' 'shoes'))"
+
+Product.cloudsearch.and { name.near "shoes" }
+# OUTPUT: "(and (near field='name' 'shoes'))"
+
+Product.cloudsearch.and { name.not.start_with "shoes" }
+# OUTPUT: "(and (not (near field='name' 'shoes')))"
+
+Product.cloudsearch.and { name(start_with("shoes"), near("puma")).not("nike") }
+# OUTPUT: "(and (prefix field='name' 'shoes') (near field='name' 'puma') (not name:'nike'))"
+```
+* #prefix (#start_with, #begin_with), #near can be called directly to generate a single field value
+```
+Product.cloudsearch.and { name.not start_with("shoes"), near("something") } 
+# OUTPUT: "(not (prefix field='name' 'shoes') (not (near field='name' 'something')))"
+```
+
+###Date, Time and Rage
+* field method accepts Ruby Date and Range Object and will automatically parse them into the CloudSearch format 
+```
+Date.today	=> "'2016-01-18T00:00:00Z'"
+Time.now	=> "'2016-01-18T14:36:57Z'"
+25..100 	=> "[25,100]"
+25...100	=> "[25,100}"
+```
+* use #range or #r for more complicated range, range object accepts Date/Time object as well
+```
+r.gt(100)		=> "{100,}"
+r.gte(100)		=> "[100,}"
+r.lt(100)		=> "{,100}"
+r.lte(100)		=> "{,100]"
+r.gte(100).lt(200)	=> "[100,200}"
+r.gt(Date.today)	=> "{'2016-01-18T00:00:00Z',}"
+```
+
+###Search Related Methods
+* #search  => send off the request, save and returns the response and clear the request
+* #found   => returns the hits found from the response 
+* #results => returns the hits.hit from the response
+* #each    => Calls the given block once for each result, passing that result as a parameter. Returns the results itself.
+* #map     => Creates a new array containing the results returned by the block.
+
+###Other Methods
+* #

data/cloud_sesame.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name        = 'CloudSesame'
-  s.version     = '0.2.1'
+  s.version     = '0.2.2'
   s.date        = '2016-01-14'
   s.summary     = "AWS CloudSearch Query Interface"
   s.description = "AWS CloudSearch Query Interface"

data/lib/cloud_sesame/domain/base.rb

@@ -41,7 +41,7 @@ module CloudSesame
 
 			def define_fuzziness(proc = nil, &block)
 				block = proc unless block_given?
-				context[:query, true][:fuzziness] = Query::Fuzziness.new(&block)
+				context[:query, true][:fuzziness] = Query::Node::Fuzziness.new(&block)
 			end
 
 			def default_scope(proc, &block)

data/lib/cloud_sesame/query/fuzziness.rb

@@ -36,7 +36,7 @@ module CloudSesame
       end
 
       def fuzziness(word)
-        if word.length >= @min_char_size
+        if word.length >= @min_char_size && !excluding_term?(word)
           fuzziness = (word.length * @fuzzy_percent).round
           fuzziness = [fuzziness, @max_fuzziness].min
           "#{word}~#{fuzziness}"
@@ -49,6 +49,10 @@ module CloudSesame
         (args = args.flatten.compact).size > 1 ? "(#{ args.join('+') })" : args[0]
       end
 
+      def excluding_term?(word)
+        !!word.match(/^\-/)
+      end
+
     end
   end
 end

data/lib/cloud_sesame/query/node/fuzziness.rb

@@ -0,0 +1,60 @@
+module CloudSesame
+  module Query
+    module Node
+      class Fuzziness
+
+        def initialize(&block)
+
+          # default fuzziness
+          @max_fuzziness = 3
+          @min_char_size = 6
+          @fuzzy_percent = 0.17
+
+          instance_eval &block if block_given?
+        end
+
+        def max_fuzziness(int)
+          @max_fuzziness = int.to_i
+        end
+
+        def min_char_size(int)
+          @min_char_size = int.to_i
+        end
+
+        def fuzzy_percent(float)
+          @fuzzy_percent = float.to_f
+        end
+
+        def parse(string)
+          result = each_with(string) { |word| fuzziness word }
+          join_by_and result
+        end
+
+        private
+
+        def each_with(string, &block)
+          string.split(' ').map &block
+        end
+
+        def fuzziness(word)
+          if word.length >= @min_char_size && !excluding_term?(word)
+            fuzziness = (word.length * @fuzzy_percent).round
+            fuzziness = [fuzziness, @max_fuzziness].min
+            "#{word}~#{fuzziness}"
+          else
+            word
+          end
+        end
+
+        def join_by_and(*args)
+          (args = args.flatten.compact).size > 1 ? "(#{ args.join('+') })" : args[0]
+        end
+
+        def excluding_term?(word)
+          !!word.match(/^\-/)
+        end
+
+      end
+    end
+  end
+end

data/lib/cloud_sesame/query/node/query.rb

@@ -16,11 +16,11 @@ module CloudSesame
 				private
 
 				def fuzziness
-					context[:fuzziness] ? context[:fuzziness].parse(query) : nil
+					context[:fuzziness] && query && !query.empty? ? context[:fuzziness].parse(query) : nil
 				end
 
 				def sloppiness
-					context[:sloppiness] && query.include?(' ') ? "\"#{ query }\"~#{ context[:sloppiness] }" : nil
+					context[:sloppiness] && query && query.include?(' ') ? "\"#{ query }\"~#{ context[:sloppiness] }" : nil
 				end
 
 				def join_by_or(*args)

data/lib/cloud_sesame/query/node/request.rb

@@ -57,7 +57,7 @@ module CloudSesame
 
 					if compiled[:filter_query].empty?
 						compiled.delete(:filter_query)
-					elsif compiled[:query].empty?
+					elsif compiled[:query].nil? || compiled[:query].empty?
 						convert_to_structured_query(compiled)
 					end
 
@@ -67,7 +67,7 @@ module CloudSesame
 				private
 
 				def convert_to_structured_query(compiled)
-					replace(compiled, :query, :filter_query).merge!(query_parser.structured.compile)
+					replace(compiled, :query, :filter_query).merge! query_parser.structured.compile
 				end
 
 				def replace(hash, key1, key2)

data/lib/cloud_sesame.rb

@@ -31,6 +31,7 @@ require 'cloud_sesame/query/dsl/operator_methods'
 require 'cloud_sesame/query/dsl/scope_methods'
 require 'cloud_sesame/query/dsl/value_methods'
 
+
 # Query Query Filter Query AST Tree
 # ===============================================
 require 'cloud_sesame/query/ast/operator'
@@ -56,6 +57,7 @@ require 'cloud_sesame/query/ast/root'
 require 'cloud_sesame/query/node/abstract'
 require 'cloud_sesame/query/node/request'
 require 'cloud_sesame/query/node/query'
+require 'cloud_sesame/query/node/fuzziness'
 require 'cloud_sesame/query/node/query_options'
 require 'cloud_sesame/query/node/query_options_field'
 require 'cloud_sesame/query/node/query_parser'
@@ -68,7 +70,6 @@ require 'cloud_sesame/query/node/return'
 # Query Builder Interface
 # ===============================================
 require 'cloud_sesame/query/builder'
-require 'cloud_sesame/query/fuzziness'
 
 # Domain Objects
 # ===============================================

data/spec/cloud_sesame_spec.rb

@@ -47,7 +47,7 @@ describe CloudSesame do
 	# 		field :category_string, 		facet: { sort: 'bucket', size: 10_000 }
 	# 		field :created_at
 
-	# 		scope :men_tag, ->(date) { created_at date }
+	# 		scope :shoes_by_brand, ->(brand = nil) { query("shoes").and { manufacturer_name brand }  if brand }
 	# 		scope :and_mens do
 	# 			and! { tags "men"}
 	# 		end
@@ -66,21 +66,25 @@ describe CloudSesame do
 	# end
 
 	# # Example Query
-	# query = Product.cloudsearch.query("children panasonic")
-	# .and {
-	# 	or!(boost: 2) {
-	# 		# tags.not start_with "flash_deal"
-	# 		tags.not.start_with "flash_deal"
-	# 		# tags.near"sales"
-	# 		# tags start_with("flash_deal"), near("sales")
-	# 	}
-	# 	or!.not {
-	# 		currency "CAD", "EUR"
-	# 	}
-	# 	and! {
-	# 		price r.gte(100).lt(200)
-	# 	}
-	# }.created_at(Date.today).description("wasup")
+	# query = Product.cloudsearch.query("shoes").and {
+	# 	searchable_text(start_with("puma")).not("nike")
+	# }
+	# .created_at(Time.now).description("wasup")
+
+	# # .and {
+	# # 	or!(boost: 2) {
+	# # 		# tags.not start_with "flash_deal"
+	# # 		tags.not.start_with "flash_deal"
+	# # 		# tags.near"sales"
+	# # 		# tags start_with("flash_deal"), near("sales")
+	# # 	}
+	# # 	or!.not {
+	# # 		currency "CAD", "EUR"
+	# # 	}
+	# # 	and! {
+	# # 		price r.gte(100).lt(200)
+	# # 	}
+
 
 	# binding.pry
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: CloudSesame
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Scott Chu
@@ -145,6 +145,7 @@ files:
 - lib/cloud_sesame/query/node/abstract.rb
 - lib/cloud_sesame/query/node/facet.rb
 - lib/cloud_sesame/query/node/filter_query.rb
+- lib/cloud_sesame/query/node/fuzziness.rb
 - lib/cloud_sesame/query/node/page.rb
 - lib/cloud_sesame/query/node/query.rb
 - lib/cloud_sesame/query/node/query_options.rb