You can use dictionary in OCL when you repeatedly match objects in one collection to objects in another collection by a shared key.

Purpose

dictionary creates a keyed lookup over a collection. Use it instead of repeatedly filtering the same collection inside an outer iteration when both operations match on a known value.

For example, if you iterate through deliveries and need the secondary object with the same name for each delivery, use dictionary to express that key-based match.

Syntax

Collection->dictionary(loopVariable | keyExpression, lookupExpression)

Part	Meaning
Collection	The collection to search by key.
loopVariable	The name used for each object in Collection while the key is defined.
keyExpression	The value from each object that becomes its lookup key.
lookupExpression	The value to match against the keys.

The expression returns the matching result as a collection, so use a collection operator when you need one object. The examples on this page use ->first because they assign an address from the first matching object.

Match two collections by a common attribute

The following expression iterates through ACollectionOf1000. For every ac1, it looks in SomeSecondaryCollectionOf1000 using ss2.Name as the key and ac1.Name as the value to look up.

ACollectionOf1000->collect(ac1 |
  SomeSecondaryCollectionOf1000
    ->dictionary(ss2 | ss2.Name, ac1.Name)
    ->first.HomeAddress := ac1.DeliveryAddress
)

In this example:

• ss2.Name is the key definition. Each object in SomeSecondaryCollectionOf1000 is keyed by its Name.
• ac1.Name is the lookup value. It selects the secondary object whose key matches the current object’s name.
• ->first takes the first matching object before its HomeAddress is assigned from ac1.DeliveryAddress.

Why use dictionary

A repeated ->select-style search examines the secondary collection for every object in the outer collection. For example, matching 1,000 outer objects against 500 inner objects requires repeated inner scans.

dictionary states the matching key directly. MDriven uses a hash-table implementation for dictionaries, enabling fast lookup by key rather than repeatedly comparing every object in the inner collection. This is most useful when the collection is read many times and changed less often.

The difference is most visible in nested matching logic:

Pattern	What happens
Repeated filtering in an outer loop	Each outer object causes another search through the inner collection.
dictionary lookup in an outer loop	The expression identifies the key used to find matching inner objects.

Use dictionary deliberately

Use dictionary when all of the following are true:

• You have a collection of candidate objects.
• You need to find objects by one known attribute or expression.
• The lookup occurs repeatedly, such as inside ->collect.
• The collection is read more often than it is written.

For a one-off collection traversal, use the collection operation that best expresses the intent. See Documentation:OCL General Operators for the available OCL operators.

Important considerations

• The key expression and lookup expression must produce values that can be meaningfully matched. In the example, both are Name values.
• dictionary returns a collection of matches. Do not assume that a match exists before applying ->first; make the handling of missing matches explicit in the surrounding OCL where needed.
• Do not use dictionary only because a collection is large. Use it for repeated key-based lookup, where it replaces repeated scanning.

See also

• Documentation:Learn OCL
• Documentation:OCL General Operators
• Documentation:OCLOperators Set
• Documentation:OCL Boolean Operators