cloudsearchable 0.0.2 → 0.0.3

data/README.md

@@ -14,12 +14,6 @@ class Customer
   
   # This is the default index. You probably only need one.
   index_in_cloudsearch do |idx|
-    literal :id,          :searchable => true
-  end
-
-  # A named index.
-  index_in_cloudsearch :test_index do |idx|
-  
     # Fetch the customer_id field from customer
     literal :customer_id, :returnable => true,  :searchable => true, :source => Proc.new { customer }
 
@@ -29,6 +23,11 @@ class Customer
     # uint fields can be used in result ranking functions
     uint    :helpfulness, :returnable => true,  :searchable => false do; 1234 end
   end
+
+  # A named index.
+  index_in_cloudsearch :test_index do |idx|
+    literal :id,          :searchable => true
+  end
 end
 ```
 ### 2. Index some objects
@@ -82,6 +81,24 @@ Supported Options
 * config.fatal_warnings - raises WarningInQueryResult exception on warning. Defaults to false.
 * config.logger - a custom logger, defaults to Rails if defined.
 
+### ActiveSupport Notifications
+
+Requests to AWS cloudsearch are instrumented using [ActiveSupport Notifications](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html). To consume these instrumented events register a subscriber in your Application. For example, to register for getting notifications for search requests:
+
+```ruby
+  ActiveSupport::Notifications.subscribe('cloudsearchable.execute_query') do |*args|
+    event = ActiveSupport::Notifications::Event.new(*args)
+    # Your code here ...
+  end
+```
+
+#### Instrumented events:
+
+1. cloudsearchable.execute_query - Instruments search requests
+2. cloudsearchable.post_record - Instruments record addition 
+3. cloudsearchable.delete_record - Instruments record deletion
+4. cloudsearchable.describe_domains - Instruments request for getting domains information
+
 ### Other Features
 
 Cloudsearchable provides access the underlying AWS client objects, such as '''CloudSearch.client''' and '''class.cloudsearch_domains'''. For example here is how to drop domains associated with Customer class:
@@ -97,9 +114,6 @@ Cloudsearchable provides access the underlying AWS client objects, such as '''Cl
 
 See spec tests and source code for more information.
 
-## TODO:
-- use ActiveSupport instrumentation: http://edgeguides.rubyonrails.org/active_support_instrumentation.html#creating-custom-events
-
 ## Credits
 
 * [Logan Bowers](https://github.com/loganb)
@@ -116,4 +130,4 @@ MIT License
 3. Run the tests (`rake spec`)
 4. Commit your changes (`git commit -am 'Add some feature'`)
 5. Push to the branch (`git push origin my-new-feature`)
-6. Create new Pull Request
+6. Create new Pull Request

data/cloudsearchable.gemspec

@@ -46,6 +46,7 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "yard"
   spec.add_dependency 'aws-sdk'
 
   # testing dependencies

data/lib/cloudsearchable.rb

@@ -8,6 +8,7 @@ require 'cloudsearchable/config'
 
 require 'active_support/inflector'
 require 'active_support/core_ext/string'
+require 'active_support/notifications'
 
 module Cloudsearchable
   def self.configure

data/lib/cloudsearchable/domain.rb

@@ -76,19 +76,25 @@ module Cloudsearchable
 
     # Add or replace the CloudSearch document for a particular version of a record
     def post_record record, record_id, version
-      CloudSearch.post_sdf doc_endpoint, addition_sdf(record, record_id, version)
+      ActiveSupport::Notifications.instrument('cloudsearchable.post_record') do
+        CloudSearch.post_sdf doc_endpoint, addition_sdf(record, record_id, version)
+      end
     end
 
     # Delete the CloudSearch document for a particular record (version must be greater than the last version pushed)
     def delete_record record_id, version
-      CloudSearch.post_sdf doc_endpoint, deletion_sdf(record_id, version)
+      ActiveSupport::Notifications.instrument('cloudsearchable.delete_record') do
+        CloudSearch.post_sdf doc_endpoint, deletion_sdf(record_id, version)
+      end
     end
 
     def execute_query(params)
       uri    = URI("http://#{search_endpoint}/#{CloudSearch::API_VERSION}/search")
       uri.query = URI.encode_www_form(params)
       Cloudsearchable.logger.info "CloudSearch execute: #{uri.to_s}"
-      res = Net::HTTP.get_response(uri).body
+      res = ActiveSupport::Notifications.instrument('cloudsearchable.execute_query') do
+        Net::HTTP.get_response(uri).body
+      end
       JSON.parse(res)
     end
 
@@ -124,7 +130,9 @@ module Cloudsearchable
     #
     def cloudsearch_domain(force_reload = false)
       if(force_reload || !@domain)
-        @domain = CloudSearch.client.describe_domains(:domain_names => [name])
+        @domain = ActiveSupport::Notifications.instrument('cloudsearchable.describe_domains') do
+          CloudSearch.client.describe_domains(:domain_names => [name])
+        end
       else
         @domain
       end

data/lib/cloudsearchable/query_chain.rb

@@ -36,6 +36,9 @@ module Cloudsearchable
     #
     #   Collection.search.where(:customer_id, :==, 12345)
     #
+    # The value you provide must be of the same type as the field.  For text and literal
+    # values, provide a string value.  For uint fields, provide a numeric value.
+    #
     # To search for any of several possible values for a field, use the :any operator:
     #
     #   Collection.search.where(:product_group, :any, %w{gl_kitchen gl_grocery})
@@ -52,26 +55,10 @@ module Cloudsearchable
           where(k, :==, v)
         end
       elsif field_or_hash.is_a? Symbol
-        field = field_or_hash
-        @clauses << if op == :within_range
-                      "#{field}:#{value.to_s}"
-                    elsif op == :== || op == :eq
-                      "#{field}:'#{value.to_s}'"
-                    elsif op == :any
-                      '(or ' + value.map { |v| "#{field}:'#{v.to_s}'" }.join(' ') + ')'
-                    elsif op == :!=
-                      "(not #{field}:'#{value.to_s}')"
-                    elsif op == :> && value.is_a?(Integer)
-                      "#{field}:#{value+1}.."
-                    elsif op == :< && value.is_a?(Integer)
-                      "#{field}:..#{value-1}"
-                    elsif op == :>= && value.is_a?(Integer)
-                      "#{field}:#{value}.."
-                    elsif op == :<= && value.is_a?(Integer)
-                      "#{field}:..#{value}"
-                    else
-                      raise "op #{op} is unrecognized"
-                    end
+        if (field = domain.fields[field_or_hash.to_sym]).nil?
+          raise "cannot query on field '#{field_or_hash}' because it is not a member of this index"
+        end
+        @clauses << clause_for(field_or_hash, field.type, op, value)
       else
         raise "field_or_hash must be a Hash or Symbol, not a #{field_or_hash.class}"
       end
@@ -204,7 +191,7 @@ module Cloudsearchable
     def to_q
       raise NoClausesError, "no search terms were specified" if (@clauses.nil? || @clauses.empty?) && (@q.nil? || @q.empty?)
       
-      bq = (@clauses.count > 0) ? "(and #{@clauses.join(' ')})" : @clauses.first
+      bq = (@clauses.count > 1) ? "(and #{@clauses.join(' ')})" : @clauses.first
       {
         q: @q,
         bq: bq,
@@ -214,5 +201,55 @@ module Cloudsearchable
         :'return-fields' => @fields.reduce("") { |s,f| s << f.to_s }
       }
     end
+
+    private
+
+    def clause_for(field, type, op, value)
+      # Operations for which 'value' is not a scalar
+      if op == :any
+        '(or ' + value.map { |v| "#{field}:#{query_clause_value(type, v)}" }.join(' ') + ')'
+      elsif op == :within_range && type == :uint
+        "#{field}:#{value.to_s}"
+      else
+        value = query_clause_value(type, value)
+
+        # Some operations are applicable to all types.
+        case op
+          when :==, :eq
+            "#{field}:#{value}"
+          when :!=
+            "(not #{field}:#{value})"
+          else
+            # Operation-specific, type-specific operations on scalars
+            case type
+              when :uint
+                case op
+                  when :>
+                    "#{field}:#{value+1}.."
+                  when :<
+                    "#{field}:..#{value-1}"
+                  when :>=
+                    "#{field}:#{value}.."
+                  when :<=
+                    "#{field}:..#{value}"
+                  else
+                    raise "op #{op} is unrecognized for value #{value} of type #{type}"
+                end
+              else
+                raise "op #{op} is unrecognized for value #{value} of type #{type}"
+            end
+        end
+      end
+    end
+
+    def query_clause_value(type, value)
+      if type == :uint
+        Integer(value)
+      elsif !value.nil?
+        "'#{value.to_s}'"
+      else
+        raise "Value #{value} cannot be converted to query string on type #{type}"
+      end
+    end
   end
 end

data/lib/cloudsearchable/version.rb

@@ -1,3 +1,3 @@
 module Cloudsearchable
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/spec/cloudsearchable/cloudsearchable_spec.rb

@@ -5,7 +5,7 @@ describe Cloudsearchable do
   let(:clazz){ CloudSearchableSampleClassFactory.call }
 
   it 'can describe an index that returns ids for the class type' do
-    test_index = clazz.cloudsearch_index(:test_index)
+    test_index = clazz.cloudsearch_index
     test_index.should be_kind_of(Cloudsearchable::Domain)
     test_index.fields.should have(4).items #3 explicit + 1 for the id of the object
   end
@@ -33,7 +33,7 @@ describe Cloudsearchable do
     end
 
     it 'supplies the right values to the fields' do
-      test_index = clazz.cloudsearch_index(:test_index)
+      test_index = clazz.cloudsearch_index
       test_index.fields[:test_class_id].value_for(inst).should be(inst.id)
       test_index.fields[:customer_id].value_for(inst).should   be(inst.customer)
       test_index.fields[:test_name].value_for(inst).should     be(inst.name)
@@ -47,7 +47,7 @@ describe Cloudsearchable do
     end
     
     it 'generates a sensible addition sdf document' do
-      sdf = clazz.cloudsearch_index(:test_index).send :addition_sdf, inst, inst.id, inst.lock_version
+      sdf = clazz.cloudsearch_index.send :addition_sdf, inst, inst.id, inst.lock_version
       sdf[:fields][:helpfulness].should be(1234)
     end
   end

data/spec/cloudsearchable/query_chain_spec.rb

@@ -4,26 +4,6 @@ require 'test_classes/cloud_searchable_test_class'
 describe Cloudsearchable::Query do
   let(:clazz){ CloudSearchableSampleClassFactory.call }
 
-  it 'can build a simple search query' do
-    clazz.search.where(:customer_id, :eq, 12345).query.to_q[:bq].should =~ /customer_id:'12345'/
-  end
-
-  it 'chains' do
-    query = clazz.search.where(customer_id: 12345).where(helpfulness: 42).query.to_q[:bq]
-    query.should =~ /customer_id:'12345'/
-    query.should =~ /helpfulness:'42'/
-  end
-
-  it 'can build a query with "not equal to" condition' do
-    query = clazz.search.where(:customer_id, :!=, 1234).query.to_q[:bq].should =~ /\(not customer_id:'1234'\)/
-  end
-
-  it 'can build a query from a hash' do
-    query = clazz.search.where(customer_id: 12345, helpfulness: 42).query.to_q[:bq]
-    query.should =~ /customer_id:'12345'/
-    query.should =~ /helpfulness:'42'/
-  end
-
   it "doesn't build queries without a query term" do
     expect do
       query = clazz.search.limit(10).query.to_q
@@ -31,40 +11,100 @@ describe Cloudsearchable::Query do
   end
 
   describe '#where' do
-    describe 'uint data type' do
-      describe 'within_range' do
-        it 'supports range query with uint fields' do
-          clazz.search.where(:helpfulness, :within_range, "0..#{123}").query.to_q[:bq].should =~ /helpfulness:0..123/
-        end
+    it 'can build a simple search query' do
+      clazz.search.where(:customer_id, :eq, 'A1234').query.to_q[:bq].should =~ /customer_id:'A1234'/
+    end
 
-        it 'supports range query with uint fields using a ruby range' do
-          clazz.search.where(:helpfulness, :within_range, 0..123).query.to_q[:bq].should =~ /helpfulness:0..123/
-        end
+    it 'rejects field names that were not defined in the index' do
+      expect { clazz.search.where(:mispeled_field, :eq, 12345) }.to raise_exception
+    end
+
+    it 'chains' do
+      query = clazz.search.where(customer_id: 'A1234').where(helpfulness: 42).query.to_q[:bq]
+      query.should =~ /customer_id:'A1234'/
+      query.should =~ /helpfulness:42/
+    end
+
+    it 'can build a query with "not equal to" condition' do
+      query = clazz.search.where(:customer_id, :!=, 'A1234').query.to_q[:bq].should =~ /\(not customer_id:'A1234'\)/
+    end
+
+    it 'can build a query from a hash' do
+      query = clazz.search.where(customer_id: 'A1234', helpfulness: 42).query.to_q[:bq]
+      query.should =~ /customer_id:'A1234'/
+      query.should =~ /helpfulness:42/
+    end
+
+    context 'literal data type' do
+      it 'supports equality' do
+        clazz.search.where(:customer_id, :==, 'ABC').query.to_q[:bq].should eq "customer_id:'ABC'"
       end
 
-      describe 'inequalities' do
-        it 'supports greater-than with uint fields' do
-          clazz.search.where(:helpfulness, :>, 123).query.to_q[:bq].should =~ /helpfulness:124../
-        end
+      it 'supports :any' do
+        clazz.search.where(:customer_id, :any, ['ABC', 'DEF']).query.to_q[:bq].should eq "(or customer_id:'ABC' customer_id:'DEF')"
+      end
 
-        it 'supports greater-than-or-equal-to with uint fields' do
-          clazz.search.where(:helpfulness, :>=, 123).query.to_q[:bq].should =~ /helpfulness:123../
-        end
+      it 'accepts a value as an integer' do
+        clazz.search.where(customer_id: 123).query.to_q[:bq].should =~ /customer_id:'123'/
+      end
 
-        it 'supports less-than with uint fields' do
-          clazz.search.where(:helpfulness, :<, 123).query.to_q[:bq].should =~ /helpfulness:..122/
-        end
+      it 'rejects nil value' do
+        expect { clazz.search.where(customer_id: nil) }.to raise_exception
+      end
+    end
+
+    context 'uint data type' do
+      it 'supports range query' do
+        clazz.search.where(:helpfulness, :within_range, "0..#{123}").query.to_q[:bq].should =~ /helpfulness:0..123/
+      end
+
+      it 'supports range query using a ruby range' do
+        clazz.search.where(:helpfulness, :within_range, 0..123).query.to_q[:bq].should =~ /helpfulness:0..123/
+      end
+
+      it 'supports equality' do
+        clazz.search.where(:helpfulness, :==, 123).query.to_q[:bq].should eq 'helpfulness:123'
+      end
+
+      it 'supports not-equality' do
+        clazz.search.where(:helpfulness, :!=, 123).query.to_q[:bq].should eq '(not helpfulness:123)'
+      end
+
+      it 'supports greater-than' do
+        clazz.search.where(:helpfulness, :>, 123).query.to_q[:bq].should =~ /helpfulness:124../
+      end
 
-        it 'supports less-than-or-equal-to with uint fields' do
-          clazz.search.where(:helpfulness, :<=, 123).query.to_q[:bq].should =~ /helpfulness:..123/
+      it 'supports greater-than-or-equal-to' do
+        clazz.search.where(:helpfulness, :>=, 123).query.to_q[:bq].should =~ /helpfulness:123../
+      end
+
+      it 'supports less-than' do
+        clazz.search.where(:helpfulness, :<, 123).query.to_q[:bq].should =~ /helpfulness:..122/
+      end
+
+      it 'supports less-than-or-equal-to' do
+        clazz.search.where(:helpfulness, :<=, 123).query.to_q[:bq].should =~ /helpfulness:..123/
+      end
+
+      it 'supports :any' do
+        clazz.search.where(:helpfulness, :any, [123, 456]).query.to_q[:bq].should eq '(or helpfulness:123 helpfulness:456)'
+      end
+
+      it 'accepts a value as a string' do
+        clazz.search.where(helpfulness: '123').query.to_q[:bq].should =~ /helpfulness:123/
+      end
+
+      [Object.new, nil, '123a'].each do |v|
+        it "rejects value #{v} of type #{v.class}" do
+          expect { clazz.search.where(helpfulness: v) }.to raise_exception
         end
+      end
+    end
 
-        it 'does not permit inequality operators with non-integer fields' do
-          [:>, :>=, :<, :<=].each do |op|
-            ['123', nil, 12.0].each do |value|
-              expect { clazz.search.where(:helpfulness, op, value).query.to_q[:bq] }.to raise_error
-            end
-          end
+    [:>, :>=, :<, :<=].each do |op|
+      [Object.new, nil, '123a'].each do |v|
+        it "does not permit op #{op} on value #{v} of type #{v.class}" do
+          expect { clazz.search.where(:helpfulness, op, v).query.to_q[:bq] }.to raise_error
         end
       end
     end
@@ -72,7 +112,7 @@ describe Cloudsearchable::Query do
 
 
   it 'supports querying for any of several values of a field' do
-    clazz.search.where(:category, :any, %w{big small}).query.to_q[:bq].should include("(or category:'big' category:'small')")
+    clazz.search.where(:test_name, :any, %w{big small}).query.to_q[:bq].should include("(or test_name:'big' test_name:'small')")
   end
 
   it 'supports text method' do
@@ -81,9 +121,9 @@ describe Cloudsearchable::Query do
   end
 
   it 'supports chaining text and where clauses together' do
-    query = clazz.search.text('test').where(:featured, :==, 'f').query
+    query = clazz.search.text('test').where(:helpfulness, :==, 123).query
     query.to_q[:q].should  =~ /test/
-    query.to_q[:bq].should =~ /featured:'f'/
+    query.to_q[:bq].should =~ /helpfulness:123/
   end
 
   it 'supports ordering with a rank expression' do
@@ -123,16 +163,16 @@ describe Cloudsearchable::Query do
                 "found" => 285,
                 "start" => 0,
                 "hit" => [
-                    {"id" => "40bdd5072b6dbae6245fe4ee837d22e3","data" => {"collection_item_id" => ["PCxSz65GIcZTtc0UpRdT-i--w-1365550370"]}},
-                    {"id" => "00af8f5f96aa1db7aff77be5651b3bb1","data" => {"collection_item_id" => ["PCxhksJTLRYnoGXvwZik82Fkw-1365020313"]}},
-                    {"id" => "00b6ac84e3ae402e7698959bf692a53e","data" => {"collection_item_id" => ["PCxs-fIVZnBcTzZ4MtfDguS1A-1365020274"]}},
-                    {"id" => "018fdee653bff74abd12ac30152a2837","data" => {"collection_item_id" => ["PCxmAGHFtAgyqUrgI3HgM_P6Q-1365548349"]}},
-                    {"id" => "01d062d24c389906eea2d16b8193eb56","data" => {"collection_item_id" => ["PCxqjaTmwydKM82NqymbryNfg-1365470479"]}},
-                    {"id" => "01e3ee5d848a30385a4e90eb851b094d","data" => {"collection_item_id" => ["PCxSz65GIcZTtc0UpRdT-i--w-1365550369"]}},
-                    {"id" => "01fca44cc596adb295ca6ee9f9f36499","data" => {"collection_item_id" => ["PCx7XKbKwOVf1VvEWvTl5c1Eg-1365020176"]}},
-                    {"id" => "02b85c9835b5045065ee389954a60c5f","data" => {"collection_item_id" => ["PCxp_xid_WeTfTmb5MySEfxhQ-1365115565"]}},
-                    {"id" => "040c01be434552a1d9e99eef9db87bdd","data" => {"collection_item_id" => ["PCxLOYzA4bCt7-bP6wsZnl-ow-1365020297"]}},
-                    {"id" => "048567c755e30d6d64d757508f1feaa0","data" => {"collection_item_id" => ["PCxJhhnpYkeSKrOxteQo5Jckw-1365115667"]}}
+                    {"id" => "40bdd5072b6dbae6245fe4ee837d22e3","data" => {"test_class_id" => ["PCxSz65GIcZTtc0UpRdT-i--w-1365550370"]}},
+                    {"id" => "00af8f5f96aa1db7aff77be5651b3bb1","data" => {"test_class_id" => ["PCxhksJTLRYnoGXvwZik82Fkw-1365020313"]}},
+                    {"id" => "00b6ac84e3ae402e7698959bf692a53e","data" => {"test_class_id" => ["PCxs-fIVZnBcTzZ4MtfDguS1A-1365020274"]}},
+                    {"id" => "018fdee653bff74abd12ac30152a2837","data" => {"test_class_id" => ["PCxmAGHFtAgyqUrgI3HgM_P6Q-1365548349"]}},
+                    {"id" => "01d062d24c389906eea2d16b8193eb56","data" => {"test_class_id" => ["PCxqjaTmwydKM82NqymbryNfg-1365470479"]}},
+                    {"id" => "01e3ee5d848a30385a4e90eb851b094d","data" => {"test_class_id" => ["PCxSz65GIcZTtc0UpRdT-i--w-1365550369"]}},
+                    {"id" => "01fca44cc596adb295ca6ee9f9f36499","data" => {"test_class_id" => ["PCx7XKbKwOVf1VvEWvTl5c1Eg-1365020176"]}},
+                    {"id" => "02b85c9835b5045065ee389954a60c5f","data" => {"test_class_id" => ["PCxp_xid_WeTfTmb5MySEfxhQ-1365115565"]}},
+                    {"id" => "040c01be434552a1d9e99eef9db87bdd","data" => {"test_class_id" => ["PCxLOYzA4bCt7-bP6wsZnl-ow-1365020297"]}},
+                    {"id" => "048567c755e30d6d64d757508f1feaa0","data" => {"test_class_id" => ["PCxJhhnpYkeSKrOxteQo5Jckw-1365115667"]}}
                 ]
             },
             "info" => {
@@ -161,7 +201,7 @@ describe Cloudsearchable::Query do
 
         q = query
         q.query.instance_variable_set(:@fatal_warnings, false)
-        lambda{ q.to_a }.should_not raise_error(Cloudsearchable::WarningInQueryResult)
+        lambda{ q.to_a }.should_not raise_error
       end
     end
 

data/spec/test_classes/cloud_searchable_test_class.rb

@@ -24,11 +24,6 @@ CloudSearchableSampleClassFactory = Proc.new do
 
     # This is the default index. You probably only need one.
     index_in_cloudsearch do |idx|
-      literal :id,          :searchable => true
-    end
-
-    # A named index.
-    index_in_cloudsearch :test_index do |idx|
       # Fetch the customer_id field from customer
       literal :customer_id, :returnable => true,  :searchable => true, :source => Proc.new { customer }
 
@@ -38,5 +33,10 @@ CloudSearchableSampleClassFactory = Proc.new do
       # uint fields can be used in result ranking functions
       uint    :helpfulness, :returnable => true,  :searchable => false do; 1234 end
     end
+
+    # A named index.
+    index_in_cloudsearch :test_index do |idx|
+      literal :id,          :searchable => true
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cloudsearchable
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-11 00:00:00.000000000 Z
+date: 2013-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -43,6 +43,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: aws-sdk
   requirement: !ruby/object:Gem::Requirement