algoliasearch-rails 1.8.1 → 1.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 54a35c426a09e202829b65c9183d2e3708d60f0b
-  data.tar.gz: 28fdaad10e6ae2c0c8dee4df2a2f81df61793664
+  metadata.gz: 936875f8253de8a3c68dd94f553d9db5b333e520
+  data.tar.gz: a8066cbfcb37003ce63683ad9431f7aa7839e089
 SHA512:
-  metadata.gz: 2507961914f1a3b87d09e0a812e6d0f0b49c1a6d49ffc2ea5d36a1dea58cc510aabe13e4b8df511208549aaf368841893d28997394023ae4147d70eaee42c031
-  data.tar.gz: eecad726fd78ef5e6afeea940ccc85abf02a52c7e50f83eb1e187e8636f648eaa0dcd7a2650963dc3d0e3f1941ad65e74a414ac8f0ab25ed3b2c7181b08b28ce
+  metadata.gz: 7393a5f1fe82912c9f322194491fea507eec9362275bde80242ceb464dcc686ebf7f822ed4ac56f2bac7cac6f38959f913b073856882aebe92cd64738fe81f99
+  data.tar.gz: 7d76df4a05fdf8c71dc9aa65ef4e5915becc5ccde12b831163a450ad518c149187d67594573b0e857fa2613d68812705ce57fdc2dcbc2392d7cd2be8f1d18d1e

data/ChangeLog

@@ -1,5 +1,9 @@
 CHANGELOG
 
+2014-02-15  1.8.2
+
+      * Ability to retrieve facets and raw answer as well
+
 2014-02-14  1.8.1
 
       * Fixed backend pagination not taking current page into account at display time.

data/README.md

@@ -19,8 +19,9 @@ Table of Content
 1. [Configuration example](#configuration-example)
 1. [Indexing](#indexing)
 1. [Tags](#tags)
+1. [Search](#search)
+1. [Faceting](#faceting)
 1. [Geo-search](#geo-search)
-1. [Search settings](#search-settings)
 1. [Typeahead UI](#typeahead-ui)
 1. [Note on testing](#note-on-testing)
 
@@ -357,45 +358,97 @@ end
 
 At query time, specify <code>{ tagFilters: 'tagvalue' }</code> or <code>{ tagFilters: ['tagvalue1', 'tagvalue2'] }</code> as search parameters to restrict the result set to specific tags.
 
-Geo-Search
------------
+Search
+----------
 
-Use the <code>geoloc</code> method to localize your record:
+A search returns ORM-compliant objects reloading them from your database. We recommend the usage of our [JavaScript API Client](https://github.com/algolia/algoliasearch-client-js) to perform queries to decrease the overall latency and offload your servers.
+
+
+```ruby
+hits =  Contact.search("jon doe")
+p hits
+p hits.raw_answer # to get the original JSON raw answer
+```
+
+If you want to retrieve the raw JSON answer from the API, without re-loading the objects from the database, you can use:
+
+```ruby
+json_answer = Contact.raw_search("jon doe")
+p json_answer
+p json_answer['hits']
+p json_answer['facets']
+```
+
+Search parameters can be specified either through the index's [settings](https://github.com/algolia/algoliasearch-client-ruby#index-settings) statically in your model or dynamically at search time specifying [search parameters](https://github.com/algolia/algoliasearch-client-ruby#search) as second argument of the ```search``` method:
 
 ```ruby
 class Contact < ActiveRecord::Base
   include AlgoliaSearch
 
   algoliasearch do
-    geoloc :lat_attr, :lng_attr
+    attribute :first_name, :last_name, :email
+    
+    # default search parameters stored in the index settings
+    minWordSizeForApprox1 4
+    minWordSizeForApprox2 8
+    hitsPerPage 42
   end
 end
 ```
 
-At query time, specify <code>{ aroundLatLng: "37.33, -121.89", aroundRadius: 50000 }</code> as search parameters to restrict the result set to 50KM around San Jose.
+```ruby
+# dynamical search parameters
+p Contact.search("jon doe", { :hitsPerPage => 5, :page => 2 })
+```
 
-Search settings
-----------
+Faceting
+---------
 
-All [settings](https://github.com/algolia/algoliasearch-client-ruby#index-settings) can be specified either statically in your model or dynamically at search time using [search options](https://github.com/algolia/algoliasearch-client-ruby#search):
+Facets can be retrieved calling the extra ```facets``` method of the search answer.
 
 ```ruby
 class Contact < ActiveRecord::Base
   include AlgoliaSearch
 
   algoliasearch do
-    attribute :first_name, :last_name, :email
-    minWordSizeForApprox1 2
-    minWordSizeForApprox2 5
-    hitsPerPage 42
+    # [...]
+
+    # specify the list of attributes available for faceting
+    attributesForFaceting [:company, :zip_code]
   end
 end
 ```
 
 ```ruby
-p Contact.search("jon doe", hitsPerPage: 5, page: 2)
+hits = Contact.search("jon doe", { :facets => '*' })
+p hits                    # ORM-compliant array of objects
+p hits.facets             # extra method added to retrieve facets
+p hits.facets['company']  # facet values+count of facet 'company'
+p hits.facets['zip_code'] # facet values+count of facet 'zip_code'
+```
+
+```ruby
+raw_json = Contact.raw_search("jon doe", { :facets => '*' })
+p raw_json['facets']
 ```
 
+Geo-Search
+-----------
+
+Use the <code>geoloc</code> method to localize your record:
+
+```ruby
+class Contact < ActiveRecord::Base
+  include AlgoliaSearch
+
+  algoliasearch do
+    geoloc :lat_attr, :lng_attr
+  end
+end
+```
+
+At query time, specify <code>{ aroundLatLng: "37.33, -121.89", aroundRadius: 50000 }</code> as search parameters to restrict the result set to 50KM around San Jose.
+
 Typeahead UI
 -------------
 

data/algoliasearch-rails.gemspec

@@ -6,7 +6,7 @@
 
 Gem::Specification.new do |s|
   s.name = "algoliasearch-rails"
-  s.version = "1.8.1"
+  s.version = "1.8.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Algolia"]

data/lib/algoliasearch-rails.rb

@@ -205,13 +205,35 @@ module AlgoliaSearch
       @algolia_index = nil
     end
 
-    def algolia_raw_search(q, settings = {})
+    def algolia_raw_search(q, params = {})
       algolia_ensure_init
-      @algolia_index.search(q, Hash[settings.map { |k,v| [k.to_s, v.to_s] }])
+      @algolia_index.search(q, Hash[params.map { |k,v| [k.to_s, v.to_s] }])
     end
 
-    def algolia_search(q, settings = {})
-      json = algolia_raw_search(q, settings)
+    module AdditionalMethods
+      def self.extended(base)
+        class <<base
+          alias_method :raw_answer, :algolia_raw_answer unless method_defined? :raw_answer
+          alias_method :facets, :algolia_facets unless method_defined? :facets
+        end
+      end
+
+      def algolia_raw_answer
+        @algolia_json
+      end
+
+      def algolia_facets
+        @algolia_json['facets']
+      end
+
+      private
+      def algolia_init_raw_answer(json)
+        @algolia_json = json
+      end
+    end
+
+    def algolia_search(q, params = {})
+      json = algolia_raw_search(q, params)
       results = json['hits'].map do |hit|
         o = algolia_options[:type].where(algolia_object_id_method => hit['objectID']).first
         if o
@@ -219,7 +241,10 @@ module AlgoliaSearch
           o
         end
       end.compact
-      AlgoliaSearch::Pagination.create(results, json['nbHits'].to_i, algolia_options.merge({ page: json['page'] + 1 }))
+      res = AlgoliaSearch::Pagination.create(results, json['nbHits'].to_i, algolia_options.merge({ page: json['page'] + 1 }))
+      res.extend(AdditionalMethods)
+      res.send(:algolia_init_raw_answer, json)
+      res
     end
 
     def algolia_index

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: algoliasearch-rails
 version: !ruby/object:Gem::Version
-  version: 1.8.1
+  version: 1.8.2
 platform: ruby
 authors:
 - Algolia