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.

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

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

When searching specific attributes instead of using the * wildcard for performing a full-text search (see below for details), we recommend to keep the number of attributes to be searched as small as possible. To this end, instead of giving a headline attribute in different object or widget classes different names (title, heading, headline, caption, head, etc.), the same name should be used for all of them. This way, more room is left for longer search terms, more values, or additional subqueries.

Examples

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

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

Searchable attributes

• * – 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.
• _restriction – Restriction of an Obj. null if public, not null if restricted.
• MetadataCollection – The metadata of binary attributes are searchable.
• every customAttribute – Custom attribute of an Obj. Note that depending on the attribute type (e.g. html), some operators cannot be applied.

matches, 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.

The examples are based on the following attribute value: “Behind every cloud is another cloud”.

matches

Searches for text matching the subquery value, with some fuzziness. The subquery value may contain phrases, i.e., sequences of words enclosed in quotation marks. Such phrases must be present in the searched text for it to match. Example subquery values:

✔ “another cloud”
✔ “behind cloud” (words searched for don’t need to be consecutive)
✔ “clo beh” (supports prefix match)
✔ “"every cloud" behind” (“every” and “cloud” are searched for as a phrase)
✘ “"ever cloud"” (phrase doesn’t match)

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 can be applied to attributes of the string, boolean, date, enum, stringlist, and multienum types. The comparison value can be a String, Number, Date or Boolean, or null.

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.

With string, boolean, date and enum attributes, their value needs to be identical to the value searched for. With stringlist and multienum attributes, at least one of their elements must be identical to the value searched for.

Example subquery values for a string attribute whose content is “Some content”:

✔ “Some content” (exact value)
✘ “Some” (not exact value)

startsWith

The startsWith operator is applicable to string, stringlist, enum and multienum attributes. It 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).

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

Example subquery values, based on “Some content” as the attribute value:

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

isLessThan and isGreaterThan

These operators are primarily intended for comparing date or numerical values. They can also be applied to numerical metadata, for example the width of an image, or to CMS object IDs. The latter allows you to find objects whose ID (by its character values) is less than or greater than the comparison value, e.g. for sharding search results with a large number of hits.

These operators only consider attributes of CMS objects, not widgets. Thus, widget attributes are not searchable using the isLessThan and isGreaterThan operators. Values of date attributes close to the current date and time are rounded to the nearest full minute before comparison.

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, 0) (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, 1, 0) (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.