ObjSearch

An instance of the ObjSearch class represents a search query. It allows iterating the results of searches for CMS objects – made using Obj.where() or Obj.all() – to retrieve individual Obj instances contained in the result set. The returned iterator is lazy, meaning that it only returns as many objects as are actually needed.

Copy
Scrivito.Obj.where("_objClass", "equals", "BlogPost").and("*", "contains", "marketing");

Instance method summary

Additionally, ObjSearch implements the iterable protocol (if available in the current JavaScript environment).

Examples

The following searches for the string "Scrivito" and boosts the "title" and "description" attributes:

Copy
Scrivito.Obj.where("*", "contains", "Scrivito", {
  title: 10,
  description: 5,
});

Find CMS objects linking to the root page through any link or reference attribute:

Copy
Scrivito.Obj.where("*", "linksTo", Scrivito.Obj.root());
Find all CMS objects of the “BlogPost” class that reference an “Author” object via the “author” reference attribute:
Copy
Scrivito.Obj.where("_objClass", "equals", "BlogPost").and("author", "refersTo", Scrivito.getClass("Author"));

Find all CMS objects that have been deleted in a working copy. If set, the value of _modification is one of new, edited, deleted (String):

Copy
Scrivito.Obj.where("_modification", "equals", "deleted");

See the SDK Cheat Sheet for further examples on searching.

Available attributes and their values

  • * – Searches all attributes.
  • id – ID of an Obj. This is a string attribute.
  • _createdAt – The creation date of an Obj. This is a date attribute.
  • _lastChanged – Date of the last change to an Obj. This is a date attribute.
  • _objClass – Object class of an Obj. This is a string attribute.
  • _path – Path of an Obj. This is a string attribute.
  • _permalink – Permalink of an Obj. This is a string attribute.
  • New in 1.6.0_restriction – Restriction of an Obj. null if public, not null if restricted.
  • MetadataCollection – The metadata of binary attributes are searchable. See MetadataCollection for examples.
  • every customAttribute – Custom attribute of an Obj. Note that depending on the attribute type (e.g. html), some operators cannot be applied.

Available operators

contains and containsPrefix

These operators are intended for full-text searches in natural-language texts. They can be applied to string, stringlist, enum, multienum and html attributes.

For contains and containsPrefix, the examples are based on the following attribute 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)

containsPrefix

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 regarding 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 attribute value: "Some content."

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

Applicable to string, stringlist, enum, multienum and date attributes. Example subquery values:

✔ "Some content." (exact value)
✘ "Some" (not exact value)

startsWith

The startsWith operator is intended for programmatic comparisons of string values.

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

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

For starts_with, the examples are based on the following attribute value: "Some content."

The attribute value needs to start exactly with the value given in this subquery.

Applicable to string, stringlist, enum and multienum attributes. Example subquery values:

✔ "Som" (prefix of the value)
✘ "som" (incorrect case of prefix)
✘ "content" (not prefix of the whole value)

isLessThan and isGreaterThan

These operators are intended for comparing date or numerical values. They can also be applied to numerical metadata, for example the width of an image. They only consider attributes of CMS objects, not of widgets. Thus, widget attributes are not searchable using the isLessThan and isGreaterThan operators.

For isLessThan and isGreaterThan, the examples are based on the following date value: new Date(2000, 0, 1, 0, 0, 0)

isLessThan

Matches if the attribute value is less than the subquery date value. Example subquery values:

new Date(1999, 11, 31, 23, 59, 59) (is less than)
new Date(2000, 0, 1, 0, 0, 0) (equal, not less than)

isGreaterThan

Matches if the attribute value is greater than the subquery string value. Example subquery values:

new Date(2000, 0, 1, 0, 0, 1) (is greater than)
new Date(2000, 0, 1, 0, 0, 0) (equal, not greater than)

linksTo

The linksTo operator searches for CMS objects containing one or more attributes linking to specific CMS objects. So the operator returns the CMS objects in which at least one html, link, linklist, reference or referencelist attribute links to specific CMS objects.

The operator can only be applied to all attributes, so the '*' wildcard must be specified for the attributes to search. If you want to search specific reference or referencelist attributes, please use the refersTo operator.

Using null instead of an instance of Obj results in an error.

Note that, in contrast to the refersTo operator, the linksTo operator searches the attributes directly part of the CMS objects as well as the attributes contained in widgets.

Example subquery values:

myObj (an instance of Obj)
[myObj1, myObj2] (an Array of instances of Obj)
null (not an instance of Obj)
"someString" (not an instance of Obj)

refersTo

The refersTo operator searches for CMS objects in which at least one of the specified reference or referencelist attributes refers to specific 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.

Providing null instead of an Obj instance or an array of Obj instances searches for all CMS objects in which none of the specified attributes refer to a CMS object.

Note that, in contrast to the linksTo operator, the refersTo operator only searches attributes directly part of the CMS objects. Currently, attributes contained in widgets are not searched.

Example subquery values:

myObj (an instance of Obj)
[myObj1, myObj2] (an Array of instances of Obj)
null
"someString" (not an instance of Obj)

Matching multienum and stringlist

Attributes of the multienum and stringlist type 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 equals operator and the value "Eggs" matches an Obj containing ["Spam","Eggs"] in a stringlist or multienum attribute.

Limitations

The number of chainable subqueries is limited. The limit depends on the number of values, attributes, and boost parameters requested, as well as the number of words in a free text search.