class Sunspot::DSL::FieldQuery
Provides an API for areas of the query DSL
that operate on specific fields. This functionality is provided by the query DSL
and the dynamic query DSL
.
Public Instance Methods
# File lib/sunspot/dsl/field_query.rb, line 363 def dynamic(base_name, &block) dynamic_field_factory = @setup.dynamic_field_factory(base_name) Sunspot::Util.instance_eval_or_call( FieldQuery.new(@search, @query, dynamic_field_factory), &block ) end
Request a facet on the search query. A facet is a feature of Solr that determines the number of documents that match the existing search and an additional criterion. This allows you to build powerful drill-down interfaces for search, at each step presenting the searcher with a set of refinements that are known to return results.
In Sunspot
, each facet returns zero or more rows, each of which represents a particular criterion conjoined with the actual query being performed. For field facets, each row represents a particular value for a given field. For query facets, each row represents an arbitrary scope; the facet itself is just a means of logically grouping the scopes.
Examples¶ ↑
Field
Facets¶ ↑
A field facet is specified by passing one or more Symbol arguments to this method:
Sunspot.search(Post) do with(:blog_id, 1) facet(:category_id) end
The facet specified above will have a row for each category_id that is present in a document which also has a blog_id of 1.
Multiselect Facets¶ ↑
In certain circumstances, it is beneficial to exclude certain query scopes from a facet; the most common example is multi-select faceting, where the user has selected a certain value, but the facet should still show all options that would be available if they had not:
Sunspot.search(Post) do with(:blog_id, 1) category_filter = with(:category_id, 2) facet(:category_id, :exclude => category_filter) end
Although the results of the above search will be restricted to those with a category_id of 2, the category_id facet will operate as if a category had not been selected, allowing the user to select additional categories (which will presumably be ORed together).
It possible to exclude multiple filters by passing an array:
Sunspot.search(Post) do with(:blog_id, 1) category_filter = with(:category_id, 2) author_filter = with(:author_id, 3) facet(:category_id, :exclude => [category_filter, author_filter].compact) end
You should consider using .compact
to ensure that the array does not contain any nil values.
<strong>As far as I can tell, Solr only supports multi-select with field facets; if :exclude
is passed to a query facet, this method will raise an error. Also, the :only
and :extra
options use query faceting under the hood, so these can't be used with :extra
either. </strong>
Query
Facets¶ ↑
A query facet is a collection of arbitrary scopes, each of which represents a row. This is specified by passing a block into the facet
method; the block then contains one or more row
blocks, each of which creates a query facet row. The row
blocks follow the usual Sunspot
scope DSL
.
For example, a query facet can be used to facet over a set of ranges:
Sunspot.search(Post) do facet(:average_rating) do row(1.0..2.0) do with(:average_rating, 1.0..2.0) end row(2.0..3.0) do with(:average_rating, 2.0..3.0) end row(3.0..4.0) do with(:average_rating, 3.0..4.0) end row(4.0..5.0) do with(:average_rating, 4.0..5.0) end end end
Note that the arguments to the facet
and row
methods simply provide labels for the facet and its rows, so that they can be retrieved and identified from the Search
object. They are not passed to Solr and no semantic meaning is attached to them. The label for facet
should be a symbol; the label for row
can be whatever you'd like.
Range Facets¶ ↑
One can use the Range Faceting feature on any date field or any numeric field that supports range queries. This is particularly useful for the cases in the past where one might stitch together a series of range queries (as facet by query) for things like prices, etc.
For example faceting over average ratings can be done as follows:
Sunspot.search(Post) do facet :average_rating, :range => 1..5, :range_interval => 1 end
Parameters¶ ↑
- field_names…<Symbol>
-
fields for which to return field facets
Options¶ ↑
- :sort<Symbol>
-
Either :count (values matching the most terms first) or :index (lexical)
- :limit<Integer>
-
The maximum number of facet rows to return
- :offset<Integer>
-
The offset from which to start returning facet rows
- :minimum_count<Integer>
-
The minimum count a facet row must have to be returned
- :zeros<Boolean>
-
Return facet rows for which there are no matches (equivalent to :minimum_count => 0). Default is false.
- :exclude<Object,Array>
-
Exclude one or more filters when performing the faceting (see Multiselect Faceting above). The object given for this argument should be the return value(s) of a scoping method (
with
,any_of
,all_of
, etc.). <strong>Only can be used for field facets that do not use the:extra
or:only
options.</strong> - :name<Symbol>
-
Give a custom name to a field facet. The main use case for this option is for requesting the same field facet multiple times, using different filter exclusions (see Multiselect Faceting above). If you pass this option, it is also the argument that should be passed to Search#facet when retrieving the facet result.
- :only<Array>
-
Only return facet rows for the given values. Useful if you are only interested in faceting on a subset of values for a given field. <strong>Only applies to field facets.</strong>
- :extra<Symbol,Array>
-
One or more of :any and :none. :any returns a facet row with a count of all matching documents that have some value for this field. :none returns a facet row with a count of all matching documents that have no value for this field. The facet row(s) corresponding to the extras have a value of the symbol passed. <strong>Only applies to field facets.</strong>
# File lib/sunspot/dsl/field_query.rb, line 242 def facet(*field_names, &block) options = Sunspot::Util.extract_options_from(field_names) if block if field_names.length != 1 raise( ArgumentError, "wrong number of arguments (#{field_names.length} for 1)" ) end search_facet = @search.add_query_facet(field_names.first, options) Sunspot::Util.instance_eval_or_call( QueryFacet.new(@query, @setup, search_facet, options), &block ) elsif options[:only] if options.has_key?(:exclude) raise( ArgumentError, "can't use :exclude with :only (see documentation)" ) end field_names.each do |field_name| field = @setup.field(field_name) search_facet = @search.add_field_facet(field, options) Util.Array(options[:only]).each do |value| facet = Sunspot::Query::QueryFacet.new facet.add_positive_restriction(field, Sunspot::Query::Restriction::EqualTo, value) @query.add_query_facet(facet) search_facet.add_row(value, facet.to_boolean_phrase) end end else field_names.each do |field_name| search_facet = nil field = @setup.field(field_name) facet = if options[:time_range] unless field.type.is_a?(Sunspot::Type::TimeType) raise( ArgumentError, ':time_range can only be specified for Date or Time fields' ) end search_facet = @search.add_date_facet(field, options) Sunspot::Query::DateFieldFacet.new(field, options) elsif options[:range] unless [Sunspot::Type::TimeType, Sunspot::Type::FloatType, Sunspot::Type::IntegerType ].inject(false){|res,type| res || field.type.is_a?(type)} raise( ArgumentError, ':range can only be specified for date or numeric fields' ) end search_facet = @search.add_range_facet(field, options) Sunspot::Query::RangeFacet.new(field, options) else search_facet = @search.add_field_facet(field, options) Sunspot::Query::FieldFacet.new(field, options) end @query.add_field_facet(facet) Util.Array(options[:extra]).each do |extra| if options.has_key?(:exclude) raise( ArgumentError, "can't use :exclude with :extra (see documentation)" ) end extra_facet = Sunspot::Query::QueryFacet.new case extra when :any extra_facet.add_negated_restriction( field, Sunspot::Query::Restriction::EqualTo, nil ) when :none extra_facet.add_positive_restriction( field, Sunspot::Query::Restriction::EqualTo, nil ) else raise( ArgumentError, "Allowed values for :extra are :any and :none" ) end search_facet.add_row(extra, extra_facet.to_boolean_phrase) @query.add_query_facet(extra_facet) end end end end
Specify a field for result grouping. Grouping groups documents with a common field value, return only the top document per group.
More information in the Solr documentation: <wiki.apache.org/solr/FieldCollapsing>
Parameters¶ ↑
- field_names…<Symbol>
-
the fields to use for grouping
# File lib/sunspot/dsl/field_query.rb, line 72 def group(*field_names, &block) group = Sunspot::Query::Group.new() field_names.each do |field_name| field = @setup.field(field_name) group.add_field(field) end if block dsl = Group.new(@setup, group) Sunspot::Util.instance_eval_or_call(dsl, &block) end @query.add_group(group) @search.add_group(group) end
# File lib/sunspot/dsl/field_query.rb, line 336 def json_facet(*field_names) options = Sunspot::Util.extract_options_from(field_names) field_names.each do |field_name| field = @setup.field(field_name) facet = Sunspot::Util.parse_json_facet(field_name, options, @setup) @search.add_json_facet(field, options) @query.add_query_facet(facet) end end
Specify the order that results should be returned in. This method can be called multiple times; precedence will be in the order given.
Parameters¶ ↑
- field_name<Symbol>
-
the field to use for ordering
- direction<Symbol>
-
:asc or :desc (default :asc)
# File lib/sunspot/dsl/field_query.rb, line 22 def order_by(field_name, direction = nil) sort = if special = Sunspot::Query::Sort.special(field_name) special.new(direction) else Sunspot::Query::Sort::FieldSort.new( @setup.field(field_name), direction ) end @query.add_sort(sort) end
Specify that results should be ordered based on a FunctionQuery - wiki.apache.org/solr/FunctionQuery Solr 3.1 and up
For example, to order by field1 + (field2*field3): order_by_function :sum, :field1, [:product, :field2, :field3], :desc
Parameters¶ ↑
- function_name<Symbol>
-
the function to run
- arguments
-
the arguments for this function.
-
Symbol for a field or function name
-
Array for a nested function
-
String for a literal constant
-
- direction<Symbol>
-
:asc or :desc
# File lib/sunspot/dsl/field_query.rb, line 389 def order_by_function(*args) @query.add_sort( Sunspot::Query::Sort::FunctionSort.new(@setup,args) ) end
Specify that the results should be ordered based on their distance from a given point.
Parameters¶ ↑
- field_name<Symbol>
-
the field that stores the location (declared as `latlon`)
- lat<Numeric>
-
the reference latitude
- lon<Numeric>
-
the reference longitude
- direction<Symbol>
-
:asc or :desc (default :asc)
# File lib/sunspot/dsl/field_query.rb, line 49 def order_by_geodist(field_name, lat, lon, direction = nil) @query.add_sort( Sunspot::Query::Sort::GeodistSort.new(@setup.field(field_name), lat, lon, direction) ) end
DEPRECATED Use order_by(:random)
# File lib/sunspot/dsl/field_query.rb, line 58 def order_by_random order_by(:random) end
# File lib/sunspot/dsl/field_query.rb, line 347 def stats(*field_names, &block) options = Sunspot::Util.extract_options_from(field_names) field_names.each do |field_name| field = @setup.field(field_name) query_stats = @query.add_stats( Sunspot::Query::FieldStats.new(field, options) ) search_stats = @search.add_field_stats(field) Sunspot::Util.instance_eval_or_call( FieldStats.new(query_stats, @setup, search_stats), &block) if block end end