Project Q

A Dynamic SOQL Query Builder for the Force.com Platform

Installation

Unlocked Package v1.0.0

Install Unlocked Package in a Sandbox

Install Unlocked Package in Production

Manual

Deploy the Apex classes from the ./force-app/main/default/classes/ repository into your Salesforce project.

Basic Usage

Q query = new Q(Account.SObjectType)
    .selectFields(SObjectType.Account.fieldSets.Example)
    .addSubquery(new Q('Contacts'))
    .add(Q.condition('Name').isLike('%Acme%'))
    .add(Q.condition('BillingCountry').isNotNull())
    .addLimit(5);

System.debug(query.build());
// SELECT CreatedById, Description, Owner.Email, (SELECT Id FROM Contacts) FROM Account WHERE Name LIKE '%Acme%' AND BillingCountry != null LIMIT 5

While chaining methods is a convenient way to initialise your query, you also have the ability to manually build complex queries depending on specific conditions.

Q query = new Q(Contact.SObjectType).addLimit(5);

if (String.isNotBlank(firstName)) {
  query.add(Q.condition('FirstName').isEqualTo(firstName));
}

if (String.isNotBlank(lastName)) {
  query.add(Q.condition('LastName').isEqualTo(lastName));
}

System.debug(query.build());
// SELECT Id FROM Contact WHERE FirstName = 'Céline' AND LastName = 'Dion' LIMIT 5

Bind Variables

String accountName = '%Acme%';
Q query = new Q(Account.SObjectType)
    .selectFields('Id')
    .add(Q.condition('Name').isLike(Q.bindVar(':accountName')));

System.debug(query.build());
// SELECT Id FROM Account WHERE Name LIKE :accountName

Parenthetical Groups

Q query = new Q(Account.SObjectType)
    .add(Q.orGroup()
        .add(Q.condition('Name').isEqualTo('Acme 1'))
        .add(Q.condition('Name').isEqualTo('Acme 2')));

System.debug(query.build());
//SELECT Id FROM Account WHERE (Name = 'Acme 1' OR Name = 'Acme 2')

Location-Based Queries

Using a custom field as the destiation

Q query = new Q(Account.SObjectType)
    .add(Q.distanceFrom('BillingAddress').to('CustomLocationField__c').isLessThan(20));

System.debug(query.build());
//SELECT Id FROM Account WHERE DISTANCE(BillingAddress, CustomLocationField__c, 'mi') < 20

Using Latitude and Longitude as the destination

Q query = new Q(Account.SObjectType)
    .add(Q.distanceFrom('BillingAddress').to(37.775, -122.418).inKilometers().isLessThan(20))

System.debug(query.build());
//SELECT Id FROM Account WHERE DISTANCE(BillingAddress, GEOLOCATION(37.775, -122.418), 'km') < 20

Date Literals

Q query = new Q(Account.SObjectType)
    .add(Q.condition('CreatedDate').isLessThan(Q.dateLiteral(QDateLiteral.Value.LAST_N_DAYS, 7)));

System.debug(query.build());
//SELECT Id FROM Account WHERE CreatedDate < LAST_N_DAYS:7

Inner Joins

Q query = new Q(Account.SObjectType)
    .addSubquery(new Q('Contacts').selectFields(new Set<String> {'Name'}))
    .add(Q.condition('Id').isIn(new Q(Contact.SObjectType).selectFields(new Set<String> {'AccountId'})));

System.debug(query.build());
//SELECT (SELECT Name FROM Contacts) FROM Account WHERE Id IN (SELECT AccountId FROM Contact)

Polymorphic Relationships (TYPEOF)

String query = new Q(Event.SObjectType)
    .selectFields(Q.typeOf('What')
        .when('Account').then(new Set<String> {'Phone', 'NumberOfEmployees'})   
        .when('Opportunity').then(new Set<String> {'Amount', 'CloseDate'})                 
        .otherwise(new Set<String> {'Name', 'Email'})
    );
    
System.debug(query.build());
/*
SELECT
    TYPEOF What
    WHEN Account THEN Phone,NumberOfEmployees
    WHEN Opportunity THEN Amount,CloseDate
    ELSE Name,Email
    END
FROM Event
*/

Roadmap

This library is being initially developed for one of my internal project, so API methods will likely be implemented in the order that they are needed by my project. Eventually, I would like to cover the entire SOQL and SOSL query language, so contributions are of course always welcome. Adding new methods is relatively straightforward, so feel free to join the fun!

License

This library is distributed under the MIT license found in the LICENSE file.