SYNTAX

<Entity>.remove

<Collection>.remove

DESCRIPTION

Removes <Entity> or removes elements from <Collection> and deletes it/them. If removing from a collection, then using a unique alias to represent the collection is optional since .remove is not a collection operator. If any elements in <Collection> have one-to-many associations with other entities, then those entities will also be deleted.

The .remove operator's impact on elements of a collection can be controlled:
  • When the operator is written as .remove, .remove(), or .remove(true), any lower-level associated entities are also removed. For an example of this behavior, see example 2 below.
  • When the operator is written as .remove(false), lower-level associated entities are promoted to root level. For an example of this behavior, see example 3 below.

USAGE RESTRICTIONS

The Operators row of the table in Summary Table of Vocabulary Usage Restriction does not apply. Special exceptions: .remove may only be used in Action Rows (section 5 in Sections of Rulesheet that correlate with usage restrictions).

EXAMPLE 1: Remove an element from a collection

RULESHEET 1

This Rulesheet uses the operator to remove elements from collection1 whose decimal1 value is greater than 5.  Note the optional use of unique alias collection1 to represent the collection of Entity2 elements associated with Entity1.

RULETEST 1

A sample Ruletest provides a collection with two elements. The illustration shows Ruletest Input and Output panels

EXAMPLE 2: Remove an entity and its children

RULESHEET 2

This Rulesheet uses the operator, defaulting to (true), to entirely remove elements from Entity1.entity2 whose decimal1 value is greater than 5. Note that no unique alias has been used to represent the collection of Entity2 elements associated with Entity1.

RULETEST 2

A sample Ruletest provides an Entity1 with two entity2, each of which has an entity3 child of its own. The illustration shows Ruletest Input and Output panels. Note that when an entity2 is removed, its associated entity3 is also removed.

Note: Removing an entity and its children removes child entities from the work document only, not from working memory. If rules are written so as to access the child entities directly, they will still execute after the parent has been removed.

EXAMPLE 3: Remove an entity then promote its children

RULESHEET 3

This Rulesheet uses the operator with its (false) parameter to remove only the specified elements from Entity1.entity2 whose decimal1 value is greater than 5. Note no unique alias has been used to represent the collection of Entity2 elements associated with Entity1.

RULETEST 3

A sample Ruletest provides an Entity1 with two entity2, each of which has an entity3 child of its own. The illustration shows Ruletest Input and Output panels. Note that when an entity2 is removed, its associated entity3 is promoted to root level.