Class: Sunspot::DSL::FieldQuery
- Inherits:
-
Scope
- Object
- Scope
- Sunspot::DSL::FieldQuery
- Defined in:
- sunspot/lib/sunspot/dsl/field_query.rb
Overview
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.
Direct Known Subclasses
Constant Summary
Constants inherited from Scope
Instance Method Summary (collapse)
- - (Object) dynamic(base_name, &block)
-
- (Object) facet(*field_names, &block)
Request a facet on the search query.
-
- (FieldQuery) initialize(search, query, setup)
constructor
:nodoc:.
-
- (Object) order_by(field_name, direction = nil)
Specify the order that results should be returned in.
-
- (Object) order_by_random
DEPRECATED Use order_by(:random).
Methods inherited from Scope
#all_of, #any_of, #text_fields, #with, #without
Constructor Details
- (FieldQuery) initialize(search, query, setup)
:nodoc:
9 10 11 12 |
# File 'sunspot/lib/sunspot/dsl/field_query.rb', line 9 def initialize(search, query, setup) #:nodoc: @search, @query = search, query super(query.scope, setup) end |
Instance Method Details
- (Object) dynamic(base_name, &block)
270 271 272 273 274 275 276 |
# File 'sunspot/lib/sunspot/dsl/field_query.rb', line 270 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 |
- (Object) facet(*field_names, &block)
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) = with(:author_id, 3) facet(:category_id, :exclude => [category_filter, ].compact) end
You should consider using .compact to ensure that the array does not contain any nil values.
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.
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.
Parameters
field_names… | fields for which to return field facets |
Options
:sort | Either :count (values matching the most terms first) or :index (lexical) |
:limit | The maximum number of facet rows to return |
:minimum_count | The minimum count a facet row must have to be returned |
:zeros | Return facet rows for which there are no matches (equivalent to :minimum_count => 0). Default is false. |
:exclude | 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.). Only can be used for field facets that do not use the :extra or :only options. |
:name | 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 | 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. Only applies to field facets. |
:extra | 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. Only applies to field facets. |
179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 |
# File 'sunspot/lib/sunspot/dsl/field_query.rb', line 179 def facet(*field_names, &block) = Sunspot::Util.(field_names) if block if field_names.length != 1 raise( ArgumentError, "wrong number of arguments (#{field_names.length} for 1)" ) end if .has_key?(:exclude) raise( ArgumentError, "can't use :exclude with query facets" ) end search_facet = @search.add_query_facet(field_names.first, ) Sunspot::Util.instance_eval_or_call( QueryFacet.new(@query, @setup, search_facet), &block ) elsif [:only] if .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, ) Util.Array([: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 [: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, ) Sunspot::Query::DateFieldFacet.new(field, ) else search_facet = @search.add_field_facet(field, ) Sunspot::Query::FieldFacet.new(field, ) end @query.add_field_facet(facet) Util.Array([:extra]).each do |extra| if .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 |
- (Object) order_by(field_name, direction = nil)
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 | the field to use for ordering |
direction | :asc or :desc (default :asc) |
22 23 24 25 26 27 28 29 30 31 32 |
# File 'sunspot/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 |
- (Object) order_by_random
DEPRECATED Use order_by(:random)
37 38 39 |
# File 'sunspot/lib/sunspot/dsl/field_query.rb', line 37 def order_by_random order_by(:random) end |