Force-Framework

QueryV1

global with sharing class QueryV1

Description	Class providing Query API. See README for full details of the Query API. Copyright (c) 2025 Mark Brennand, released under MIT License.
Author	Mark Brennand

Description

Class providing Query API.

See README for full details of the Query API.

Author

Mark Brennand

Methods

aggregatedField

global static QueryV1.AggregatedField aggregatedField(final SObjectField field, final String alias)

Description	Builds a field which may be used to aggregate data in a query.
Parameter	field: The field to aggregate the results by.
Parameter	alias: The AggregateResult records returned will have the value keyed by the alias.
Returns	An aggregate field which can be used in the query.

aggregatedField

global static QueryV1.AggregatedField aggregatedField(final SObjectField joinField, final SObjectField field, final String alias)

Description	Builds a field from a related object which may be used to aggregate data in a query.
Parameter	joinField: The field which links the related object.
Parameter	field: The field in the related object to aggregate the results by.
Parameter	alias: The AggregateResult records returned will have the value keyed by the alias.
Returns	An aggregate field which can be used in the query.

aggregatedField

global static QueryV1.AggregatedField aggregatedField(final String function, final SObjectField field, final String alias)

Description	Builds a field from a related object which may be used to aggregate data in a query.
Parameter	function: The aggregation function to use, e.g. COUNT or SUM.
Parameter	field: The field in the related object to aggregate the results by.
Parameter	alias: The AggregateResult records returned will have the value keyed by the alias.
Returns	An aggregate field which can be used in the query.

aggregatedField

global static QueryV1.AggregatedField aggregatedField(final String function, final SObjectField joinField, final SObjectField field, final String alias)

Description	Builds a field from a related object which may be used to aggregate data in a query.
Parameter	function: The aggregation function to use, e.g. COUNT or SUM.
Parameter	joinField: The field which links the related object.
Parameter	field: The field in the related object to aggregate the results by.
Parameter	alias: The AggregateResult records returned will have the value keyed by the alias.
Returns	An aggregate field which can be used in the query.

ascending

global static QueryV1.Order ascending(final SObjectField field)

Description	Creates an ordering to add to the query for the given field in ascending value.
Parameter	field: The field to be ordered.
Returns	The ordering tgo add to the query.

ascending

global static QueryV1.Order ascending(final SObjectField joinField, final SObjectField field)

Description	Creates an ordering to add to the query for the given field in ascending order from a related object.
Parameter	joinField: The Id field of the related related object containing the field to order.
Parameter	field: The field to be ordered.
Returns	The ordering tgo add to the query.

ascending

global static QueryV1.Order ascending(final AggregatedField field)

Description	Creates an ordering to add to the query for the given aggregated field in ascending value.
Parameter	field: The aggregated field to be ordered.
Returns	The ordering tgo add to the query.

count

global static QueryV1.API count(final SObjectType type)

Description	Creates an instance of the Query API to perform a count of the given object.
Parameter	type: The object to be counted.
Returns	The Query API instance.

descending

global static QueryV1.Order descending(final SObjectField field)

Description	Creates an ordering to add to the query for the given field in descending value.
Parameter	field: The field to be ordered.
Returns	The ordering tgo add to the query.

descending

global static QueryV1.Order descending(final SObjectField joinField, final SObjectField field)

Description	Creates an ordering to add to the query for the given field in descending order from a related object.
Parameter	joinField: The Id field of the related related object containing the field to order.
Parameter	field: The field to be ordered.
Returns	The ordering tgo add to the query.

descending

global static QueryV1.Order descending(final AggregatedField field)

Description	Creates an ordering to add to the query for the given aggregated field in descending value.
Parameter	field: The aggregated field to be ordered.
Returns	The ordering tgo add to the query.

of

global static QueryV1.API of(final SObjectType type)

Description	Creates an instance of the Query API to query the given object.
Parameter	type: The object to be queried.
Returns	The Query API instance.

QueryV1.AggregatedField

global interface AggregatedField

Description	Implementation dependent representation of an aggregated field.

QueryV1.Order

global interface Order

Description	Representation of an SOQL order clause.

Methods

getField

String getField()

Description	Returns the field that the results will be ordered by.
Returns	The field to be ordered by.

isAscending

Boolean isAscending()

Description	Returns true if the results are to be ordered in ascending value, false if descending.
Returns	True is the results are returned in ascending order, false if descending.

isNullsFirst

OptionalV1 isNullsFirst()

Description	Returns an OptionalV1 representing whether null values for the associated field are to be included in the results at the start or end. If the return value is not set in the OptionalV1, then the default null ordering is being used. Otherwise, a value of true indicates null values will be returned first and false indicates last.
Returns	An OptionalV1 representing the ordering of null values.

Description

Returns an OptionalV1 representing whether null values for the associated field are to be included in the results at the start or end.

If the return value is not set in the OptionalV1, then the default null ordering is being used.

Otherwise, a value of true indicates null values will be returned first and false indicates last.

Returns

An OptionalV1 representing the ordering of null values.

nullsFirst

QueryV1.Order nullsFirst()

Description	Sets the result ordering to null values first.
Returns	The current instance for method chaining.

nullsLast

QueryV1.Order nullsLast()

Description	Sets the result ordering to null values last.
Returns	The current instance for method chaining.

QueryV1.API

global interface API

Description	Interface defining the actions required for querying. A new implementation of the Query API must implement all the methods of this interface. It can then add a Dependency Injection Binding to inject it as the implementation used in the QueryAPI class.

Description

Interface defining the actions required for querying.

A new implementation of the Query API must implement all the methods of this interface. It can then add a Dependency Injection Binding to inject it as the implementation used in the QueryAPI class.

Methods

bindings

QueryV1.API bindings(final Map<String, Object> values)

Description	Sets the bind variables to be used in the query set by the matching() method.
Parameter	values: The bind variables.
Returns	The current instance for method chaining.

count

QueryV1.API count()

Description	Marks the query as a count. The OptionalV1 returned by the execute method will contain an Integer with the result.
Returns	The current instance for method chaining.

Description

Marks the query as a count.

The OptionalV1 returned by the execute method will contain an Integer with the result.

Returns

The current instance for method chaining.

execute

OptionalV1 execute()

Description	Executes the query. The Optional returned will have no value if there are no matching objects. If there are matches, the Optional value will be an ImmutableV1.Collection containing the matching objects.
Returns	The results.

Description

Executes the query.

The Optional returned will have no value if there are no matching objects. If there are matches, the Optional value will be an ImmutableV1.Collection containing the matching objects.

Returns

The results.

group

QueryV1.API group(final Set<SObjectField> fields)

Description	For an aggregated query, sets the fields to group the results by. The grouping is determined by the accumulation of all the group calls.
Parameter	fields: The fields to group the results by.
Returns	The current instance for method chaining.

Description

For an aggregated query, sets the fields to group the results by.

The grouping is determined by the accumulation of all the group calls.

Parameter

fields: The fields to group the results by.

Returns

The current instance for method chaining.

group

QueryV1.API group(final SObjectField joinField, final Set<SObjectField> fields)

Description	For an aggregated query, sets the fields in a related object to group the results by. The grouping is determined by the accumulation of all the group calls.
Parameter	joinField: The Id field in the object being queried that links to the related object.
Parameter	fields: The fields to group the results by.
Returns	The current instance for method chaining.

has

QueryV1.API has(final String condition)

Description	Method to set the has condition for an aggregate query.
Parameter	condition: The condition to be set.
Returns	The current instance for method chaining.

matching

QueryV1.API matching(final String condition)

Description	Sets the WHERE clause for the query. The condition may include bind variables. The Map passed to the execute method must include a definition for each bind variable in the condition.
Parameter	condition: The query WHERE clause.
Returns	The current instance for method chaining.

Description

Sets the WHERE clause for the query.

The condition may include bind variables. The Map passed to the execute method must include a definition for each bind variable in the condition.

Parameter

condition: The query WHERE clause.

Returns

The current instance for method chaining.

max

QueryV1.API max(final Integer max)

Description	Sets the maximum number of records to be returned by the query.
Parameter	max: The maximum number of records.
Returns	The current instance for method chaining.

offset

QueryV1.API offset(final Integer offset)

Description	Sets the offset to the first record to be returned by the query.
Parameter	offset: The offset to the first record.
Returns	The current instance for method chaining.

ordered

QueryV1.API ordered(final QueryV1.Order order)

Description	Adds a result ordering to the query. The result ordering is determined by the accumulation of all the ordered calls.
Parameter	order: The result order to add to the query.
Returns	The current instance for method chaining.

Description

Adds a result ordering to the query.

The result ordering is determined by the accumulation of all the ordered calls.

Parameter

order: The result order to add to the query.

Returns

The current instance for method chaining.

ordered

QueryV1.API ordered(final Set<QueryV1.Order> order)

Description	Adds result orderings to the query. The result ordering is determined by the accumulation of all the ordered calls.
Parameter	order: The result orders to add to the query.
Returns	The current instance for method chaining.

Description

Adds result orderings to the query.

The result ordering is determined by the accumulation of all the ordered calls.

Parameter

order: The result orders to add to the query.

Returns

The current instance for method chaining.

returning

QueryV1.API returning(final SObjectField field)

Description	Adds the given field to the fields to be returned by the query. The fields to be returned are accumulated from all the calls to the returning methods.
Parameter	field: The field to return.
Returns	The current instance for method chaining.

Description

Adds the given field to the fields to be returned by the query.

The fields to be returned are accumulated from all the calls to the returning methods.

Parameter

field: The field to return.

Returns

The current instance for method chaining.

returning

QueryV1.API returning(final Set<SObjectField> fields)

Description	Adds the given fields to the fields to be returned by the query. The fields to be returned are accumulated from all the calls to the returning methods.
Parameter	fields: The fields to return.
Returns	The current instance for method chaining.

Description

Adds the given fields to the fields to be returned by the query.

The fields to be returned are accumulated from all the calls to the returning methods.

Parameter

fields: The fields to return.

Returns

The current instance for method chaining.

returning

QueryV1.API returning(final SObjectField joinField, final Set<SObjectField> fields)

Description	Adds the given fields from a related object to the fields to be returned by the query. The fields to be returned are accumulated from all the calls to the returning methods.
Parameter	joinField: The Id field in the object being queried that links to the related object.
Parameter	fields: The fields to return.
Returns	The current instance for method chaining.

returning

QueryV1.API returning(final QueryV1.API query)

Description	Adds the given sub query to the fields. The SObjectType of the sub query is used to determine the child relationship(s) from the object being queried to the object associated with the sub query. A query field is added to the query for each child relationship. The fields to be returned are accumulated from all the calls to the returning methods.
Parameter	query: The sub query.
Returns	The current instance for method chaining.

Description

Adds the given sub query to the fields.

The SObjectType of the sub query is used to determine the child relationship(s) from the object being queried to the object associated with the sub query. A query field is added to the query for each child relationship.

The fields to be returned are accumulated from all the calls to the returning methods.

Parameter

query: The sub query.

Returns

The current instance for method chaining.

returning

QueryV1.API returning(final QueryV1.AggregatedField field)

Description	Adds the given aggregated field to the fields to be returned by the query. The fields to be returned are accumulated from all the calls to the returning methods.
Parameter	field: The aggregated field to return.
Returns	The current instance for method chaining.

Description

Adds the given aggregated field to the fields to be returned by the query.

The fields to be returned are accumulated from all the calls to the returning methods.

Parameter

field: The aggregated field to return.

Returns

The current instance for method chaining.

returning

QueryV1.API returning(final Set<QueryV1.AggregatedField> fields)

Description	Adds the given aggregated fields to the fields to be returned by the query. The fields to be returned are accumulated from all the calls to the returning methods.
Parameter	fields: The aggregated fields to return.
Returns	The current instance for method chaining.

Description

Adds the given aggregated fields to the fields to be returned by the query.

The fields to be returned are accumulated from all the calls to the returning methods.

Parameter

fields: The aggregated fields to return.

Returns

The current instance for method chaining.

returningAll

QueryV1.API returningAll()

Description	Selects all the fields in the object being queried for return. Only the fields the user has FLS read access to are returned. No fields in joined objects or child relationships are returned.
Returns	The current instance for method chaining.

Description

Selects all the fields in the object being queried for return.

Only the fields the user has FLS read access to are returned.

No fields in joined objects or child relationships are returned.

Returns

The current instance for method chaining.

security

QueryV1.API security(final AccessLevel security)

Description	Sets the access level for the query. In SYSTEM mode, no CRUD or FLS checks should be performed. In USER mode, CRUD and FLS checks must be performed.
Parameter	security: The access level for the query.
Returns	The current instance for method chaining.

Description

Sets the access level for the query.

In SYSTEM mode, no CRUD or FLS checks should be performed. In USER mode, CRUD and FLS checks must be performed.

Parameter

security: The access level for the query.

Returns

The current instance for method chaining.

type

SObjectType type()

Description	Yields the type of the object being queried.
Returns	The type of object.

type

QueryV1.API type(final SObjectType type)

Description	Sets the type of object to query.
Parameter	type: The object type.
Returns	The current instance for method chaining.