v5.1.0

07-June-2025

Scope

• Documentation Update
• New SOQL Features
• Enhanced AggregateResult Mocking
• Querying Improvements

SOQL

• Added support for WITH DATA CATEGORY.
• Introduced a new way to mock AggregateResult.
• Added orderByCount() for aggregate queries.
• Enhanced toValuesOf() to support related fields.
• Added alwaysAddId() for convenience.

Documentation Update

We've invested heavily in making our documentation clearer and more comprehensive.

• New Examples: Added extensive examples for new features like WITH DATA CATEGORY and AggregateResult mocking.
• Titled Code Blocks: All code examples now have titles, making it easier to understand the context of each snippet.
• Improved Structure: The documentation sidebar has been reorganized for better navigation.

New Feature: WITH DATA CATEGORY

SOQL Lib now fully supports WITH DATA CATEGORY clauses, allowing you to filter queries based on Salesforce Knowledge data categories.

SOQL

SELECT Id, Title
FROM Knowledge__kav
WITH DATA CATEGORY Geography__c AT (Europe__c, North_America__c)

SOQL Lib

SOQL.of(Knowledge__kav.SObjectType)
    .with(Knowledge__kav.Id, Knowledge__kav.Title)
    .withDataCategory(
        SOQL.DataCategoryFilter
            .with('Geography__c')
            .at(new List<String>{ 'Europe__c', 'North_America__c' })
    ).toList();

Enhanced AggregateResult Mocking

Mocking AggregateResult has always been a challenge in Apex. We've introduced SOQL.AggregateResultProxy to simplify this process. Use the new .toAggregatedProxy() method to get mockable results from your aggregate queries.

Controller

public with sharing class ExampleController {
    public void getLeadAggregateResults() {
        List<SOQL.AggregateResultProxy> result = SOQL.of(Lead.SObjectType)
            .with(Lead.LeadSource)
            .COUNT(Lead.Id, 'total')
            .groupBy(Lead.LeadSource)
            .mockId('ExampleController.getLeadAggregateResults')
            .toAggregatedProxy(); // <== Use toAggregatedProxy()
    }
}

Test Class

@IsTest
static void getLeadAggregateResults() {
    List<Map<String, Object>> aggregateResults = new List<Map<String, Object>>{
        new Map<String, Object>{ 'LeadSource' => 'Web',  'total' => 10},
        new Map<String, Object>{ 'LeadSource' => 'Phone', 'total' => 5}
    };

    SOQL.mock('ExampleController.getLeadAggregateResults').thenReturn(aggregateResults);

    Test.startTest();
    List<SOQL.AggregateResultProxy> result = ExampleController.getLeadAggregateResults();
    Test.stopTest();

    Assert.areEqual(2, result.size());
}

Querying Improvements

ORDER BY COUNT()

You can now order grouped results by the count of a field using the orderByCount() method.

SOQL

SELECT Industry
FROM Account
GROUP BY Industry
ORDER BY COUNT(Industry) DESC NULLS LAST

SOQL Lib

SOQL.of(Account.SObjectType)
    .with(Account.Industry)
    .groupBy(Account.Industry)
    .orderByCount(Account.Industry).sortDesc().nullsLast()
    .toAggregated();

toValuesOf() for Related Fields

The toValuesOf() method now supports retrieving values from related parent objects, simplifying data extraction.

Apex

Set<String> parentAccountNames = new Set<String>();
for (Account acc : [SELECT Parent.Name FROM Account WHERE ParentId != NULL]) {
    parentAccountNames.add(acc.Parent.Name);
}

SOQL Lib

Set<String> parentAccountNames = SOQL.of(Account.SObjectType)
    .toValuesOf('Parent', Account.Name);

Breaking Changes

There are no breaking changes in this release.

Contributors

Thank you @packocz for your ideas and support!