Class: Scrivito::ObjSearchEnumerator

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/scrivito/obj_search_enumerator.rb,
lib/scrivito/obj_search_enumerator/batch.rb,
lib/scrivito/obj_search_enumerator/facet_query.rb,
lib/scrivito/obj_search_enumerator/batch_iterator.rb,
lib/scrivito/obj_search_enumerator/query_executor.rb

Overview

Provides an enumerator for iterating over the results of searches for CMS objects to retrieve instances of these objects. This is achieved through the Enumerable mixin, which provides methods such as map, select or take.

This enumerator is lazy. If, for example, you are looking for Objs whose object class is Publication, and there are 93 objects in total, then enum.take(10) fetches the first 10 objects only, ignoring the other 83. This implies that repeatedly iterating over this enumerator causes the search results and the objects to be fetched again and again. If you want to get all objects at once, use enum.to_a.

To start searching, use one of the Obj methods that return an ObjSearchEnumerator. The preferred way is to start with Obj.where or Obj.all.

Currently available fields and their values

:*

Searches all fields. This is only possible with the contains and starts_with operators.

:id

Id of an Obj. This is a string field.

:_path

Path of an Obj. This is a string field.

:_name

Name of an Obj. This is a string field.

:_obj_class

Object class of an Obj. This is a string field.

:_permalink

Permalink of an Obj. This is a string field.

:_last_changed

Date of last change to an Obj.

every :custom_attribute

Custom attribute of an Obj. Note that depending on the attribute type (e.g. an html field), some operators cannot be applied.

Meta Data

If an Obj has a binary attribute named blob, the meta data of this attribute is searchable. For a full list of the available meta data attributes, see the documentation of the MetaDataCollection. The meta data attribute name needs to be prefixed with blob: when searching for it. So, for example, when searching for the width, you need to specify the attribute name using blob:width. Binary attributes other than blob are not searchable.

Currently available operators

contains and contains_prefix

These operators are intended for full text search of natural language texts. They are applicable to string, stringlist, enum, multienum and html fields.

For contains and contains_prefix, the examples are based on the following field value: “Behind every cloud is another cloud.”

:contains

Searches for one or more whole words. Each word needs to be present.

Example subquery values:

✔ “behind cloud” (case insensitive)

✘ “behi clo” (not whole words)

✘ “behind everything” (second word does not match)

:contains_prefix

Searches for a word prefix.

Example subquery values:

✔ “Clou” (case insensitive)

✔ “Every” (case insensitive)

equals

The equals operator is intended for programmatic comparisons of string and date values.

The operator has some limits with regard to string length. String values are only guaranteed to be considered if they are at most 1000 characters in length. String values of more than 1000 characters may be ignored by these operators.

For equals, the examples are based on the following field value: “Some content.”

:equals

The field value needs to be identical to the value of this subquery.

Applicable to string, stringlist, enum, multienum and date fields.

Example subquery values:

✔ “Some content.” (exact value)

✘ “Some” (not exact value)

starts_with

The starts_with is intended for programmatic comparions of string values.

The starts_with operator has a precision limit: Only prefixes of up to 20 characters are guaranteed to be matched. If you supply a prefix of more than 20 characters, the additional characters may be ignored.

When combined with the system attribute _path, the operator starts_with has some special functionality: There is not precision limit, i.e. a prefix of arbitrary length may be used to match on _path. Also, prefix matching on _path automatically matches entire path components, i.e. the prefix matching is delimited by slashes (the character ‘/’).

For starts_with, the examples are based on the following field value: “Some content.”

:starts_with

The field value needs to start exactly with the value of this subquery.

Applicable to string, stringlist, enum and multienum fields.

Example subquery values:

✔ “Som” (prefix of the value)

✘ “som” (incorrect case of prefix)

✘ “content” (not prefix of the whole value)

is_less_than and is_greater_than

These operators are intended for comparing date values or numerical metadata, for example the width of an image. It only considers attributes of Objs and not of Widgets. Therefore, Widget attributes are not searchable using the is_less_than and is_greater_than operators.

For is_less_than and is_greater_than, the examples are based on the following date value: Time.new(2000,01,01,00,00,00)

:is_less_than

Matches if the field value is less than the subquery string value.

Example subquery values:

✔ Time.new(1999,12,31,23,59,59) (is less than)

✘ Time.new(2000,01,01,00,00,00) (equal, not less than)

:is_greater_than

Matches if the field value is greater than the subquery string value.

Example subquery values:

✔ Time.new(2000,01,01,00,00,01) (is greater than)

✘ Time.new(2000,01,01,00,00,00) (equal, not greater than)

Matching multienum and stringlist

Attributes of type multienum and stringlist contain an array of strings. Each of these strings is searched individually. A search query matches a multienum or stringlist, if at least one string in the list matches. Example: A query using the operator :equals and the value “Eggs” matches an Obj containing [“Spam”,“Eggs”] in a stringlist or multienum attribute.

Chainable methods collapse

Instance Method Summary collapse

Instance Method Details

#and(field, operator, value, boost = nil) ⇒ Scrivito::ObjSearchEnumerator

Adds the given AND subquery to this Scrivito::ObjSearchEnumerator.

Compares the field(s) with the value(s) using the operator of this subquery. All CMS objects to which this criterion applies remain in the result set.

Parameters:

  • field (Symbol, String, Array<Symbol, String>) —

    Name(s) of the field(s) to be searched. For arrays, the subquery matches if one or more of these fields meet this criterion.

  • operator (Symbol, String) —

    See “Currently available operators” above.

  • value (String, Date, Time, Array<String, Date, Time>) —

    The value(s) to compare with the field value(s) using the operator of this subquery. For arrays, the subquery matches if the condition is met for one or more of the array elements.

  • boost (Hash) (defaults to: nil) —

    A hash where the keys are field names and their values are boosting factors. Boosting factors must be in the range from 1 to 10. Boosting can only be applied to subqueries in which the contains or contains_prefix operator is used.

Returns:



178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 178

def and(field, operator, value, boost = nil)
  real_operator = operator_mapping(operator)
  subquery = {:field => field, :operator => real_operator, :value => convert_value(value)}
  if boost.present?
    valid_boost_operators = [:contains, :contains_prefix]
    if valid_boost_operators.include?(operator.to_sym)
      subquery[:boost] = boost
    else
      raise "Boost is not allowed with operator '#{operator}'. " +
          "Valid operators are: #{valid_boost_operators.join(', ')}"
    end
  end
  reset_for_changed_query
  @query = (query || []) + [subquery]

  self
end

#and_not(field, operator, value) ⇒ Scrivito::ObjSearchEnumerator

Adds the given negated AND subquery to this Scrivito::ObjSearchEnumerator.

Compares the field(s) with the value(s) using the negated operator of this subquery. All CMS objects to which this criterion applies are removed from the result set.

Parameters:

  • field (Symbol, String, Array<Symbol, String>) —

    Name(s) of the field(s) to be searched. For arrays, the subquery matches if one or more of these fields meet this criterion.

  • operator (Symbol, String) —

    Only applicable to subqueries in which the equals, starts_with, is_greater_than or is_less_than operator is used. (See “Currently available operators” above).

  • value (String, Date, Time, Array<String, Date, Time>) —

    The value(s) to compare with the field value(s) using the operator of this subquery. For arrays, the subquery matches if the condition is met for one or more of the array elements.

Returns:



211
212
213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 211

def and_not(field, operator, value)
  real_operator = operator_mapping(operator)
  valid_negated_operators = [:equals, :starts_with, :is_greater_than, :is_less_than]
  unless valid_negated_operators.include?(operator.to_sym)
    raise "Negating operator '#{operator}' is not valid."
  end
  subquery = {:field => field, :operator => real_operator, :value => convert_value(value),
      :negate => true}
  reset_for_changed_query
  @query = (query || []) + [subquery]

  self
end

#batch_size(size) ⇒ Scrivito::ObjSearchEnumerator

Number of search results to be returned by each of the internal search requests.

The default is 10.

Scrivito makes a best effort to return the given number of search results, but may under certain circumstances return larger or smaller batches due to technical reasons.

Parameters:

  • size (Integer) —

    number of search results to be returned by each of the internal search requests. Scrivito tries to honor the requested size as much as possible, but there is no guarantee. At the time of writing, size is capped at 100, for example.

Returns:



289
290
291
292
293
294
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 289

def batch_size(size)
  @batch_size = size
  @preload_batch = true

  self
end

#each {|Obj| ... }

This method returns an undefined value.

Iterates over the search result, yielding Obj.

Yields:



319
320
321
322
323
324
325
326
327
328
329
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 319

def each
  iterator = BatchIterator.new(workspace, search_dsl_params, @preloaded_batch)

  iterator.each do |batch|
    batch.objs.each do |obj|
      yield obj
    end
  end

  @size = iterator.total
end

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

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 20.

    • :include_objs (Integer) —

      number of Objs to fetch for each unique value. Defaults to 0.

    Returns:

  • #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. 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.

    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.



500
501
502
503
504
505
506
507
508
509
510
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 500

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

#load_batch ⇒ Array

Loads a single batch of search results from the backend. Usually returns batch_size results if available, but may occasionally return more or fewer than batch_size results (due to technical reasons). If you need an exact number of hits, use methods from Enumerable, for example take.

Returns:

  • (Array) —

    of Obj.



362
363
364
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 362

def load_batch
  fetch_batch.objs
end

#offset(amount) ⇒ Scrivito::ObjSearchEnumerator

Omits the first amount of Objs from the results. The default is 0.

Parameters:

  • amount (Integer)

Returns:



301
302
303
304
305
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 301

def offset(amount)
  options[:offset] += amount

  self
end

#order(field_name) ⇒ Scrivito::ObjSearchEnumerator #order(field_and_direction) ⇒ Scrivito::ObjSearchEnumerator

Orders the results by field_name.

Applicable to the attribute types string, enum and date.

There is a precision limit when sorting string values: Only the first 50 characters of a string are guaranteed to be considered when sorting search results.

Examples:

Sorting descending

Obj.all.order(_last_changed: :desc)

Overloads:

  • #order(field_name) ⇒ Scrivito::ObjSearchEnumerator

    Parameters:

    • field_name (Symbol, String) —

      This parameter specifies the field by which the hits are sorted (e.g. :_path).

  • #order(field_and_direction) ⇒ Scrivito::ObjSearchEnumerator

    Parameters:

    • field_and_direction (Hash) —

      The field name and sort direction can be specfied as the key and value of a hash. Valid directions are :asc and :desc. The default is :asc.

Returns:



246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 246

def order(field_name)
  field_name, direction = if field_name.is_a?(Hash)
    field_name.to_a.first
  else
    [field_name, :asc]
  end

  options[:sort_by] = field_name
  options[:sort_order] = direction.to_sym

  self
end

#reverse_order ⇒ Scrivito::ObjSearchEnumerator

Deprecated.

This method is deprecated and will be removed in the next major version. Please specify the direction using #order.

Reverses the order of the results. Requires #order to be applied before.

Returns:



264
265
266
267
268
269
270
271
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 264

def reverse_order
  Scrivito::Deprecation.warn_method("reverse_order", "order")
  options[:sort_by].present? or raise "A search order has to be specified"\
      " before reverse_order can be applied."
  options[:sort_order] = options[:sort_order] == :asc ? :desc : :asc

  self
end

#size ⇒ Integer Also known as: length, count

The total number of hits.

This number is an approximation. Scrivito makes a best effort to deliver the exact number of hits. But due to technical reasons, the returned number may differ from the actual number under certain circumstances.

Returns:

  • (Integer) 


339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 339

def size
  return @size if @size

  size_query = {
    query: query,
    size: 0
  }
  if @include_deleted
    size_query[:options] = {
      include_deleted: true
    }
  end

  @size ||= CmsBackend.search_objs(workspace, size_query)['total'].to_i
end