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, contains_prefix, refers_to and links_to 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)

refers_to

The refers_to operator searches for CMS objects in which specific attributes reference specific CMS objects. It works with individual reference or referencelist attributes and with a list of attributes of these types.

So the operator returns the CMS objects in which given attributes of the reference or referencelist type reference the given CMS objects.

Using the “*” wildcard for the attributes to search causes all reference and referencelist attributes of the searched CMS objects to be taken into account.

Note that only attributes directly part of the CMS objects are searched. Currently, attributes contained in widgets are not searched.

:refers_to

Searches for CMS objects referencing given objects by means of specific attributes.

Example subquery values:

✔ myObj (an instance of Obj)

✘ “NameString” (not an instance of Obj)

✘ Time.new(2000,01,01,00,00,00) (not an instance of Obj)

The links_to operator searches for CMS objects containing one or more links pointing to a specific CMS object. So the operator returns the CMS objects in which an html, link, linklist, reference or referencelist attribute links to the CMS object.

The operator can only be applied to all attributes, so the “*” wild card must be specified for the attribute to search.

:links_to

Searches for one or more linked objects.

Example subquery values:

✔ myObj (an instance of Obj)

✘ “NameString” (not an instance of Obj)

✘ Time.new(2000,01,01,00,00,00) (not an instance of Obj)

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:



223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 223

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) —

    Must be one of: equals, starts_with, is_greater_than, is_less_than. (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:



256
257
258
259
260
261
262
263
264
265
266
267
268
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 256

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:



334
335
336
337
338
339
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 334

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:



364
365
366
367
368
369
370
371
372
373
374
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 364

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.



545
546
547
548
549
550
551
552
553
554
555
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 545

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.



407
408
409
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 407

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:



346
347
348
349
350
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 346

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:



291
292
293
294
295
296
297
298
299
300
301
302
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 291

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:



309
310
311
312
313
314
315
316
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 309

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) 


384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
 
# File 'lib/scrivito/obj_search_enumerator.rb', line 384

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