Method: Scrivito::ObjSearchEnumerator#facet

Defined in:: app/cms/scrivito/obj_search_enumerator.rb

Perform a faceted search over up to ten attributes to retrieve structured results for individual values of these attributes.

Applicable to attributes of the following types: string, stringlist, enum, multienum.

Please note that there is a precision limit for faceting: Only the first 50 characters of a string are guaranteed to be considered for faceting. If two string values have the same first 50 characters, they may be grouped into the same facet value.

Please note that by default #facet does not preload the first batch of the search results. In order to reduce the number of search requests, batch_size can be explicitly set using the #batch_size method. This causes Scrivito to preload the first batch of the search results.

Examples:

Faceted request: colors of big balloons:

facets = Balloon.where(:size, :equals, "big").facet("color")

# Big balloons come in 3 colors:
facets.count #=> 3

# There are 3 big red balloons:
red_balloons = facets.first
red_balloons.name #=> "red"
red_balloons.count #=> 3

# There are 2 big green balloons:
green_balloons = facets.second
green_balloons.name #=> "green"
green_balloons.count #=> 2

# There is 1 big blue balloon:
blue_balloons = facets.third
blue_balloons.name #=> "blue"
blue_balloons.count #=> 1

Faceted request with limit: at most 2 colors of big balloons:

facets = Balloon.where(:size, :equals, "big").facet("color", limit: 2)

# Although there are 3 different colors of big balloons,
# only the first 2 colors will be taken into account.
facets.count # => 2

Faceted request with included Objs:

facets = Balloon.where(:size, :equals, "big").facet("color", include_objs: 2)

facets.each do |facet|
  facet.included_objs.each do |obj|
    puts "#{obj.size} #{obj.color} #{obj.class}"
  end
end

# If there are 2 big red balloons, 2 big green balloons and 1 big blue balloon,
# then this will produce:

"big red Balloon"
"big red Balloon"
"big green Balloon"
"big green Balloon"
"big blue Balloon"

Multiple faceting request:

facets = Balloon.where(:size, :equals, "big").facet(
  color: {limit: 3, include_objs: 5},
  motif: {limit: 3, include_objs: 5}
)

color_facet_obj_values = facets[:color]
motif_facet_obj_values = facets[:motif]

color_facet_obj_values.each do |facet|
  facet.included_objs.each do |obj|
    puts "#{obj.size} #{obj.color} #{obj.class}"
  end
end

motif_facet_obj_values.each do |facet|
  facet.included_objs.each do |obj|
    puts "#{obj.size} #{obj.motif} #{obj.class}"
  end
end

# If there are 2 big red balloons, 2 big green balloons and 1 big blue balloon,
# this will produce:

"big red Balloon"
"big red Balloon"
"big green Balloon"
"big green Balloon"
"big blue Balloon"

# If there are 1 big birthday balloon and 1 big wedding balloon,
# this will produce:

"big birthday Balloon"
"big wedding Balloon"

Faceted `where` query with `batch_size`:

big_balloons = Balloon.where(:size, :equals, "big")

# Without preloading
balloon_colors = big_balloons.facet("color")
first_ten_balloons = big_balloons.take(10) # This will cause a search request.

# With preloading
big_balloons.batch_size(10) # Make Scrivito preload the first ten balloons.
balloon_colors = big_balloons.facet("color")
first_ten_balloons = big_balloons.take(10) # This will cause _no_ search request.

Overloads:

#facet(attribute, options = {}) ⇒ Array<Scrivito::ObjFacetValue>

Single-attribute faceting request.
Parameters:
- attribute (String) —
  
  the name of an attribute.
- options (Hash) (defaults to: {}) —
  
  the options to facet a request with.
Options Hash (options):
- :limit (Integer) —
  
  maximum number of unique values to return. Defaults to 10.
- :include_objs (Integer) —
  
  maximum number of Objs to fetch for each unique value. Defaults to 0.
Returns:
- (Array<Scrivito::ObjFacetValue>) —
  
  A list of unique values that were found for the given attribute name. The list is ordered by frequency, i.e. values occurring more frequently come first.
#facet(facets) ⇒ Hash

Multi-attribute faceting request. The maximum number of attributes that may be specified is 10.
Parameters:
- facets (Hash) —
  
  a hash where the keys are attribute names and the values are options. The available options are identical to the options for single faceting requests.
Returns:
- (Hash) —
  
  a hash where the keys are identical to the keys given in the facets parameter. The values of the hash are lists of Scrivito::ObjFacetValue.
Raises:
- (Scrivito::ClientError) —
  
  If the number of attributes exceeds 10.

Raises:

(Scrivito::ClientError) —

If the maximum number of results has been exceeded. The number of results is limited to 100 with respect to the facets themselves and the included Objs.

# File 'app/cms/scrivito/obj_search_enumerator.rb', line 621

def facet(*facet_params)
  search_params = search_dsl_params
  search_params[:size] = 0 unless @preload_batch

  facet_query = FacetQuery.new(facet_params, search_params, workspace)
  facet_query.execute!

  @preloaded_batch = facet_query.batch if @preload_batch

  facet_query.result
end