Lambda provides functional constructs for SObject collections!

List<Account> accounts = new List<Account>{
    new Account(Name = 'Foo', AnnualRevenue = 50000),
    new Account(Name = 'Bar', AnnualRevenue = 30000)
}

SObjectCollection accountCollection = SObjectCollection.of(accounts);

SObjectCollection filtered = accountCollection.filter(Match.field(Account.AnnualRevenue).greaterThan(40000));
SObjectCollection mapped = filtered.mapAll(CopyFields.fromRecord(new Account(High_Value__c = true)));
SObjectCollection remaining = mapped.remove(Match.record(new Account(Name = 'Bar')));

Documentation

Lambda offers eager and lazy evaluation.

Eager evaluation through SObjectCollection is stable, richer, easier to use and is not consumable.

Lazy evaluation through SObjectStream can be more efficient for large data sets and can be performed for only as long as required, but is consumable and has to be recreated for every use.

• SObjectCollection
• SObjectStream

SObjectCollection functions

• isEmpty
• difference
• filter
• remove
• groupBy
• pick
• pluck
• mapAll
• mapSome
• mapToDecimal
• mapToDouble

isEmpty

difference

filter

Two predicates are provided out of the box, FieldsMatch and RecordMatch. They are instantiated through factory methods on Match:

SObjectCollection accountCollection = SObjectCollection.of(accounts);

Account prototype = new Account(Name = 'Foo');
SObjectCollection recordMatched = accountCollection.filter(Match.record(prototype));

SObjectCollection fieldMatched = accountCollection.filter(Match.field(Account.Name).equals('Foo'));

FieldsMatch

FieldsMatch returns true if a record satisfies all field matching conditions.

FieldsMatch is constructed with a fluent interface. Match factory method field returns an IncompleteFieldsMatch. FieldsMatch is obtained from the IncompleteFieldsMatch by providing a matching condition on the field. FieldsMatch can be expanded with a new matching condition to get another IncompleteFieldsMatch. The process is continued until all desired matching conditions are defined.

FieldsMatch m = Match.field(Account.Name).equals('Foo').also(Account.AnnualRevenue).greaterThan(100000);

FieldsMatch can be provided directly to filter method:

SObjectCollection filtered = SObjectCollection.of(accounts).filter(Match.field(Account.Name).equals('Foo').also(Account.AnnualRevenue).greaterThan(100000));

IncompleteFieldsMatch

FieldsMatch

Additional conditions can be defined with also, or its alias, field:

Warning ⚠️

isIn and isNotIn support a Set of one of the following types:

• Boolean
• Date
• Datetime
• Decimal
• Double
• Id
• Integer
• Long
• String

Other types are not supported and will throw an exception.

Fields used in field conditions must be available on the collection which is filtered, otherwise a System.SObjectException: SObject row was retrieved via SOQL without querying the requested field exception can be thrown.

RecordMatch

RecordMatch returns true if record fields are equal to those defined on a “prototype” record. Fields that are not defined on a prototype record do not have to match.

Account prototype = new Account(
    Name = 'Test',
    AnnualRevenue = 50000000
);
// Accounts named 'Test' with an AnnualRevenue of **exactly** 50,000,000 are matched
SObjectCollection filtered = accountCollection.filter(Match.record(prototype));

Warning ⚠️

Fields that are present on the prototype object must also be available on the collection which is filtered, otherwise a System.SObjectException: SObject row was retrieved via SOQL without querying the requested field exception will be thrown.

remove

remove works just like filter, but records which match a predicate are removed from the Collection view instead of kept.

pluck

Plucks field values from a SObjectCollection view of records into a List of appropriate type.

List<Account> accounts = new List<Account>{
	new Account(Name = 'Foo'),
	new Account(Name = 'Bar')
}
// Names are plucked into a new list, ['Foo', 'Bar']
List<String> names = SObjectCollection.of(accounts).pluckStrings(Account.Name);

Pluck can also be used for deeper relations by using String field paths instead of Schema.SObjectField parameters.

List<Opportunity> opportunities = new List<Opportunity>{
	new Opportunity(Account = new Account(Name = 'Foo')),
	new Opportunity(Account = new Account(Name = 'Bar'))
};

// Names are plucked into a new list ['Foo', 'Bar']
List<String> accountNames = SObjectCollection.of(opportunities).pluckStrings('Account.Name');

groupBy

Groups records by values of a specified field.

Map<Date, List<Opportunity>> opportunitiesByCloseDate = SObjectCollection.of(opportunities).groupByDates(Opportunity.CloseDate, opportunities);

pick

Returns a new SObjectCollection view of the collection which keeps just the specified fields, discarding others. Helps reduce overwriting potential for concurrent updates when locking is not an option.

List<Opportunity> opportunities = new List<Opportunity>{
	new Opportunity(Name = 'Foo', Amount = 10000, Description = 'Bar')
}
// Picked contains just Name and Amount fields. Description is not present.
SObjectCollection picked = SObjectCollection.of(opportunities).pick(new Set<String>{'Name', 'Amount'});

mapAll

Maps all elements of SObjectCollection view into another SObjectCollection view with the provided SObjectToSObjectFunction mapping function.

private class DoubleAmount implements SObjectToSObjectFunction {
    public SObject apply(SObject record) {
        record.put('Amount', 2 * (Decimal) record.get('Amount'));
        return record;
    }
}

List<Opportunity> opps = new List<Opportunity>{
    new Opportunity(Amount = 100),
    new Opportunity(Amount = 150)
};

SObjectCollection.of(opps).mapAll(new DoubleAmount()); // amounts have been doubled

One SObjectToSObjectFunction is provided out of the box, CopyFields. It is instantiated through a factory method, CopyFields.fromRecord.

CopyFields

CopyFields copies all defined fields from prototype record to the record it is applied to. Values of fields defined for prototype are overwritten on target records. Other fields on target record are not modified.

SObjectCollection.of(opps).mapAll(CopyFields.fromRecord(new Opportunity(Name = 'Test'))); // Name field has been overwritten with 'Test'

mapSome

Returns a new SObjectCollection view formed by mapping those view elements that satisfy predicate, and keeping those that do not unchanged.

private class DoubleAmount implements SObjectToSObjectFunction {
    public SObject apply(SObject record) {
        record.put('Amount', 2 * (Decimal) record.get('Amount'));
        return record;
    }
}

List<Opportunity> opps = new List<Opportunity>{
    new Opportunity(Amount = 100),
    new Opportunity(Amount = 150)
};

SObjectCollection.of(opps).mapSome(Match.field('Amount').gt(120), new DoubleAmount()); // 100 remains, but 150 has been doubled to 300

mapToDecimal

Maps a numeric field to a DecimalCollection. This is similar to pluckDecimals, but unlike a raw List<Decimal> returns a DecimalCollection which provides further functions.

Functions on DecimalCollection include sum and average.

mapToDouble

Maps a numeric field to a DoubleCollection. This is similar to pluckDoubles, but unlike a raw List<Double> returns a DoubleCollection which provides further functions.

Functions on DoubleCollection include sum and average.

List<Opportunity> opps = new List<Opportunity>{
    new Opportunity(Amount = 100),
    new Opportunity(Amount = 150)
};

Double average = SObjectCollection.of(opps).mapToDouble(Opportunity.Amount).average();

Important notes on the type system in Apex

Apex allows assignment of SObject lists and sets to its “subclass”, and the other way around:

List<SObject> objects = new List<SObject>();
List<Account> accounts = objects; // compiles!

List<Account> accounts = new List<Account>();
List<SObject> objects = accounts; // compiles as well!

An SObject list is an instance of any SObject “subclass” list!

List<SObject> objects = new List<SObject>();
System.debug(objects instanceof List<Account>); // true
System.debug(objects instanceof List<Opportunity>); // true

asList() and asSet() on SObjectCollection return a raw List<SObject> and Set<SObject>. This is more convenient because the type does not need to be provided, and a cast is not required in either case, but instanceof can provide unexpected results. A concrete type of the list can be passed in as well. When this is done, the returned List or Set are of the correct concrete type instead of generic SObject collection type:

List<Account> filteredAccounts = accountCollection.asList();
// List<SObject> returned!

List<Account> filteredAccounts = accountCollection.asList(List<Account>.class);
// List<Account> returned!

SObjectCollection also provides asMap() which returns a raw Map<Id, SObject>. Properly typed maps cannot be used without a cast.

Map<Id, Account> accountMap = accountCollection.asMap(); // Illegal assignment from Map<Id, SObject> to Map<Id, Account>
Map<Id, SObject> recordMap = accountCollection.asMap(); // Works!

For typed maps, both a cast and the correct concrete type must be provided:

Map<Id, Account> recordMap = (Map<Id, Account>) accountCollection.asMap(Map<Id, Account>.class); // Works!

🚧 SObjectStream functions

SObjectStream aims to provide SObjectCollection facilities but with a lazy evaluation, similar to Java’s Stream. It’s under construction and could rapidly change.

• filter
• remove
• mapAll
• mapSome

filter

Two predicates are provided out of the box, FieldsMatch and RecordMatch. They are instantiated through factory methods on Match

remove

mapAll

mapSome