Class | Ultrasphinx::Search |
In: |
lib/ultrasphinx/search/parser.rb
lib/ultrasphinx/search/internals.rb lib/ultrasphinx/search.rb lib/ultrasphinx/search.rb |
Parent: | Object |
Command-interface Search object.
To set up a search, instantiate an Ultrasphinx::Search object with a hash of parameters. Only the :query key is mandatory.
@search = Ultrasphinx::Search.new( :query => @query, :sort_mode => 'descending', :sort_by => 'created_at' )
Now, to run the query, call its run method. Your results will be available as ActiveRecord instances via the results method. Example:
@search.run @search.results
The query string supports boolean operation, parentheses, phrases, and field-specific search. Query words are stemmed and joined by an implicit AND by default.
A Sphinx::SphinxInternalError will be raised on invalid queries. In general, queries can only be nested to one level.
@query = 'dog OR cat OR "white tigers" NOT (lions OR bears) AND title:animals'
The hash lets you customize internal aspects of the search.
:per_page: | An integer. How many results per page. |
:page: | An integer. Which page of the results to return. |
:class_names: | An array or string. The class name of the model you want to search, an array of model names to search, or nil for all available models. |
:sort_mode: | ‘relevance‘ or ‘ascending‘ or ‘descending‘. How to order the result set. Note that ‘time‘ and ‘extended‘ modes are available, but not tested. |
:sort_by: | A field name. What field to order by for ‘ascending‘ or ‘descending‘ mode. Has no effect for ‘relevance‘. |
:weights: | A hash. Text-field names and associated query weighting. The default weight for every field is 1.0. Example: :weights => {‘title’ => 2.0} |
:filters: | A hash. Names of numeric or date fields and associated values. You can use a single value, an array of values, or a range. (See the bottom of the ActiveRecord::Base page for an example.) |
:facets: | An array of fields for grouping/faceting. You can access the returned facet values and their result counts with the facets method. |
:location: | A hash. Specify the names of your latititude and longitude attributes as declared in your is_indexed calls. To sort the results by distance, set :sort_mode => ‘extended‘ and :sort_by => ‘distance asc’. |
:indexes: | An array of indexes to search. Currently only Ultrasphinx::MAIN_INDEX and Ultrasphinx::DELTA_INDEX are available. Defaults to both; changing this is rarely needed. |
Note that you can set up your own query defaults in environment.rb:
self.class.query_defaults = HashWithIndifferentAccess.new({ :per_page => 10, :sort_mode => 'relevance', :weights => {'title' => 2.0} })
If you pass a :location Hash, distance from the location in meters will be available in your result records via the distance accessor:
@search = Ultrasphinx::Search.new(:class_names => 'Point', :query => 'pizza', :sort_mode => 'extended', :sort_by => 'distance', :location => { :lat => 40.3, :long => -73.6 }) @search.run.first.distance #=> 1402.4
Note that Sphinx expects lat/long to be indexed as radians. If you have degrees in your database, do the conversion in the is_indexed as so:
is_indexed 'fields' => [ 'name', 'description', {:field => 'lat', :function_sql => "RADIANS(?)"}, {:field => 'lng', :function_sql => "RADIANS(?)"} ]
Then, set Ultrasphinx::Search.client_options[:location][:units] = ‘degrees‘.
The MySQL :double column type is recommended for storing location data. For Postgres, use <tt>:float</tt.
Ultrasphinx uses the find_all_by_id method to instantiate records. If you set with_finders: true in Interlock's config/memcached.yml, Interlock overrides find_all_by_id with a caching version.
The Search instance responds to the same methods as a WillPaginate::Collection object, so once you have called run or excerpt you can use it directly in your views:
will_paginate(@search)
You can have Sphinx excerpt and highlight the matched sections in the associated fields. Instead of calling run, call excerpt.
@search.excerpt
The returned models will be frozen and have their field contents temporarily changed to the excerpted and highlighted results.
You need to set the content_methods key on Ultrasphinx::Search.excerpting_options to whatever groups of methods you need the excerpter to try to excerpt. The first responding method in each group for each record will be excerpted. This way Ruby-only methods are supported (for example, a metadata method which combines various model fields, or an aliased field so that the original record contents are still available).
There are some other keys you can set, such as excerpt size, HTML tags to highlight with, and number of words on either side of each excerpt chunk. Example (in environment.rb):
Ultrasphinx::Search.excerpting_options = HashWithIndifferentAccess.new({ :before_match => '<strong>', :after_match => '</strong>', :chunk_separator => "...", :limit => 256, :around => 3, :content_methods => [['title'], ['body', 'description', 'content'], ['metadata']] })
Note that your database is never changed by anything Ultrasphinx does.
SPHINX_CLIENT_PARAMS | = | { 'sort_mode' => { 'relevance' => :relevance, 'descending' => :attr_desc, 'ascending' => :attr_asc, 'time' => :time_segments, 'extended' => :extended, } | Friendly sort mode mappings | |
MODELS_TO_IDS | = | Ultrasphinx.get_models_to_class_ids || {} | ||
IDS_TO_MODELS | = | MODELS_TO_IDS.invert #:nodoc: | ||
MAX_MATCHES | = | DAEMON_SETTINGS["max_matches"].to_i | ||
SPHINX_CLIENT_PARAMS | = | { 'sort_mode' => { 'relevance' => :relevance, 'descending' => :attr_desc, 'ascending' => :attr_asc, 'time' => :time_segments, 'extended' => :extended, } | Friendly sort mode mappings | |
MODELS_TO_IDS | = | Ultrasphinx.get_models_to_class_ids || {} | ||
IDS_TO_MODELS | = | MODELS_TO_IDS.invert #:nodoc: | ||
MAX_MATCHES | = | DAEMON_SETTINGS["max_matches"].to_i |
Builds a new command-interface Search object.
# File lib/ultrasphinx/search.rb, line 298 298: def initialize opts = {} 299: 300: # Change to normal hashes with String keys for speed 301: opts = Hash[HashWithIndifferentAccess.new(opts._deep_dup._coerce_basic_types)] 302: unless self.class.query_defaults.instance_of? Hash 303: self.class.query_defaults = Hash[self.class.query_defaults] 304: self.class.query_defaults['location'] = Hash[self.class.query_defaults['location']] 305: 306: self.class.client_options = Hash[self.class.client_options] 307: self.class.excerpting_options = Hash[self.class.excerpting_options] 308: self.class.excerpting_options['content_methods'].map! {|ary| ary.map {|m| m.to_s}} 309: end 310: 311: # We need an annoying deep merge on the :location parameter 312: opts['location'].reverse_merge!(self.class.query_defaults['location']) if opts['location'] 313: 314: # Merge the rest of the defaults 315: @options = self.class.query_defaults.merge(opts) 316: 317: @options['query'] = @options['query'].to_s 318: @options['class_names'] = Array(@options['class_names']) 319: @options['facets'] = Array(@options['facets']) 320: @options['indexes'] = Array(@options['indexes']).join(" ") 321: 322: raise UsageError, "Weights must be a Hash" unless @options['weights'].is_a? Hash 323: raise UsageError, "Filters must be a Hash" unless @options['filters'].is_a? Hash 324: 325: @options['parsed_query'] = parse(query) 326: 327: @results, @subtotals, @facets, @response = [], {}, {}, {} 328: 329: extra_keys = @options.keys - (self.class.query_defaults.keys + INTERNAL_KEYS) 330: log "discarded invalid keys: #{extra_keys * ', '}" if extra_keys.any? and RAILS_ENV != "test" 331: end
Builds a new command-interface Search object.
# File lib/ultrasphinx/search.rb, line 298 298: def initialize opts = {} 299: 300: # Change to normal hashes with String keys for speed 301: opts = Hash[HashWithIndifferentAccess.new(opts._deep_dup._coerce_basic_types)] 302: unless self.class.query_defaults.instance_of? Hash 303: self.class.query_defaults = Hash[self.class.query_defaults] 304: self.class.query_defaults['location'] = Hash[self.class.query_defaults['location']] 305: 306: self.class.client_options = Hash[self.class.client_options] 307: self.class.excerpting_options = Hash[self.class.excerpting_options] 308: self.class.excerpting_options['content_methods'].map! {|ary| ary.map {|m| m.to_s}} 309: end 310: 311: # We need an annoying deep merge on the :location parameter 312: opts['location'].reverse_merge!(self.class.query_defaults['location']) if opts['location'] 313: 314: # Merge the rest of the defaults 315: @options = self.class.query_defaults.merge(opts) 316: 317: @options['query'] = @options['query'].to_s 318: @options['class_names'] = Array(@options['class_names']) 319: @options['facets'] = Array(@options['facets']) 320: @options['indexes'] = Array(@options['indexes']).join(" ") 321: 322: raise UsageError, "Weights must be a Hash" unless @options['weights'].is_a? Hash 323: raise UsageError, "Filters must be a Hash" unless @options['filters'].is_a? Hash 324: 325: @options['parsed_query'] = parse(query) 326: 327: @results, @subtotals, @facets, @response = [], {}, {}, {} 328: 329: extra_keys = @options.keys - (self.class.query_defaults.keys + INTERNAL_KEYS) 330: log "discarded invalid keys: #{extra_keys * ', '}" if extra_keys.any? and RAILS_ENV != "test" 331: end
Returns the current page number of the result set. (Page indexes begin at 1.)
# File lib/ultrasphinx/search.rb, line 264 264: def current_page 265: @options['page'] 266: end
Returns the current page number of the result set. (Page indexes begin at 1.)
# File lib/ultrasphinx/search.rb, line 264 264: def current_page 265: @options['page'] 266: end
Overwrite the configured content attributes with excerpted and highlighted versions of themselves. Runs run if it hasn‘t already been done.
# File lib/ultrasphinx/search.rb, line 372 372: def excerpt 373: 374: require_run 375: return if results.empty? 376: 377: # See what fields in each result might respond to our excerptable methods 378: results_with_content_methods = results.map do |result| 379: [result, 380: self.class.excerpting_options['content_methods'].map do |methods| 381: methods.detect do |this| 382: result.respond_to? this 383: end 384: end 385: ] 386: end 387: 388: # Fetch the actual field contents 389: docs = results_with_content_methods.map do |result, methods| 390: methods.map do |method| 391: method and strip_bogus_characters(result.send(method).to_s) or "" 392: end 393: end.flatten 394: 395: excerpting_options = { 396: :docs => docs, 397: :index => MAIN_INDEX, # http://www.sphinxsearch.com/forum/view.html?id=100 398: :words => strip_query_commands(parsed_query) 399: } 400: self.class.excerpting_options.except('content_methods').each do |key, value| 401: # Riddle only wants symbols 402: excerpting_options[key.to_sym] ||= value 403: end 404: 405: responses = perform_action_with_retries do 406: # Ship to Sphinx to highlight and excerpt 407: @request.excerpts(excerpting_options) 408: end 409: 410: responses = responses.in_groups_of(self.class.excerpting_options['content_methods'].size) 411: 412: results_with_content_methods.each_with_index do |result_and_methods, i| 413: # Override the individual model accessors with the excerpted data 414: result, methods = result_and_methods 415: methods.each_with_index do |method, j| 416: data = responses[i][j] 417: if method 418: result._metaclass.send('define_method', method) { data } 419: attributes = result.instance_variable_get('@attributes') 420: attributes[method] = data if attributes[method] 421: end 422: end 423: end 424: 425: @results = results_with_content_methods.map do |result_and_content_method| 426: result_and_content_method.first.freeze 427: end 428: 429: self 430: end
Overwrite the configured content attributes with excerpted and highlighted versions of themselves. Runs run if it hasn‘t already been done.
# File lib/ultrasphinx/search.rb, line 372 372: def excerpt 373: 374: require_run 375: return if results.empty? 376: 377: # See what fields in each result might respond to our excerptable methods 378: results_with_content_methods = results.map do |result| 379: [result, 380: self.class.excerpting_options['content_methods'].map do |methods| 381: methods.detect do |this| 382: result.respond_to? this 383: end 384: end 385: ] 386: end 387: 388: # Fetch the actual field contents 389: docs = results_with_content_methods.map do |result, methods| 390: methods.map do |method| 391: method and strip_bogus_characters(result.send(method).to_s) or "" 392: end 393: end.flatten 394: 395: excerpting_options = { 396: :docs => docs, 397: :index => MAIN_INDEX, # http://www.sphinxsearch.com/forum/view.html?id=100 398: :words => strip_query_commands(parsed_query) 399: } 400: self.class.excerpting_options.except('content_methods').each do |key, value| 401: # Riddle only wants symbols 402: excerpting_options[key.to_sym] ||= value 403: end 404: 405: responses = perform_action_with_retries do 406: # Ship to Sphinx to highlight and excerpt 407: @request.excerpts(excerpting_options) 408: end 409: 410: responses = responses.in_groups_of(self.class.excerpting_options['content_methods'].size) 411: 412: results_with_content_methods.each_with_index do |result_and_methods, i| 413: # Override the individual model accessors with the excerpted data 414: result, methods = result_and_methods 415: methods.each_with_index do |method, j| 416: data = responses[i][j] 417: if method 418: result._metaclass.send('define_method', method) { data } 419: attributes = result.instance_variable_get('@attributes') 420: attributes[method] = data if attributes[method] 421: end 422: end 423: end 424: 425: @results = results_with_content_methods.map do |result_and_content_method| 426: result_and_content_method.first.freeze 427: end 428: 429: self 430: end
Delegates enumerable methods to @results, if possible. This allows us to behave directly like a WillPaginate::Collection. Failing that, we delegate to the options hash if a key is set. This lets us use self directly in view helpers.
# File lib/ultrasphinx/search.rb, line 434 434: def method_missing(*args, &block) 435: if @results.respond_to? args.first 436: @results.send(*args, &block) 437: elsif options.has_key? args.first.to_s 438: @options[args.first.to_s] 439: else 440: super 441: end 442: end
Delegates enumerable methods to @results, if possible. This allows us to behave directly like a WillPaginate::Collection. Failing that, we delegate to the options hash if a key is set. This lets us use self directly in view helpers.
# File lib/ultrasphinx/search.rb, line 434 434: def method_missing(*args, &block) 435: if @results.respond_to? args.first 436: @results.send(*args, &block) 437: elsif options.has_key? args.first.to_s 438: @options[args.first.to_s] 439: else 440: super 441: end 442: end
Returns the next page number.
# File lib/ultrasphinx/search.rb, line 288 288: def next_page 289: current_page < page_count ? (current_page + 1) : nil 290: end
Returns the next page number.
# File lib/ultrasphinx/search.rb, line 288 288: def next_page 289: current_page < page_count ? (current_page + 1) : nil 290: end
Returns the global index position of the first result on this page.
# File lib/ultrasphinx/search.rb, line 293 293: def offset 294: (current_page - 1) * per_page 295: end
Returns the global index position of the first result on this page.
# File lib/ultrasphinx/search.rb, line 293 293: def offset 294: (current_page - 1) * per_page 295: end
Returns the last available page number in the result set.
# File lib/ultrasphinx/search.rb, line 274 274: def page_count 275: require_run 276: (total_entries / per_page.to_f).ceil 277: end
Returns the last available page number in the result set.
# File lib/ultrasphinx/search.rb, line 274 274: def page_count 275: require_run 276: (total_entries / per_page.to_f).ceil 277: end
Returns the number of records per page.
# File lib/ultrasphinx/search.rb, line 269 269: def per_page 270: @options['per_page'] 271: end
Returns the number of records per page.
# File lib/ultrasphinx/search.rb, line 269 269: def per_page 270: @options['per_page'] 271: end
Returns the previous page number.
# File lib/ultrasphinx/search.rb, line 283 283: def previous_page 284: current_page > 1 ? (current_page - 1) : nil 285: end
Returns the previous page number.
# File lib/ultrasphinx/search.rb, line 283 283: def previous_page 284: current_page > 1 ? (current_page - 1) : nil 285: end
Returns an array of result objects.
# File lib/ultrasphinx/search.rb, line 219 219: def results 220: require_run 221: @results 222: end
Returns an array of result objects.
# File lib/ultrasphinx/search.rb, line 219 219: def results 220: require_run 221: @results 222: end
Run the search, filling results with an array of ActiveRecord objects. Set the parameter to false if you only want the ids returned.
# File lib/ultrasphinx/search.rb, line 335 335: def run(reify = true) 336: @request = build_request_with_options(@options) 337: 338: log "searching for #{@options.inspect}" 339: 340: perform_action_with_retries do 341: @response = @request.query(parsed_query, @options['indexes']) 342: log "search returned #{total_entries}/#{response[:total_found].to_i} in #{time.to_f} seconds." 343: 344: if self.class.client_options['with_subtotals'] 345: @subtotals = get_subtotals(@request, parsed_query) 346: 347: # If the original query has a filter on this class, we will use its more accurate total rather the facet's 348: # less accurate total. 349: if @options['class_names'].size == 1 350: @subtotals[@options['class_names'].first] = response[:total_found] 351: end 352: 353: end 354: 355: Array(@options['facets']).each do |facet| 356: @facets[facet] = get_facets(@request, parsed_query, facet) 357: end 358: 359: @results = convert_sphinx_ids(response[:matches]) 360: @results = reify_results(@results) if reify 361: 362: say "warning; #{response[:warning]}" if response[:warning] 363: raise UsageError, response[:error] if response[:error] 364: 365: end 366: self 367: end
Run the search, filling results with an array of ActiveRecord objects. Set the parameter to false if you only want the ids returned.
# File lib/ultrasphinx/search.rb, line 335 335: def run(reify = true) 336: @request = build_request_with_options(@options) 337: 338: log "searching for #{@options.inspect}" 339: 340: perform_action_with_retries do 341: @response = @request.query(parsed_query, @options['indexes']) 342: log "search returned #{total_entries}/#{response[:total_found].to_i} in #{time.to_f} seconds." 343: 344: if self.class.client_options['with_subtotals'] 345: @subtotals = get_subtotals(@request, parsed_query) 346: 347: # If the original query has a filter on this class, we will use its more accurate total rather the facet's 348: # less accurate total. 349: if @options['class_names'].size == 1 350: @subtotals[@options['class_names'].first] = response[:total_found] 351: end 352: 353: end 354: 355: Array(@options['facets']).each do |facet| 356: @facets[facet] = get_facets(@request, parsed_query, facet) 357: end 358: 359: @results = convert_sphinx_ids(response[:matches]) 360: @results = reify_results(@results) if reify 361: 362: say "warning; #{response[:warning]}" if response[:warning] 363: raise UsageError, response[:error] if response[:error] 364: 365: end 366: self 367: end
Returns a hash of total result counts, scoped to each available model. Set Ultrasphinx::Search.client_options[:with_subtotals] = true to enable.
The subtotals are implemented as a special type of facet.
# File lib/ultrasphinx/search.rb, line 240 240: def subtotals 241: raise UsageError, "Subtotals are not enabled" unless self.class.client_options['with_subtotals'] 242: require_run 243: @subtotals 244: end
Returns a hash of total result counts, scoped to each available model. Set Ultrasphinx::Search.client_options[:with_subtotals] = true to enable.
The subtotals are implemented as a special type of facet.
# File lib/ultrasphinx/search.rb, line 240 240: def subtotals 241: raise UsageError, "Subtotals are not enabled" unless self.class.client_options['with_subtotals'] 242: require_run 243: @subtotals 244: end
Returns the total result count.
# File lib/ultrasphinx/search.rb, line 247 247: def total_entries 248: require_run 249: [response[:total_found] || 0, MAX_MATCHES].min 250: end