QRY_Builder
Class · Group: Query Infrastructure
Learn it: Fast Start - Selectors and Selectors guide
global inherited sharing class QRY_BuilderModern fluent query builder - the primary entry point for constructing and executing SOQL queries. Provides a clean, type-safe API for building queries with support for conditions, ordering, pagination, caching, and security enforcement. Design Principle: QRY_Builder passes the work to the existing query classes (QRY_Generator and QRY_Engine). This keeps older code working while giving new code a cleaner set of methods. 95% Use Case: Inline queries via QRY_Builder.selectFrom(...) 5% Use Case: Extend Builder for reusable custom selectors
Example
// Basic query
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.fields(new List<String>{'Name', 'Industry'})
.condition(Account.Industry).equals('Technology')
.toList();// With caching
Account account = (Account)QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Id).equals(accountId)
.withSystemMode()
.withSharing()
.withCache(300)
.getFirst();// Pagination
QRY_Builder.QueryPage result = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Type).equals('Customer')
.getPage(2, 25);See Also: IF_Queryable, QRY_Condition.DateLiteral, QRY_Function
Methods
| Method | Description |
|---|---|
| global static void clearMocks() | Clears all registered mocks and mock context classes for all SObjectTypes. |
| global static void registerMockContextClass(SObjectType sObjectType, String contextClassName) | Registers a FormulaEval context class for an SObjectType, enabling smart mock filtering. |
| global static QRY_Builder.Builder selectFrom(SObjectType sObjectType) | Entry point for inline queries. |
| global static void setAggregateMock(SObjectType sObjectType, List<Map<String, Object>> rows) | Makes every aggregate query on this object type return these rows instead of reading the database, in your tests. |
| global static void setMock(SObjectType sObjectType, List<SObject> mocks) | Registers mock records for a specific SObjectType during test execution. |
| global static void setMockException(SObjectType sObjectType, Exception exceptionToThrow) | Registers an exception to be thrown when QRY_Builder is invoked for the specified SObjectType. |
clearMocks
global static void clearMocks()Clears all registered mocks and mock context classes for all SObjectTypes.
Example
QRY_Builder.clearMocks();registerMockContextClass
global static void registerMockContextClass(SObjectType sObjectType, String contextClassName)Registers a FormulaEval context class for an SObjectType, enabling smart mock filtering. When registered, mock queries against this SObjectType will evaluate WHERE conditions in memory using the specified context class, returning only matching mock records.
Standard objects (Account, Contact, etc.) and Foobar__c are auto-detected and do not require explicit registration. Use this method for custom objects that need mock filtering.
Parameters
| Parameter | Type | Description |
|---|---|---|
sObjectType | SObjectType | The SObjectType to register the context for |
contextClassName | String | The fully qualified class name of the FormulaEval context |
Example
QRY_Builder.registerMockContextClass(Invoice__c.SObjectType, 'InvoiceFormulaContext');
QRY_Builder.setMock(Invoice__c.SObjectType, mockInvoices);
// Queries against Invoice__c now filter mocks using InvoiceFormulaContextselectFrom
global static QRY_Builder.Builder selectFrom(SObjectType sObjectType)Entry point for inline queries. Creates a new Builder instance for the specified SObject type.
Parameters
| Parameter | Type | Description |
|---|---|---|
sObjectType | SObjectType | The SObject type to query |
Returns QRY_Builder.Builder — Builder for fluent chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.fields(new List<String>{'Name', 'Industry'})
.condition(Account.Industry).equals('Technology')
.toList();setAggregateMock
global static void setAggregateMock(SObjectType sObjectType, List<Map<String, Object>> rows)Makes every aggregate query on this object type return these rows instead of reading the database, in your tests. Each map is one row: its keys are the aliases your code reads, its values what they hold. Pass null to clear.
An aggregate query is one with count(field, alias), count(fieldName), countDistinct(), sum(), avg(), min(), max() or groupBy(). The count() that ends a query and returns a number is not one: like toList(), it reads record mocks set with setMock. Read the rows with toAggregateList() or getFirstAggregate(). The rows come back in the order you gave them; only the query's limit is applied to them. Aliases are matched without regard to case. Rows set here replace any set earlier for the type, as setMock replaces records; TST_Mock.registerAggregateRows adds to them instead. clearMocks() removes them too.
Parameters
| Parameter | Type | Description |
|---|---|---|
sObjectType | SObjectType | The object type whose aggregate queries the rows answer. |
rows | List | The rows to return, in this order, or null to remove the rows set for the type. |
Throws
| Exception | Description |
|---|---|
| IllegalArgumentException | When sObjectType is null. |
Example
QRY_Builder.setAggregateMock(Account.SObjectType, new List<Map<String, Object>>
{
new Map<String, Object> {'total' => 3, 'Industry' => 'Energy'}
});
QRY_Builder.AggregateRow row = QRY_Builder.selectFrom(Account.SObjectType)
.count(Account.Id, 'total')
.groupBy(Account.Industry)
.getFirstAggregate();
Integer total = row.getInteger('total');setMock
global static void setMock(SObjectType sObjectType, List<SObject> mocks)Registers mock records for a specific SObjectType during test execution. When mocks are registered, queries will return these records instead of executing actual SOQL.
Smart Mock Filtering: WHERE conditions are evaluated in memory against mock records using FormulaEval when a context class is available for the SObjectType. Standard objects (Account, Contact, etc.) and Foobar__c are auto-detected. For custom objects, register a context class via registerMockContextClass() to enable filtering.
When filtering is not possible (no context class, unsupported condition operators, or relationship field traversals), all mocks are returned with only LIMIT and pagination applied.
Parameters
| Parameter | Type | Description |
|---|---|---|
sObjectType | SObjectType | The SObjectType to mock |
mocks | List | List of mock records to return for queries |
Throws
| Exception | Description |
|---|---|
| IllegalArgumentException | if mocks contain records of a different type than sObjectType |
Example
List<Account> mockAccounts = (List<Account>)TST_Builder.of(Account.SObjectType)
.withOverride(Account.Name, 'Test Account')
.withCount(5)
.withoutInsertion(true)
.buildList();
QRY_Builder.setMock(Account.SObjectType, mockAccounts);setMockException
global static void setMockException(SObjectType sObjectType, Exception exceptionToThrow)Registers an exception to be thrown when QRY_Builder is invoked for the specified SObjectType. Used for negative-path test coverage when a caller needs to exercise a catch block around a SOQL call. Cleared by TST_Mock.clear() and TST_Mock.clear(SObjectType).
Parameters
| Parameter | Type | Description |
|---|---|---|
sObjectType | SObjectType | The SObjectType for which queries should throw. |
exceptionToThrow | Exception | The exception instance to throw. |
Example
QRY_Builder.setMockException(Account.SObjectType, new QueryException('Simulated SOQL failure'));Inner Classes
| Class | Description |
|---|---|
| AggregateRow | Typed wrapper around AggregateResult for convenient value access. |
| Builder | Extensible query builder class. |
| ConditionBuilder | Fluent builder for field-level conditions (WHERE and HAVING). |
| DataCategoryBuilder | Fluent builder for WITH DATA CATEGORY filters. |
| QueryPage | Result container for paged queries, providing records and pagination metadata. |
| Scope | Enumeration of valid SOQL scope values for use with the USING SCOPE clause. |