QRY_Builder.Builder
Class
global virtual inherited sharing class QRY_Builder.Builder implements IF_QueryableImplements: IF_Queryable
Known Derived Types: IF_Queryable.count(), IF_Queryable.exists(), IF_Queryable.getFirst(), IF_Queryable.toList(), IF_Queryable.toQueryLocator()
Extensible query builder class. Maintains internal query state and uses QRY_Generator for SOQL building and QRY_Engine for execution.
Example
QRY_Builder.Builder query = QRY_Builder.selectFrom(Account.SObjectType)
.addField(Account.Name)
.condition(Account.Industry).equals('Technology');
List<Account> accounts = query.toList();Methods
| Method | Description |
|---|---|
| global QRY_Builder.Builder addCondition(QRY_Condition.Evaluable condition) | Adds a pre-built condition to the query. |
| global virtual QRY_Builder.Builder addField(QRY_Function functionField, String alias) | Projects a SOQL date-function expression into SELECT under an explicit alias, for read-back via AggregateRow (e.g. |
| global QRY_Builder.Builder addField(SObjectField objectField) | Adds a single field without disabling default fields. |
| global QRY_Builder.Builder addField(String fieldName) | Adds a single field without disabling default fields. |
| global QRY_Builder.Builder addFields(List<SObjectField> objectFields) | Adds fields to the selection without disabling default fields. |
| global QRY_Builder.Builder addFields(List<String> fieldNames) | Adds fields to the selection without disabling default fields. |
| global QRY_Builder.Builder addFieldSet(FieldSet aFieldset) | Adds fields from a FieldSet token without disabling default fields. |
| global QRY_Builder.Builder addFieldSet(String fieldSetName) | Adds fields from a FieldSet without disabling default fields. |
| global QRY_Builder.Builder allRows() | Includes deleted and archived records (ALL ROWS). |
| global virtual QRY_Builder.ConditionBuilder andCondition(QRY_Function functionField) | Starts an AND condition whose left-hand side is a SOQL function expression (for example a geolocation DISTANCE from QRY_Function.distanceInMiles). |
| global QRY_Builder.ConditionBuilder andCondition(SObjectField field) | Starts an AND condition on a field using an SObjectField token. |
| global QRY_Builder.ConditionBuilder andCondition(String fieldName) | Starts an AND condition on a field using its API name. |
| global QRY_Builder.Builder ascending() | Sets the last ORDER BY clause to ASCENDING. |
| global Map<Id, List<SObject>> asGroupedMapById(SObjectField keyField) | Executes the query and returns the results grouped by an Id field (e.g. |
| global Map<Id, List<SObject>> asGroupedMapById(String fieldName) | Executes the query and returns the results grouped by an Id field. |
| global Map<String, List<SObject>> asGroupedMapByString(SObjectField keyField) | Executes the query and returns the results grouped by a String field value. |
| global Map<String, List<SObject>> asGroupedMapByString(String fieldName) | Executes the query and returns the results grouped by a String field value. |
| global List<Id> asIdList() | Returns the results as a List of Ids. |
| global Set<Id> asIdSet() | Executes the query and returns a Set of record Ids. |
| global Map<Id, SObject> asMap() | Executes the query and returns results as a Map. |
| global Map<Id, SObject> asMapById(SObjectField keyField) | Executes the query and returns the results as a Map keyed by the specified Id field (e.g. |
| global Map<Id, SObject> asMapById(String fieldName) | Executes the query and returns the results as a Map keyed by the specified Id field. |
| global Map<String, SObject> asMapByString(SObjectField keyField) | Executes the query and returns the results as a Map keyed by a String field value. |
| global Map<String, SObject> asMapByString(String fieldName) | Executes the query and returns the results as a Map keyed by a String field value. |
| global Set<String> asStringSet(SObjectField field) | Executes the query and returns a Set of distinct String values for the specified field. |
| global Set<String> asStringSet(String fieldName) | Executes the query and returns a Set of distinct String values for the specified field. |
| global Set<Object> asValueSet(SObjectField field) | Executes the query and returns a Set of distinct values for the specified field. |
| global Set<Object> asValueSet(String fieldName) | Executes the query and returns a Set of distinct values for the specified field. |
| global QRY_Builder.Builder avg(SObjectField field) | Applies an AVG aggregate function. |
| global virtual QRY_Builder.Builder avg(SObjectField field, String alias) | Applies an AVG aggregate under an explicit result alias. |
| global QRY_Builder.Builder bypassSharing() | Bypasses sharing rules using a without sharing proxy class. |
| global virtual QRY_Builder.ConditionBuilder condition(QRY_Function functionField) | Starts a WHERE condition whose left-hand side is a SOQL function expression (for example a geolocation DISTANCE from QRY_Function.distanceInMiles), so you can filter on the function result: .lessThan(10) renders DISTANCE(...) < 10. |
| global QRY_Builder.ConditionBuilder condition(SObjectField objectField) | Starts a WHERE condition on a field using an SObjectField token. |
| global QRY_Builder.ConditionBuilder condition(String fieldName) | Starts a WHERE condition on a field using its API name. |
| global Integer count() | Returns the number of records that match the query criteria. |
| global virtual QRY_Builder.Builder count(SObjectField field, String alias) | Applies a COUNT aggregate under an explicit result alias. |
| global QRY_Builder.Builder count(String fieldName) | Applies a COUNT aggregate function. |
| global QRY_Builder.Builder countDistinct(SObjectField field) | Applies a COUNT_DISTINCT aggregate function. |
| global virtual QRY_Builder.Builder countDistinct(SObjectField field, String alias) | Applies a COUNT_DISTINCT aggregate under an explicit result alias. |
| global QRY_Builder.Builder countDistinct(String fieldName) | Applies a COUNT_DISTINCT aggregate function. |
| global QRY_Builder.Builder cube() | Flags the GROUP BY clause as CUBE for cross-tabulation. |
| global QRY_Builder.Builder descending() | Sets the last ORDER BY clause to DESCENDING. |
| global Boolean exists() | Checks whether any records exist matching the query criteria. |
| global QRY_Builder.Builder fields(List<SObjectField> objectFields) | Explicitly select fields using SObjectField tokens. |
| global QRY_Builder.Builder fields(List<String> fieldNames) | Explicitly select fields by API name. |
| global QRY_Builder.Builder fieldSet(FieldSet aFieldset) | Selects fields from a FieldSet token. |
| global QRY_Builder.Builder fieldSet(String fieldSetName) | Selects fields from a FieldSet. |
| global QRY_Builder.Builder forcePerformanceLogging() | Forces performance logging regardless of threshold for this query. |
| global QRY_Builder.Builder forReference() | Locks returned records FOR REFERENCE. |
| global QRY_Builder.Builder forUpdate() | Locks returned records FOR UPDATE. |
| global QRY_Builder.Builder forView() | Locks returned records FOR VIEW. |
| global virtual Set<String> getDefaultFields() | Override to provide default fields for this selector. |
| global SObject getFirst() | Executes the query and returns the first record (or null). |
| global QRY_Builder.AggregateRow getFirstAggregate() | Executes an aggregate query and returns the first result as a typed AggregateRow. |
| global QRY_Builder.QueryPage getPage(Integer requestedPageNumber, Integer requestedPageSize) | Executes a paged query and returns results with pagination metadata. |
| global SObject getRandomItem() | Returns a single random record matching the query criteria. |
| global List<SObject> getRandomItems(Integer randomCount) | Returns multiple random records matching the query criteria. |
| global virtual QRY_Builder.Builder groupBy(QRY_Function functionField) | Adds a SOQL date-function expression to the GROUP BY clause (e.g. |
| global QRY_Builder.Builder groupBy(SObjectField groupField) | Adds a field to the GROUP BY clause using an SObjectField token. |
| global QRY_Builder.Builder groupBy(String groupField) | Adds a GROUP BY clause. |
| global QRY_Builder.Builder grouping(SObjectField field) | Adds a GROUPING(field) expression to the SELECT clause for use with ROLLUP or CUBE. |
| global QRY_Builder.Builder grouping(String fieldName) | Adds a GROUPING(field) expression to the SELECT clause by field name. |
| global QRY_Builder.ConditionBuilder havingAvgOf(SObjectField field) | Starts a HAVING condition on the AVG of a field. |
| global QRY_Builder.ConditionBuilder havingCount() | Starts a HAVING condition on the global COUNT(). |
| global QRY_Builder.ConditionBuilder havingCountOf(SObjectField field) | Starts a HAVING condition on the COUNT of a field. |
| global QRY_Builder.ConditionBuilder havingMaxOf(SObjectField field) | Starts a HAVING condition on the MAX of a field. |
| global QRY_Builder.ConditionBuilder havingMinOf(SObjectField field) | Starts a HAVING condition on the MIN of a field. |
| global QRY_Builder.ConditionBuilder havingSumOf(SObjectField field) | Starts a HAVING condition on the SUM of a field. |
| global Boolean isCached() | Indicates whether the last execution retrieved results from cache. |
| global QRY_Builder.Builder logPerformanceIfSlowerThan(Integer thresholdMs) | Sets a custom performance threshold for this query. |
| global QRY_Builder.Builder max(SObjectField field) | Applies a MAX aggregate function. |
| global virtual QRY_Builder.Builder max(SObjectField field, String alias) | Applies a MAX aggregate under an explicit result alias. |
| global QRY_Builder.Builder min(SObjectField field) | Applies a MIN aggregate function. |
| global virtual QRY_Builder.Builder min(SObjectField field, String alias) | Applies a MIN aggregate under an explicit result alias. |
| global QRY_Builder.Builder nullsFirst() | Sets the last ORDER BY clause to NULLS FIRST. |
| global QRY_Builder.Builder nullsLast() | Sets the last ORDER BY clause to NULLS LAST. |
| global virtual QRY_Builder.ConditionBuilder orCondition(QRY_Function functionField) | Starts an OR condition whose left-hand side is a SOQL function expression (for example a geolocation DISTANCE from QRY_Function.distanceInMiles). |
| global QRY_Builder.ConditionBuilder orCondition(SObjectField field) | Starts an OR condition on a field using an SObjectField token. |
| global QRY_Builder.ConditionBuilder orCondition(String fieldName) | Starts an OR condition on a field using its API name. |
| global virtual QRY_Builder.Builder orderBy(QRY_Function functionField) | Orders by a SOQL date-function expression, ascending (e.g. |
| global virtual QRY_Builder.Builder orderBy(QRY_Function functionField, Boolean sortDescending) | Orders by a SOQL date-function expression, ascending or descending. |
| global QRY_Builder.Builder orderBy(SObjectField field) | Adds an ORDER BY clause (default ascending). |
| global QRY_Builder.Builder orderBy(SObjectField field, Boolean sortDescending) | Adds an ORDER BY clause with a dynamic sort direction. |
| global QRY_Builder.Builder orderBy(SObjectField field, Boolean sortDescending, Boolean nullsLast) | Adds an ORDER BY clause with a dynamic sort direction and nulls placement. |
| global QRY_Builder.Builder orderBy(String fieldName) | Adds an ORDER BY clause (default ascending). |
| global QRY_Builder.Builder orderBy(String fieldName, Boolean sortDescending) | Adds an ORDER BY clause with a dynamic sort direction. |
| global QRY_Builder.Builder orderBy(String fieldName, Boolean sortDescending, Boolean nullsLast) | Adds an ORDER BY clause with a dynamic sort direction and nulls placement. |
| global virtual QRY_Builder.Builder orderByCount(SObjectField field, Boolean sortDescending) | Orders an aggregate query by COUNT of a field (e.g. |
| global QRY_Builder.Builder relatedField(String parentField) | Adds a single parent field. |
| global QRY_Builder.Builder relatedFields(List<String> parentFields) | Adds parent (related) fields to the selection. |
| global QRY_Builder.Builder rollup() | Flags the GROUP BY clause as ROLLUP for subtotals. |
| global QRY_Builder.Builder selectAllFields() | Configures the query to select ALL fields on the object. |
| global QRY_Builder.Builder stripInaccessible() | Strips inaccessible fields from results. |
| global QRY_Builder.Builder subselect(QRY_Builder.Builder childQuery, String relationshipName) | Adds a child subquery (child relationship query). |
| global QRY_Builder.Builder sum(SObjectField field) | Applies a SUM aggregate function. |
| global virtual QRY_Builder.Builder sum(SObjectField field, String alias) | Applies a SUM aggregate under an explicit result alias. |
| global QRY_Builder.Builder suppressPerformanceLogging() | Suppresses performance logging for this query. |
| global List<QRY_Builder.AggregateRow> toAggregateList() | Executes an aggregate query and returns results as typed AggregateRow wrappers. |
| global Database.Cursor toCursor() | Returns a Database.Cursor for large data set traversal. |
| global List<SObject> toList() | Executes the query and returns a List of SObjects. |
| global Database.QueryLocator toQueryLocator() | Returns a Database.QueryLocator for batch processing. |
| global String toSoql() | Generates and returns the SOQL string without executing it. |
| global QRY_Builder.Builder usingScope(QRY_Builder.Scope scopeValue) | Filters records by visibility scope using USING SCOPE clause. |
| global QRY_Builder.Builder withCache(Integer ttlSeconds) | Enables platform caching for this query. |
| global QRY_Builder.DataCategoryBuilder withDataCategory(String groupName) | Starts a WITH DATA CATEGORY filter for the specified data category group. |
| global QRY_Builder.Builder withLimit(Integer recordLimit) | Sets the maximum number of records to return (LIMIT). |
| global QRY_Builder.Builder withOffset(Integer rowNumber) | Sets the record offset (OFFSET). |
| global QRY_Builder.Builder withoutSecurity() | Disables all security enforcement. |
| global QRY_Builder.Builder withSharing() | Enforces sharing rules using a with sharing proxy class. |
| global QRY_Builder.Builder withSystemMode() | Forces SYSTEM_MODE execution regardless of the UserModeQueries_Enabled feature flag. |
| global QRY_Builder.Builder withUserMode() | Runs the query in USER_MODE. |
addCondition
global QRY_Builder.Builder addCondition(QRY_Condition.Evaluable condition)Adds a pre-built condition to the query. Use this for complex condition groups that cannot be expressed with the fluent API.
Parameters
| Parameter | Type | Description |
|---|---|---|
condition | QRY_Condition.Evaluable | The condition to add (created via QRY_Condition classes) |
Returns QRY_Builder.Builder — Builder for chaining
Example
QRY_Condition.OrCondition statusGroup = new QRY_Condition.OrCondition();
statusGroup.add(new QRY_Condition.FieldCondition('Status__c', QRY_Condition.Operator.EQUALS, 'Active'));
statusGroup.add(new QRY_Condition.FieldCondition('Status__c', QRY_Condition.Operator.EQUALS, 'Pending'));
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Industry).equals('Technology')
.addCondition(statusGroup)
.toList();addField
global virtual QRY_Builder.Builder addField(QRY_Function functionField, String alias)Projects a SOQL date-function expression into SELECT under an explicit alias, for read-back via AggregateRow (e.g. CALENDAR_MONTH(CloseDate) closeMonth -> row.getInteger('closeMonth')). Pair with groupBy(QRY_Function) using the same factory so the SELECT and GROUP BY expressions match. The alias is validated as a bare identifier — the same rule as the aliased aggregate selections — so a caller-supplied alias can never carry SOQL syntax into the clause.
Parameters
| Parameter | Type | Description |
|---|---|---|
functionField | QRY_Function | The date-function expression, from a QRY_Function factory |
alias | String | The read-back alias for the projected expression; must be a bare identifier |
Returns QRY_Builder.Builder — Builder for chaining
Throws
| Exception | Description |
|---|---|
| IllegalArgumentException | if alias is not a bare identifier (a letter followed by letters, digits or underscores) |
Example
QRY_Builder.selectFrom(Opportunity.SObjectType)
.addField(QRY_Function.calendarMonth(Opportunity.CloseDate), 'closeMonth')
.count('Id')
.groupBy(QRY_Function.calendarMonth(Opportunity.CloseDate))
.toAggregateList();global QRY_Builder.Builder addField(SObjectField objectField)Adds a single field without disabling default fields.
Parameters
| Parameter | Type | Description |
|---|---|---|
objectField | SObjectField | SObjectField token |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.addField(Account.Website)
.toList();global QRY_Builder.Builder addField(String fieldName)Adds a single field without disabling default fields.
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldName | String | API name |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.addField('Website')
.toList();addFields
global QRY_Builder.Builder addFields(List<SObjectField> objectFields)Adds fields to the selection without disabling default fields.
Parameters
| Parameter | Type | Description |
|---|---|---|
objectFields | List | List of SObjectField tokens |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.addFields(new List<SObjectField>{Account.Phone, Account.Website})
.toList();global QRY_Builder.Builder addFields(List<String> fieldNames)Adds fields to the selection without disabling default fields.
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldNames | List | List of field API names |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.addFields(new List<String>{'Phone', 'Website'})
.toList();addFieldSet
global QRY_Builder.Builder addFieldSet(FieldSet aFieldset)Adds fields from a FieldSet token without disabling default fields.
Parameters
| Parameter | Type | Description |
|---|---|---|
aFieldset | FieldSet | The Schema.FieldSet token |
Returns QRY_Builder.Builder — Builder for chaining
Example
FieldSet fs = SObjectType.Account.fieldSets.Account_Summary;
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.addFieldSet(fs)
.toList();global QRY_Builder.Builder addFieldSet(String fieldSetName)Adds fields from a FieldSet without disabling default fields.
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldSetName | String | The API Name of the FieldSet |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.addFieldSet('Account_Summary')
.toList();allRows
global QRY_Builder.Builder allRows()Includes deleted and archived records (ALL ROWS).
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.IsDeleted).equals(true)
.allRows()
.toList();andCondition
global virtual QRY_Builder.ConditionBuilder andCondition(QRY_Function functionField)Starts an AND condition whose left-hand side is a SOQL function expression (for example a geolocation DISTANCE from QRY_Function.distanceInMiles). Mirrors andCondition(SObjectField) for function expressions.
Parameters
| Parameter | Type | Description |
|---|---|---|
functionField | QRY_Function | The function expression, from a QRY_Function factory |
Returns QRY_Builder.ConditionBuilder — ConditionBuilder for specifying the operator
Example
List<Account> nearby = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Industry).equals('Technology')
.andCondition(QRY_Function.distanceInMiles(Account.BillingAddress, 37.775, -122.418)).lessThan(10)
.toList();global QRY_Builder.ConditionBuilder andCondition(SObjectField field)Starts an AND condition on a field using an SObjectField token.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | Field token |
Returns QRY_Builder.ConditionBuilder — ConditionBuilder for specifying the operator
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Industry).equals('Technology')
.andCondition(Account.Type).equals('Customer')
.toList();global QRY_Builder.ConditionBuilder andCondition(String fieldName)Starts an AND condition on a field using its API name.
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldName | String | Field API name |
Returns QRY_Builder.ConditionBuilder — ConditionBuilder for specifying the operator
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.condition('Industry').equals('Technology')
.andCondition('Type').equals('Customer')
.toList();ascending
global QRY_Builder.Builder ascending()Sets the last ORDER BY clause to ASCENDING.
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.orderBy(Account.Name).ascending()
.toList();asGroupedMapById
global Map<Id, List<SObject>> asGroupedMapById(SObjectField keyField)Executes the query and returns the results grouped by an Id field (e.g. a parent-lookup field). Duplicates are preserved as separate entries within each group. Delegates to UTIL_SObject.groupByKey.
Parameters
| Parameter | Type | Description |
|---|---|---|
keyField | SObjectField | The SObjectField token whose value will be used as the map key. Must reference an Id-typed field on the returned SObject. |
Returns SObject — Map > keyed by the field value. Records with a null key field are grouped under the null key. Returns an empty map if the query yields no results.
Example
Map<Id, List<SObject>> contactsByAccount = QRY_Builder.selectFrom(Contact.SObjectType)
.addFields(new List<SObjectField>{Contact.Id, Contact.AccountId})
.condition(Contact.AccountId).isNotNull()
.asGroupedMapById(Contact.AccountId);global Map<Id, List<SObject>> asGroupedMapById(String fieldName)Executes the query and returns the results grouped by an Id field. Supports dot-notation for parent fields. Delegates to UTIL_SObject.groupByKey.
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldName | String | The API name of the Id field whose value will be used as the map key. |
Returns SObject — Map > keyed by the field value. Records with a null key field are grouped under the null key. Returns an empty map when the query yields no results.
Example
Map<Id, List<SObject>> contactsByOwner = QRY_Builder.selectFrom(Contact.SObjectType)
.addField(Contact.OwnerId)
.asGroupedMapById('OwnerId');asGroupedMapByString
global Map<String, List<SObject>> asGroupedMapByString(SObjectField keyField)Executes the query and returns the results grouped by a String field value. Duplicates are preserved as separate entries within each group. Key casing is preserved. Delegates to UTIL_SObject.groupByStringKey.
Parameters
| Parameter | Type | Description |
|---|---|---|
keyField | SObjectField | The SObjectField token whose value will be used as the map key. |
Returns SObject — Map > keyed by the stringified field value. Returns an empty map when the query yields no results.
Example
Map<String, List<SObject>> accountsByIndustry = QRY_Builder.selectFrom(Account.SObjectType)
.addField(Account.Industry)
.asGroupedMapByString(Account.Industry);global Map<String, List<SObject>> asGroupedMapByString(String fieldName)Executes the query and returns the results grouped by a String field value. Supports dot-notation for parent fields. Key casing is preserved. Delegates to UTIL_SObject.groupByStringKey.
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldName | String | The API name of the field whose value will be used as the map key. |
Returns SObject — Map > keyed by the stringified field value. Returns an empty map when the query yields no results.
Example
Map<String, List<SObject>> accountsByOwnerName = QRY_Builder.selectFrom(Account.SObjectType)
.addField(Account.OwnerId)
.relatedField('Owner.Name')
.asGroupedMapByString('Owner.Name');asIdList
global List<Id> asIdList()Returns the results as a List of Ids.
Returns Id — List
Example
List<Id> accountIds = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Type).equals('Customer')
.asIdList();asIdSet
global Set<Id> asIdSet()Executes the query and returns a Set of record Ids.
Returns Id — Set
Example
Set<Id> accountIds = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Type).equals('Customer')
.asIdSet();asMap
global Map<Id, SObject> asMap()Executes the query and returns results as a Map .
Returns SObject — Map
Example
Map<Id, SObject> accountMap = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Type).equals('Customer')
.asMap();asMapById
global Map<Id, SObject> asMapById(SObjectField keyField)Executes the query and returns the results as a Map keyed by the specified Id field (e.g. a parent-lookup field). Last record wins when key values collide. Delegates to UTIL_SObject.indexById.
Parameters
| Parameter | Type | Description |
|---|---|---|
keyField | SObjectField | The SObjectField token whose value will be used as the map key. Must reference an Id-typed field on the returned SObject. |
Returns SObject — Map keyed by the field value. Records with a null key field are mapped under the null key. Returns an empty map when the query yields no results.
Example
Map<Id, SObject> contactsByAccount = QRY_Builder.selectFrom(Contact.SObjectType)
.addFields(new List<SObjectField>{Contact.Id, Contact.AccountId})
.condition(Contact.AccountId).isNotNull()
.asMapById(Contact.AccountId);global Map<Id, SObject> asMapById(String fieldName)Executes the query and returns the results as a Map keyed by the specified Id field. Supports dot-notation for parent fields (e.g. 'Account.OwnerId'). Delegates to UTIL_SObject.indexById.
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldName | String | The API name of the Id field whose value will be used as the map key. |
Returns SObject — Map keyed by the field value. Records with a null key field are mapped under the null key. Returns an empty map when the query yields no results.
Example
Map<Id, SObject> contactsByOwner = QRY_Builder.selectFrom(Contact.SObjectType)
.addField(Contact.OwnerId)
.asMapById('OwnerId');asMapByString
global Map<String, SObject> asMapByString(SObjectField keyField)Executes the query and returns the results as a Map keyed by a String field value. Last record wins when key values collide. Key casing is preserved (no implicit lowering). Delegates to UTIL_SObject.indexByStringKey.
Parameters
| Parameter | Type | Description |
|---|---|---|
keyField | SObjectField | The SObjectField token whose value will be used as the map key. |
Returns SObject — Map keyed by the stringified field value. Returns an empty map when the query yields no results.
Example
Map<String, SObject> accountByName = QRY_Builder.selectFrom(Account.SObjectType)
.addField(Account.Name)
.asMapByString(Account.Name);global Map<String, SObject> asMapByString(String fieldName)Executes the query and returns the results as a Map keyed by a String field value. Supports dot-notation for parent fields (e.g. 'Owner.Name'). Key casing is preserved. Delegates to UTIL_SObject.indexByStringKey.
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldName | String | The API name of the field whose value will be used as the map key. |
Returns SObject — Map keyed by the stringified field value. Returns an empty map when the query yields no results.
Example
Map<String, SObject> accountByOwnerName = QRY_Builder.selectFrom(Account.SObjectType)
.addField(Account.OwnerId)
.relatedField('Owner.Name')
.asMapByString('Owner.Name');asStringSet
global Set<String> asStringSet(SObjectField field)Executes the query and returns a Set of distinct String values for the specified field.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field token to extract String values from |
Returns String — Set of String field values (nulls excluded)
Example
Set<String> nicknames = QRY_Builder.selectFrom(User.SObjectType)
.addField(User.CommunityNickname)
.condition(User.CommunityNickname).startsWith('Billy')
.asStringSet(User.CommunityNickname);global Set<String> asStringSet(String fieldName)Executes the query and returns a Set of distinct String values for the specified field.
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldName | String | The field API name to extract String values from |
Returns String — Set of String field values (nulls excluded)
Example
Set<String> ownerNames = QRY_Builder.selectFrom(Account.SObjectType)
.relatedField('Owner.Name')
.asStringSet('Owner.Name');asValueSet
global Set<Object> asValueSet(SObjectField field)Executes the query and returns a Set of distinct values for the specified field.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field token to extract values from |
Returns Object — Set of field values
Example
Set<Object> industries = QRY_Builder.selectFrom(Account.SObjectType)
.addField(Account.Industry)
.asValueSet(Account.Industry);global Set<Object> asValueSet(String fieldName)Executes the query and returns a Set of distinct values for the specified field.
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldName | String | The field API name to extract values from |
Returns Object — Set of field values
Example
Set<Object> ownerNames = QRY_Builder.selectFrom(Account.SObjectType)
.relatedField('Owner.Name')
.asValueSet('Owner.Name');avg
global QRY_Builder.Builder avg(SObjectField field)Applies an AVG aggregate function.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field to aggregate |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<AggregateResult> results = QRY_Builder.selectFrom(Opportunity.SObjectType)
.groupBy(Opportunity.StageName)
.avg(Opportunity.Amount)
.toList();global virtual QRY_Builder.Builder avg(SObjectField field, String alias)Applies an AVG aggregate under an explicit result alias. Aliased aggregates accumulate, so one query folds several aggregates and reads each back by its alias.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field to average |
alias | String | The result alias; must be a bare identifier, unique across the aliased selections |
Returns QRY_Builder.Builder — Builder for chaining
Throws
| Exception | Description |
|---|---|
| IllegalArgumentException | if alias is not a bare identifier (a letter followed by letters, digits or underscores); or, when the query builds, if the alias duplicates an earlier aliased selection |
Example
.avg(Opportunity.Amount, 'meanAmount')bypassSharing
global QRY_Builder.Builder bypassSharing()Bypasses sharing rules using a without sharing proxy class.
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.bypassSharing()
.toList();condition
global virtual QRY_Builder.ConditionBuilder condition(QRY_Function functionField)Starts a WHERE condition whose left-hand side is a SOQL function expression (for example a geolocation DISTANCE from QRY_Function.distanceInMiles), so you can filter on the function result: .lessThan(10) renders DISTANCE(...) < 10. Mirrors condition(SObjectField) but seats the rendered function expression on the comparison left-hand side.
Parameters
| Parameter | Type | Description |
|---|---|---|
functionField | QRY_Function | The function expression, from a QRY_Function factory |
Returns QRY_Builder.ConditionBuilder — ConditionBuilder for specifying the operator
Example
List<Account> nearby = QRY_Builder.selectFrom(Account.SObjectType)
.condition(QRY_Function.distanceInMiles(Account.BillingAddress, 37.775, -122.418)).lessThan(10)
.toList();global QRY_Builder.ConditionBuilder condition(SObjectField objectField)Starts a WHERE condition on a field using an SObjectField token.
Parameters
| Parameter | Type | Description |
|---|---|---|
objectField | SObjectField | Field token |
Returns QRY_Builder.ConditionBuilder — ConditionBuilder for specifying the operator
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Industry).equals('Technology')
.toList();global QRY_Builder.ConditionBuilder condition(String fieldName)Starts a WHERE condition on a field using its API name.
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldName | String | Field API name |
Returns QRY_Builder.ConditionBuilder — ConditionBuilder for specifying the operator
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.condition('Industry').equals('Technology')
.toList();count
global Integer count()Returns the number of records that match the query criteria.
Returns Integer — Integer count
Example
Integer total = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Type).equals('Customer')
.count();global virtual QRY_Builder.Builder count(SObjectField field, String alias)Applies a COUNT aggregate under an explicit result alias. Aliased aggregates accumulate — unlike the single-aggregate overloads, each call adds one more selection — so one query folds several aggregates and reads each back by its alias on the AggregateRow.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field to count |
alias | String | The result alias; must be a bare identifier, unique across the aliased selections |
Returns QRY_Builder.Builder — Builder for chaining
Throws
| Exception | Description |
|---|---|
| IllegalArgumentException | if alias is not a bare identifier (a letter followed by letters, digits or underscores); or, when the query builds, if the alias duplicates an earlier aliased selection |
Example
List<QRY_Builder.AggregateRow> rows = QRY_Builder.selectFrom(Opportunity.SObjectType)
.groupBy(Opportunity.StageName)
.count(Opportunity.Id, 'rowTotal')
.min(Opportunity.CreatedDate, 'firstSeen')
.toAggregateList();global QRY_Builder.Builder count(String fieldName)Applies a COUNT aggregate function.
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldName | String | The field to count (or null for COUNT()) |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<AggregateResult> results = QRY_Builder.selectFrom(Account.SObjectType)
.groupBy(Account.Industry)
.count('Id')
.toList();countDistinct
global QRY_Builder.Builder countDistinct(SObjectField field)Applies a COUNT_DISTINCT aggregate function.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field to count distinct values |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<AggregateResult> results = QRY_Builder.selectFrom(Contact.SObjectType)
.groupBy(Contact.AccountId)
.countDistinct(Contact.Email)
.toList();global virtual QRY_Builder.Builder countDistinct(SObjectField field, String alias)Applies a COUNT_DISTINCT aggregate under an explicit result alias. Aliased aggregates accumulate, so one query folds several aggregates and reads each back by its alias.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field to count distinct values of |
alias | String | The result alias; must be a bare identifier, unique across the aliased selections |
Returns QRY_Builder.Builder — Builder for chaining
Throws
| Exception | Description |
|---|---|
| IllegalArgumentException | if alias is not a bare identifier (a letter followed by letters, digits or underscores); or, when the query builds, if the alias duplicates an earlier aliased selection |
Example
.countDistinct(Contact.Email, 'uniqueEmails')global QRY_Builder.Builder countDistinct(String fieldName)Applies a COUNT_DISTINCT aggregate function.
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldName | String | The field name to count distinct values |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<AggregateResult> results = QRY_Builder.selectFrom(Contact.SObjectType)
.groupBy(Contact.AccountId)
.countDistinct('Email')
.toList();cube
global QRY_Builder.Builder cube()Flags the GROUP BY clause as CUBE for cross-tabulation.
Returns QRY_Builder.Builder — Builder for chaining
Example
List<QRY_Builder.AggregateRow> results = QRY_Builder.selectFrom(Opportunity.SObjectType)
.groupBy(Opportunity.StageName)
.groupBy(Opportunity.LeadSource)
.sum(Opportunity.Amount)
.cube()
.toAggregateList();descending
global QRY_Builder.Builder descending()Sets the last ORDER BY clause to DESCENDING.
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.orderBy(Account.CreatedDate).descending()
.toList();exists
global Boolean exists()Checks whether any records exist matching the query criteria.
Returns Boolean — Boolean true if at least one record exists
Example
Boolean hasCustomers = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Type).equals('Customer')
.exists();fields
global QRY_Builder.Builder fields(List<SObjectField> objectFields)Explicitly select fields using SObjectField tokens.
Parameters
| Parameter | Type | Description |
|---|---|---|
objectFields | List | List of SObjectField tokens |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.fields(new List<SObjectField>{Account.Name, Account.Industry})
.toList();global QRY_Builder.Builder fields(List<String> fieldNames)Explicitly select fields by API name.
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldNames | List | List of field API names |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.fields(new List<String>{'Name', 'Industry', 'AnnualRevenue'})
.toList();fieldSet
global QRY_Builder.Builder fieldSet(FieldSet aFieldset)Selects fields from a FieldSet token.
Parameters
| Parameter | Type | Description |
|---|---|---|
aFieldset | FieldSet | The Schema.FieldSet token |
Returns QRY_Builder.Builder — Builder for chaining
Example
FieldSet fs = SObjectType.Account.fieldSets.Account_Summary;
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.fieldSet(fs)
.toList();global QRY_Builder.Builder fieldSet(String fieldSetName)Selects fields from a FieldSet.
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldSetName | String | The API Name of the FieldSet |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.fieldSet('Account_Summary')
.toList();forcePerformanceLogging
global QRY_Builder.Builder forcePerformanceLogging()Forces performance logging regardless of threshold for this query.
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.forcePerformanceLogging()
.toList();forReference
global QRY_Builder.Builder forReference()Locks returned records FOR REFERENCE.
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Id).equals(accountId)
.forReference()
.toList();forUpdate
global QRY_Builder.Builder forUpdate()Locks returned records FOR UPDATE.
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Id).equals(accountId)
.forUpdate()
.toList();forView
global QRY_Builder.Builder forView()Locks returned records FOR VIEW.
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Id).equals(accountId)
.forView()
.toList();getDefaultFields
global virtual Set<String> getDefaultFields()Override to provide default fields for this selector.
Returns String — Set of field API names
Example
public override Set<String> getDefaultFields()
{
return new Set<String>{'Name', 'Industry', 'Type'};
}getFirst
global SObject getFirst()Executes the query and returns the first record (or null).
Returns SObject — Single SObject or null
Example
Account account = (Account)QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Id).equals(accountId)
.getFirst();getFirstAggregate
global QRY_Builder.AggregateRow getFirstAggregate()Executes an aggregate query and returns the first result as a typed AggregateRow. Convenience method for single-row aggregates (e.g., SUM without GROUP BY).
Returns QRY_Builder.AggregateRow — Single AggregateRow or null if no results
Example
QRY_Builder.AggregateRow row = QRY_Builder.selectFrom(Opportunity.SObjectType)
.sum('Amount')
.getFirstAggregate();
Decimal totalAmount = row.getDecimal('expr0');getPage
global QRY_Builder.QueryPage getPage(Integer requestedPageNumber, Integer requestedPageSize)Executes a paged query and returns results with pagination metadata.
Parameters
| Parameter | Type | Description |
|---|---|---|
requestedPageNumber | Integer | The page number to retrieve (1-based) |
requestedPageSize | Integer | Number of records per page |
Returns QRY_Builder.QueryPage — Page containing records and pagination metadata
Example
QRY_Builder.QueryPage page = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Type).equals('Customer')
.orderBy(Account.Name).ascending()
.getPage(2, 25);getRandomItem
global SObject getRandomItem()Returns a single random record matching the query criteria.
Returns SObject — Single random SObject or null
Example
Account random = (Account)QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Type).equals('Customer')
.getRandomItem();getRandomItems
global List<SObject> getRandomItems(Integer randomCount)Returns multiple random records matching the query criteria. Uses a Database.Cursor to fetch records at a random offset, eliminating the 2,000 SOQL OFFSET limitation. Supports random selection across the full result set (up to 50 million records).
When mocks are active, falls back to standard SOQL OFFSET (capped at 2,000).
Parameters
| Parameter | Type | Description |
|---|---|---|
randomCount | Integer | Maximum number of random records to return |
Returns SObject — List of random SObjects
Example
List<Account> randoms = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Type).equals('Customer')
.getRandomItems(5);groupBy
global virtual QRY_Builder.Builder groupBy(QRY_Function functionField)Adds a SOQL date-function expression to the GROUP BY clause (e.g. CALENDAR_MONTH(CloseDate)), bucketing records by that date part. Use the same QRY_Function factory in addField to project the bucket.
Parameters
| Parameter | Type | Description |
|---|---|---|
functionField | QRY_Function | The date-function expression, from a QRY_Function factory |
Returns QRY_Builder.Builder — Builder for chaining
Example
QRY_Builder.selectFrom(Opportunity.SObjectType)
.addField(QRY_Function.calendarMonth(Opportunity.CloseDate), 'closeMonth')
.count('Id')
.groupBy(QRY_Function.calendarMonth(Opportunity.CloseDate))
.toAggregateList();global QRY_Builder.Builder groupBy(SObjectField groupField)Adds a field to the GROUP BY clause using an SObjectField token. Call multiple times for multi-field grouping (max 3 per SOQL spec).
Parameters
| Parameter | Type | Description |
|---|---|---|
groupField | SObjectField | The field to group by |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<QRY_Builder.AggregateRow> results = QRY_Builder.selectFrom(Account.SObjectType)
.groupBy(Account.Industry)
.groupBy(Account.Rating)
.count('Id')
.toAggregateList();global QRY_Builder.Builder groupBy(String groupField)Adds a GROUP BY clause.
Parameters
| Parameter | Type | Description |
|---|---|---|
groupField | String | The field to group by |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<AggregateResult> results = QRY_Builder.selectFrom(Account.SObjectType)
.groupBy('Industry')
.count('Id')
.toList();grouping
global QRY_Builder.Builder grouping(SObjectField field)Adds a GROUPING(field) expression to the SELECT clause for use with ROLLUP or CUBE. Returns 1 for subtotal rows and 0 for regular data rows.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field to wrap in GROUPING() |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<QRY_Builder.AggregateRow> results = QRY_Builder.selectFrom(Opportunity.SObjectType)
.groupBy(Opportunity.StageName)
.grouping(Opportunity.StageName)
.sum(Opportunity.Amount)
.rollup()
.toAggregateList();global QRY_Builder.Builder grouping(String fieldName)Adds a GROUPING(field) expression to the SELECT clause by field name.
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldName | String | The field API name to wrap in GROUPING() |
Returns QRY_Builder.Builder — Builder for chaining
Example
.groupBy('Industry').grouping('Industry').rollup()havingAvgOf
global QRY_Builder.ConditionBuilder havingAvgOf(SObjectField field)Starts a HAVING condition on the AVG of a field.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field to aggregate |
Returns QRY_Builder.ConditionBuilder — ConditionBuilder configured for HAVING
Example
List<AggregateResult> results = QRY_Builder.selectFrom(Opportunity.SObjectType)
.groupBy(Opportunity.AccountId)
.avg(Opportunity.Amount)
.havingAvgOf(Opportunity.Amount).greaterThan(50000)
.toList();havingCount
global QRY_Builder.ConditionBuilder havingCount()Starts a HAVING condition on the global COUNT().
Returns QRY_Builder.ConditionBuilder — ConditionBuilder configured for HAVING
Example
List<AggregateResult> results = QRY_Builder.selectFrom(Contact.SObjectType)
.groupBy(Contact.AccountId)
.count('Id')
.havingCount().greaterThan(5)
.toList();havingCountOf
global QRY_Builder.ConditionBuilder havingCountOf(SObjectField field)Starts a HAVING condition on the COUNT of a field.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field to count |
Returns QRY_Builder.ConditionBuilder — ConditionBuilder configured for HAVING
Example
List<AggregateResult> results = QRY_Builder.selectFrom(Contact.SObjectType)
.groupBy(Contact.AccountId)
.count('Id')
.havingCountOf(Contact.Id).greaterThan(10)
.toList();havingMaxOf
global QRY_Builder.ConditionBuilder havingMaxOf(SObjectField field)Starts a HAVING condition on the MAX of a field.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field to aggregate |
Returns QRY_Builder.ConditionBuilder — ConditionBuilder configured for HAVING
Example
List<AggregateResult> results = QRY_Builder.selectFrom(Opportunity.SObjectType)
.groupBy(Opportunity.AccountId)
.max(Opportunity.Amount)
.havingMaxOf(Opportunity.Amount).lessThan(1000000)
.toList();havingMinOf
global QRY_Builder.ConditionBuilder havingMinOf(SObjectField field)Starts a HAVING condition on the MIN of a field.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field to aggregate |
Returns QRY_Builder.ConditionBuilder — ConditionBuilder configured for HAVING
Example
List<AggregateResult> results = QRY_Builder.selectFrom(Opportunity.SObjectType)
.groupBy(Opportunity.AccountId)
.min(Opportunity.Amount)
.havingMinOf(Opportunity.Amount).greaterThan(1000)
.toList();havingSumOf
global QRY_Builder.ConditionBuilder havingSumOf(SObjectField field)Starts a HAVING condition on the SUM of a field.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field to aggregate |
Returns QRY_Builder.ConditionBuilder — ConditionBuilder configured for HAVING
Example
List<AggregateResult> results = QRY_Builder.selectFrom(Opportunity.SObjectType)
.groupBy(Opportunity.AccountId)
.sum(Opportunity.Amount)
.havingSumOf(Opportunity.Amount).greaterThan(100000)
.toList();isCached
global Boolean isCached()Indicates whether the last execution retrieved results from cache.
Returns Boolean — true if results came from cache
Example
QRY_Builder.Builder query = QRY_Builder.selectFrom(Account.SObjectType).withCache(300);
List<SObject> results = query.toList();
Boolean fromCache = query.isCached();logPerformanceIfSlowerThan
global QRY_Builder.Builder logPerformanceIfSlowerThan(Integer thresholdMs)Sets a custom performance threshold for this query. The query will be logged only if duration exceeds this threshold.
Parameters
| Parameter | Type | Description |
|---|---|---|
thresholdMs | Integer | Custom threshold in milliseconds |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.logPerformanceIfSlowerThan(500)
.toList();max
global QRY_Builder.Builder max(SObjectField field)Applies a MAX aggregate function.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field to aggregate |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<AggregateResult> results = QRY_Builder.selectFrom(Opportunity.SObjectType)
.groupBy(Opportunity.StageName)
.max(Opportunity.Amount)
.toList();global virtual QRY_Builder.Builder max(SObjectField field, String alias)Applies a MAX aggregate under an explicit result alias. Aliased aggregates accumulate, so one query folds several aggregates and reads each back by its alias.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field to take the maximum of |
alias | String | The result alias; must be a bare identifier, unique across the aliased selections |
Returns QRY_Builder.Builder — Builder for chaining
Throws
| Exception | Description |
|---|---|
| IllegalArgumentException | if alias is not a bare identifier (a letter followed by letters, digits or underscores); or, when the query builds, if the alias duplicates an earlier aliased selection |
Example
.max(Opportunity.CreatedDate, 'lastSeen')min
global QRY_Builder.Builder min(SObjectField field)Applies a MIN aggregate function.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field to aggregate |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<AggregateResult> results = QRY_Builder.selectFrom(Opportunity.SObjectType)
.groupBy(Opportunity.StageName)
.min(Opportunity.CloseDate)
.toList();global virtual QRY_Builder.Builder min(SObjectField field, String alias)Applies a MIN aggregate under an explicit result alias. Aliased aggregates accumulate, so one query folds several aggregates and reads each back by its alias.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field to take the minimum of |
alias | String | The result alias; must be a bare identifier, unique across the aliased selections |
Returns QRY_Builder.Builder — Builder for chaining
Throws
| Exception | Description |
|---|---|
| IllegalArgumentException | if alias is not a bare identifier (a letter followed by letters, digits or underscores); or, when the query builds, if the alias duplicates an earlier aliased selection |
Example
.min(Opportunity.CreatedDate, 'firstSeen')nullsFirst
global QRY_Builder.Builder nullsFirst()Sets the last ORDER BY clause to NULLS FIRST.
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.orderBy(Account.Industry).ascending().nullsFirst()
.toList();nullsLast
global QRY_Builder.Builder nullsLast()Sets the last ORDER BY clause to NULLS LAST.
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.orderBy(Account.Industry).ascending().nullsLast()
.toList();orCondition
global virtual QRY_Builder.ConditionBuilder orCondition(QRY_Function functionField)Starts an OR condition whose left-hand side is a SOQL function expression (for example a geolocation DISTANCE from QRY_Function.distanceInMiles). Mirrors orCondition(SObjectField) for function expressions.
Parameters
| Parameter | Type | Description |
|---|---|---|
functionField | QRY_Function | The function expression, from a QRY_Function factory |
Returns QRY_Builder.ConditionBuilder — ConditionBuilder for specifying the operator
Example
List<Account> nearby = QRY_Builder.selectFrom(Account.SObjectType)
.condition(QRY_Function.distanceInMiles(Account.BillingAddress, 37.775, -122.418)).lessThan(10)
.orCondition(QRY_Function.distanceInMiles(Account.ShippingAddress, 37.775, -122.418)).lessThan(10)
.toList();global QRY_Builder.ConditionBuilder orCondition(SObjectField field)Starts an OR condition on a field using an SObjectField token.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | Field token |
Returns QRY_Builder.ConditionBuilder — ConditionBuilder for specifying the operator
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Industry).equals('Technology')
.orCondition(Account.Industry).equals('Finance')
.toList();global QRY_Builder.ConditionBuilder orCondition(String fieldName)Starts an OR condition on a field using its API name.
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldName | String | Field API name |
Returns QRY_Builder.ConditionBuilder — ConditionBuilder for specifying the operator
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.condition('Industry').equals('Technology')
.orCondition('Industry').equals('Finance')
.toList();orderBy
global virtual QRY_Builder.Builder orderBy(QRY_Function functionField)Orders by a SOQL date-function expression, ascending (e.g. ORDER BY CALENDAR_MONTH(CloseDate)).
Parameters
| Parameter | Type | Description |
|---|---|---|
functionField | QRY_Function | The date-function expression, from a QRY_Function factory |
Returns QRY_Builder.Builder — Builder for chaining
Example
.orderBy(QRY_Function.calendarMonth(Opportunity.CloseDate))global virtual QRY_Builder.Builder orderBy(QRY_Function functionField, Boolean sortDescending)Orders by a SOQL date-function expression, ascending or descending.
Parameters
| Parameter | Type | Description |
|---|---|---|
functionField | QRY_Function | The date-function expression, from a QRY_Function factory |
sortDescending | Boolean | When true, sorts DESCENDING; otherwise ASCENDING |
Returns QRY_Builder.Builder — Builder for chaining
Example
.orderBy(QRY_Function.calendarMonth(Opportunity.CloseDate), true)global QRY_Builder.Builder orderBy(SObjectField field)Adds an ORDER BY clause (default ascending).
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | Field token to sort by |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.orderBy(Account.Name).ascending()
.toList();global QRY_Builder.Builder orderBy(SObjectField field, Boolean sortDescending)Adds an ORDER BY clause with a dynamic sort direction. Nulls placement defaults to standard SOQL behavior (NULLS FIRST for ASC, NULLS LAST for DESC).
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | Field token to sort by |
sortDescending | Boolean | When true, sorts DESCENDING; otherwise ASCENDING |
Returns QRY_Builder.Builder — Builder for chaining
Example
Boolean isDescending = true;
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.orderBy(Account.Name, isDescending)
.toList();global QRY_Builder.Builder orderBy(SObjectField field, Boolean sortDescending, Boolean nullsLast)Adds an ORDER BY clause with a dynamic sort direction and nulls placement.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | Field token to sort by |
sortDescending | Boolean | When true, sorts DESCENDING; otherwise ASCENDING |
nullsLast | Boolean | When true, places nulls last; otherwise places nulls first |
Returns QRY_Builder.Builder — Builder for chaining
Example
Boolean isDescending = true;
Boolean isNullsLast = true;
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.orderBy(Account.Name, isDescending, isNullsLast)
.toList();global QRY_Builder.Builder orderBy(String fieldName)Adds an ORDER BY clause (default ascending).
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldName | String | Field API name to sort by |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.orderBy('CreatedDate').descending()
.toList();global QRY_Builder.Builder orderBy(String fieldName, Boolean sortDescending)Adds an ORDER BY clause with a dynamic sort direction. Nulls placement defaults to standard SOQL behavior (NULLS FIRST for ASC, NULLS LAST for DESC).
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldName | String | Field API name to sort by |
sortDescending | Boolean | When true, sorts DESCENDING; otherwise ASCENDING |
Returns QRY_Builder.Builder — Builder for chaining
Example
Boolean isDescending = false;
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.orderBy('CreatedDate', isDescending)
.toList();global QRY_Builder.Builder orderBy(String fieldName, Boolean sortDescending, Boolean nullsLast)Adds an ORDER BY clause with a dynamic sort direction and nulls placement.
Parameters
| Parameter | Type | Description |
|---|---|---|
fieldName | String | Field API name to sort by |
sortDescending | Boolean | When true, sorts DESCENDING; otherwise ASCENDING |
nullsLast | Boolean | When true, places nulls last; otherwise places nulls first |
Returns QRY_Builder.Builder — Builder for chaining
Example
Boolean isDescending = true;
Boolean isNullsLast = false;
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.orderBy('CreatedDate', isDescending, isNullsLast)
.toList();orderByCount
global virtual QRY_Builder.Builder orderByCount(SObjectField field, Boolean sortDescending)Orders an aggregate query by COUNT of a field (e.g. ORDER BY COUNT(Id) DESC), the SOQL form for ranking grouped rows by how many records each group holds — a top-N-groups read combines this with withLimit. No NULLS clause is emitted: COUNT never yields null groups.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field whose COUNT orders the grouped rows |
sortDescending | Boolean | When true, sorts DESCENDING (largest groups first); otherwise ASCENDING |
Returns QRY_Builder.Builder — Builder for chaining
Throws
| Exception | Description |
|---|---|
| IllegalArgumentException | if field is null |
Example
List<QRY_Builder.AggregateRow> topSources = QRY_Builder.selectFrom(Opportunity.SObjectType)
.groupBy(Opportunity.StageName)
.count(Opportunity.Id, 'rowTotal')
.orderByCount(Opportunity.Id, true)
.withLimit(3)
.toAggregateList();relatedField
global QRY_Builder.Builder relatedField(String parentField)Adds a single parent field.
Parameters
| Parameter | Type | Description |
|---|---|---|
parentField | String | Field path (e.g., 'Account.Owner.Name') |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Contact> contacts = QRY_Builder.selectFrom(Contact.SObjectType)
.relatedField('Account.Owner.Name')
.toList();relatedFields
global QRY_Builder.Builder relatedFields(List<String> parentFields)Adds parent (related) fields to the selection.
Parameters
| Parameter | Type | Description |
|---|---|---|
parentFields | List | List of field paths (e.g., 'Account.Name') |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Contact> contacts = QRY_Builder.selectFrom(Contact.SObjectType)
.relatedFields(new List<String>{'Account.Name', 'Account.Industry'})
.toList();rollup
global QRY_Builder.Builder rollup()Flags the GROUP BY clause as ROLLUP for subtotals.
Returns QRY_Builder.Builder — Builder for chaining
Example
List<QRY_Builder.AggregateRow> results = QRY_Builder.selectFrom(Opportunity.SObjectType)
.groupBy(Opportunity.StageName)
.groupBy(Opportunity.AccountId)
.sum(Opportunity.Amount)
.rollup()
.toAggregateList();selectAllFields
global QRY_Builder.Builder selectAllFields()Configures the query to select ALL fields on the object.
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.selectAllFields()
.withLimit(10)
.toList();stripInaccessible
global QRY_Builder.Builder stripInaccessible()Strips inaccessible fields from results.
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.stripInaccessible()
.toList();subselect
global QRY_Builder.Builder subselect(QRY_Builder.Builder childQuery, String relationshipName)Adds a child subquery (child relationship query).
Parameters
| Parameter | Type | Description |
|---|---|---|
childQuery | QRY_Builder.Builder | Configured Builder for the child object |
relationshipName | String | The child relationship API name (e.g., 'Contacts') |
Returns QRY_Builder.Builder — Builder for chaining
Example
QRY_Builder.Builder contactQuery = new QRY_Builder.Builder(Contact.SObjectType)
.fields(new List<SObjectField>{Contact.FirstName, Contact.LastName});
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.subselect(contactQuery, 'Contacts')
.toList();sum
global QRY_Builder.Builder sum(SObjectField field)Applies a SUM aggregate function.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field to aggregate |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<AggregateResult> results = QRY_Builder.selectFrom(Opportunity.SObjectType)
.groupBy(Opportunity.StageName)
.sum(Opportunity.Amount)
.toList();global virtual QRY_Builder.Builder sum(SObjectField field, String alias)Applies a SUM aggregate under an explicit result alias. Aliased aggregates accumulate, so one query folds several aggregates and reads each back by its alias.
Parameters
| Parameter | Type | Description |
|---|---|---|
field | SObjectField | The field to sum |
alias | String | The result alias; must be a bare identifier, unique across the aliased selections |
Returns QRY_Builder.Builder — Builder for chaining
Throws
| Exception | Description |
|---|---|
| IllegalArgumentException | if alias is not a bare identifier (a letter followed by letters, digits or underscores); or, when the query builds, if the alias duplicates an earlier aliased selection |
Example
.sum(Opportunity.Amount, 'pipelineTotal')suppressPerformanceLogging
global QRY_Builder.Builder suppressPerformanceLogging()Suppresses performance logging for this query.
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.suppressPerformanceLogging()
.toList();toAggregateList
global List<QRY_Builder.AggregateRow> toAggregateList()Executes an aggregate query and returns results as typed AggregateRow wrappers. Use with aggregate methods like count(), sum(), avg(), min(), max() and groupBy().
Returns QRY_Builder.AggregateRow — List of AggregateRow wrappers
Example
List<QRY_Builder.AggregateRow> rows = QRY_Builder.selectFrom(Account.SObjectType)
.count('Id')
.groupBy('Industry')
.toAggregateList();
for(QRY_Builder.AggregateRow row : rows)
{
System.debug(row.getString('Industry') + ': ' + row.getInteger('expr0'));
}toCursor
global Database.Cursor toCursor()Returns a Database.Cursor for large data set traversal.
Returns Database.Cursor — Database.Cursor
Example
Database.Cursor cursor = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Type).equals('Customer')
.toCursor();toList
global List<SObject> toList()Executes the query and returns a List of SObjects.
Returns SObject — List results
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Industry).equals('Technology')
.toList();toQueryLocator
global Database.QueryLocator toQueryLocator()Returns a Database.QueryLocator for batch processing.
Returns Database.QueryLocator — Database.QueryLocator
Example
Database.QueryLocator locator = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Type).equals('Customer')
.toQueryLocator();toSoql
global String toSoql()Generates and returns the SOQL string without executing it.
Returns String — The built SOQL query string
Example
String soql = QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Industry).equals('Technology')
.toSoql();usingScope
global QRY_Builder.Builder usingScope(QRY_Builder.Scope scopeValue)Filters records by visibility scope using USING SCOPE clause.
Parameters
| Parameter | Type | Description |
|---|---|---|
scopeValue | QRY_Builder.Scope | The scope to apply |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.usingScope(QRY_Builder.Scope.MINE)
.toList();withCache
global QRY_Builder.Builder withCache(Integer ttlSeconds)Enables platform caching for this query.
Parameters
| Parameter | Type | Description |
|---|---|---|
ttlSeconds | Integer | Time-to-live in seconds |
Returns QRY_Builder.Builder — Builder for chaining
Example
Account account = (Account)QRY_Builder.selectFrom(Account.SObjectType)
.condition(Account.Id).equals(accountId)
.withCache(300)
.getFirst();withDataCategory
global QRY_Builder.DataCategoryBuilder withDataCategory(String groupName)Starts a WITH DATA CATEGORY filter for the specified data category group.
Parameters
| Parameter | Type | Description |
|---|---|---|
groupName | String | The data category group API name |
Returns QRY_Builder.DataCategoryBuilder — DataCategoryBuilder for operator selection
Throws
| Exception | Description |
|---|---|
| IllegalArgumentException | if groupName is blank |
Example
List<SObject> articles = QRY_Builder.selectFrom(KnowledgeArticleVersion.SObjectType)
.fields(new List<String>{'Id', 'Title'})
.condition('PublishStatus').equals('Online')
.withDataCategory('Geography__c').at('USA__c')
.withDataCategory('Product__c').below('Electronics__c')
.toList();withLimit
global QRY_Builder.Builder withLimit(Integer recordLimit)Sets the maximum number of records to return (LIMIT).
Parameters
| Parameter | Type | Description |
|---|---|---|
recordLimit | Integer | Maximum number of records |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.withLimit(100)
.toList();withOffset
global QRY_Builder.Builder withOffset(Integer rowNumber)Sets the record offset (OFFSET).
Parameters
| Parameter | Type | Description |
|---|---|---|
rowNumber | Integer | Number of records to skip |
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.withLimit(25)
.withOffset(50)
.toList();withoutSecurity
global QRY_Builder.Builder withoutSecurity()Disables all security enforcement.
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.withoutSecurity()
.toList();withSharing
global QRY_Builder.Builder withSharing()Enforces sharing rules using a with sharing proxy class.
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.withSharing()
.toList();withSystemMode
global QRY_Builder.Builder withSystemMode()Forces SYSTEM_MODE execution regardless of the UserModeQueries_Enabled feature flag. Framework-internal queries that read CMDT, framework-owned sObjects, or system-schema tables must use this method so they continue working when the subscriber's running user lacks FLS/CRUD on those objects by design.
Returns QRY_Builder.Builder — Builder for chaining
Example
TriggerSetting__mdt setting = (TriggerSetting__mdt)QRY_Builder.selectFrom(TriggerSetting__mdt.SObjectType)
.withSystemMode()
.condition(TriggerSetting__mdt.SObjectType__c).equals('Account')
.getFirst();withUserMode
global QRY_Builder.Builder withUserMode()Runs the query in USER_MODE.
Returns QRY_Builder.Builder — Builder for chaining
Example
List<Account> accounts = QRY_Builder.selectFrom(Account.SObjectType)
.withUserMode()
.toList();Constructors
| Constructor | Description |
|---|---|
| global Builder() | Default constructor. |
| global Builder(SObjectType sObjectType) | Constructor that sets the SObject type. |
Builder()
global Builder()Default constructor.
Example
QRY_Builder.Builder query = new QRY_Builder.Builder();Builder(SObjectType sObjectType)
global Builder(SObjectType sObjectType)Constructor that sets the SObject type.
Parameters
| Parameter | Type | Description |
|---|---|---|
sObjectType | SObjectType | The SObject to query |
Example
QRY_Builder.Builder query = new QRY_Builder.Builder(Account.SObjectType);Properties
| Property | Description |
|---|---|
| global SObjectType objectType | The SObjectType being queried by this builder. |
objectType
global SObjectType objectTypeType: SObjectType
The SObjectType being queried by this builder.