Skip to main content

Getting Started

Read about the SOQL Lib in blog post.

Deploy to Scratch Org and run tests codecov

The SOQL Lib provides functional constructs for SOQL queries in Apex.


// SELECT Id FROM Account
List<Account> accounts = SOQL.of(Account.SObjectType).toList();
// SELECT Id, Name, Industry FROM Account
List<Account> accounts = SOQL.of(Account.SObjectType)
.with(Account.Id, Account.Name, Account.Industry)


public inherited sharing class SOQL_Contact extends SOQL implements SOQL.Selector {
public static SOQL_Contact query() {
return new SOQL_Contact();

private SOQL_Contact() {
// default settings
with(Contact.Id, Contact.Name, Contact.AccountId)

public SOQL_Contact byAccountId(Id accountId) {
return this;
public with sharing class ExampleController {
public static List<Contact> getAccountContacts(Id accountId) {
return SOQL_Contact.query()


  1. Additional level of abstraction - The selector layer is an additional level of abstraction that gives you the possibility to control the execution of SOQL.
  2. Mocking - Selector classes give a possibility to mock return values in unit tests.
    • Mock external objects (__x) - External objects cannot be inserted in unit tests. You need to mock them.
    • Mock custom metadata - Custom metadata cannot be inserted in unit tests unless the developer uses the Metadata API. Mock can be a solution.
  3. Control field-level security - The best practice is to execute SOQLs WITH USER_MODE to enforce field-level security and object permissions of the running user. The selector layer can apply WITH USER_MODE by default to all of the queries, so the developer does not need to care about it. Developers can also add WITH SYSTEM_MODE to all SOQLs from a specific selector.
  4. Control sharings rules - The selector allows to execute of different methods in the same class in different sharing modes.
  5. Avoid duplicates - Generic SQOLs like getById, and getByRecordType can be stored in the selector class.
  6. Default configuration - The selector class can provide default SOQL configuration like default fields, FLS settings, and sharing rules.
  7. Mocking - The selector class has built in Mocking functionality that provides ability to dynamically return data in test execution

License notes

  • For proper license management each repository should contain LICENSE file similar to this one.
  • Each original class should contain copyright mark: Copyright (c) 2023 BeyondTheCloud.Dev