Skip to content

Commit 33a80ed

Browse files
jongpiejongpie
authored
Summer '18 - v3 rewrite
There are now 3 builder classes (SobjectQueryBuilder, AggregateQueryBuilder & SearchBuilder) and 2 abstract classes (Soql & Sosl). * Upgraded to API v43.0 * Converted Soql.cls to an abstract class with shared logic + enums + subclasses * The old (but improved) AggregateResultQueryBuilder is back as AggregateQueryBuilder * (Re-)created SobjectQueryBuilder.cls * Polymorphic fields now have the sobject type added to the query Ex: addField(Lead.OwnerId) --> "Owner.Name, Owner.Type, OwnerId" are added to the query * Renamed includeChildrenRecords & getChildrenRecordsQuery methods * Added SearchBuilder.getSobjectTypes() * Simplified all aggregate methods into a few addAggregateField methods * Added support for rollup & dimesion groupings in aggregate queries * Renamed method useGroupingDimension to usingGroupingDimension * Added support for 'HAVING' keyword in aggregates * Added Soql.Operator enum to finally replace String operator * Added support for OR filters in the Soql builder classes * Replaced strings needed for Soql.DateLiteral with some enums * Added getFormattedValue() to Soql.QueryFilter * Added support for date functions (including convertTimeZone) in QueryField * Added AggregateQueryBuilder.getResultCount()
1 parent bedb0df commit 33a80ed

18 files changed

+1605
-732
lines changed

‎README.md‎

Lines changed: 68 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,69 +1,104 @@
1-
# Nebula Query & Search
2-
A lightweight Apex library for easily building dynamic SOQL queries & SOSL searches<br /><br />
3-
[![Travis CI](https://img.shields.io/travis/jongpie/NebulaLogger/master.svg)](https://travis-ci.org/jongpie/NebulaLogger)
1+
# Nebula Query & Search for Salesforce Apex
2+
[![Travis CI](https://img.shields.io/travis/jongpie/NebulaQueryAndSearch/master.svg)](https://travis-ci.org/jongpie/NebulaQueryAndSearch)
43

54
<a href="https://githubsfdeploy.herokuapp.com" target="_blank">
65
<img alt="Deploy to Salesforce" src="https://raw.githubusercontent.com/afawcett/githubsfdeploy/master/deploy.png">
76
</a>
87

8+
A dynamic SOQL query & SOSL search library for for Salesforce Apex<br /><br />
9+
910
## Features
10-
* Easily add a field if the field meets the category specified, using the Soql.FieldCategory enum
11-
* Easily add any fields that are accessible, updateable, standard or custom, using the Soql.FieldCategory enum
11+
* Provides chainable builder methods for dyanmically building queries & searches in APex
12+
* Easily add fields to a query based on field level security
1213
* Easily add fields from a field set
1314
* Automatically adds the parent name field for any lookup/master-detail fields
1415
* Adds translations for picklist fields & record types by calling includeLabels()
1516
* Adds localized formatting for number, date, datetime, time, or currency fields by calling includeFormattedValues()
1617
* Leverage query scope to filter results
18+
* Enable query & search caching by simple calling cacheResults()
1719
* Reuse your dynamic SOQL queries to quickly build dynamic SOSL searches
1820

19-
## SOQL Query Examples
21+
## Overview
22+
There are 3 main builder classes
23+
24+
&nbsp; | SobjectQueryBuilder | AggregateQueryBuilder | SearchBuilder
25+
------- | --------------------|-----------------------|--------------
26+
Super Class | Soql.cls (Queries) | Soql.cls (Queries) | Sosl.cls (Searches) | -
27+
Action | Queries an Sobject | Queries an Sobject | Searches 1 or more Sobjects
28+
Returns | `Sobject` or `List<Sobject>` | `AggregateResult` or `List<AggregateResult>` | `Sobject`, `List<Sobject>` or `List<List<Sobject>>`
29+
30+
## SOQL Sobject Query Examples
2031
**Basic Usage:** Query an object & return the object's ID and display name field (typically the 'Name' field, but some objects use other fields, like Task.Subject and Case.CaseNumber). Since no filters have been added, this query would also return all accounts.
2132

2233
```
23-
List<Account> accounts = new Soql(Schema.Account.SobjectType).getQueryResults();
34+
List<Account> accounts = new SobjectQueryBuilder(Schema.Account.SobjectType).getResults();
2435
```
2536

2637
**Advanced Usage:** Query an object & leverage the query builder methods. The order of the builder methods does not matter - you can arrange the calls to these methods in any order that you prefer.
2738

2839
```
29-
Soql accountQuery = new Soql(Schema.Account) // Query the account object
30-
.addField(Schema.Account.ParentId) // Include the ParentId field, using SObjectField. The current user must have at least read access to the field
31-
.addField(Schema.Account.Type, Soql.FieldCategory.UPDATEABLE) // Include the Type field if the current user has access to update it
32-
.addFields(Soql.FieldCategory.CUSTOM) // Include all custom fields - Soql.cls only includes fields that are accessible to the user
33-
.addFields(myAccountFieldSet) // Include all fields in a field set that are accessible to the user
34-
.removeField(Schema.Account.My_custom_Field__c) // remove a custom field
35-
.usingScope(Soql.Scope.MINE) // Set the query scope
36-
.filterWhere(Schema.Account.CreatedDate, '=', new Soql.DateLiteral('LAST_WEEK')) // Filter on the created date, using a date literal
37-
.orderBy(Schema.Account.Type) // Order by a field API name - sort order/nulls defaults to 'Type ASC NULLS FIRST'
38-
.orderBy(Account.Name, Soql.SortOrder.ASCENDING) // Order by, using SObjectField & sort order
39-
.orderBy(Account.AnnualRevenue, Soql.SortOrder.DESCENDING, false) // Order by, using SObjectField, sort order and nulls sort order
40-
.limitCount(100) // Limit the results to 100 records
41-
.includeLabels() // Include labels/translations for any picklist fields or record types. These are aliased using the convention 'FieldName__c_Label'
42-
.includeFormattedValues() // Include formatted values for any number, date, time, or currency fields
43-
.cacheResults() // When enabled, the query results are internally cached - any subsequent calls for getQueryResults() will returned cached results instead of executing the query again
44-
.offset(25); // Skip the first 25 results
40+
SobjectQueryBuilder accountQuery = new SobjectQueryBuilder(Schema.Account.SobjectType) // Query the account object
41+
.addField(Schema.Account.ParentId) // Include the ParentId field, using SObjectField. The current user must have at least read access to the field
42+
.addField(Schema.Account.Type, Soql.FieldCategory.UPDATEABLE) // Include the Type field if the current user has access to update it
43+
.addFields(Soql.FieldCategory.CUSTOM) // Include all custom fields - only fields that are accessible to the user are included
44+
.addFieldSet(Schema.Account.MyFieldSet) // Include all fields in a field set that are accessible to the user
45+
.removeField(Schema.Account.My_Custom_Field__c) // remove a custom field
46+
.usingScope(Soql.Scope.MINE) // Set the query scope
47+
.filterWhere(Schema.Account.CreatedDate, '=', new Soql.DateLiteral('LAST_WEEK')) // Filter on the created date, using a date literal
48+
.orderBy(Schema.Account.Type) // Order by a field API name - sort order/nulls defaults to 'Type ASC NULLS FIRST'
49+
.orderBy(Account.Name, Soql.SortOrder.ASCENDING) // Order by, using SObjectField & sort order
50+
.orderBy(Account.AnnualRevenue, Soql.SortOrder.DESCENDING, false) // Order by, using SObjectField, sort order and nulls sort order
51+
.limitTo(100) // Limit the results to 100 records
52+
.includeLabels() // Include labels/translations for any picklist fields or record types. These are aliased using the convention 'FieldName__c_Label'
53+
.includeFormattedValues() // Include formatted values for any number, date, time, or currency fields
54+
.cacheResults() // When enabled, the query results are internally cached - any subsequent calls for getResults() will returned cached results instead of executing the query again
55+
.offsetBy(25); // Skip the first 25 results
4556
4657
// Execute the query and store the results in the 'accounts' variable
47-
List<Account> accounts = accountQuery.getQueryResults();
58+
List<Account> accounts = accountQuery.getResults();
59+
60+
/****** Resulting output *******
61+
SELECT Id, MyCustomDateField__c, MyCustomPicklistField__c, Name,
62+
format(MyCustomDateField__c) MyCustomDateField__c__Formatted,
63+
toLabel(MyCustomPicklistField__c) MyCustomPicklistField__c__Label
64+
FROM Account
65+
USING SCOPE MINE
66+
WHERE CreatedDate = LAST_WEEK
67+
ORDER BY Type ASC NULLS FIRST, Name ASC NULLS FIRST, AnnualRevenue DESC NULLS LAST LIMIT 100 OFFSET 25
68+
*******************************/
69+
70+
System.debug(accountQuery.getQuery());
4871
```
4972

5073
## SOSL Search Examples
5174
**Basic Usage:** Search a single object
5275

5376
```
54-
Soql userQuery = new Soql(Schema.User.SobjectType); // Create an instance of Soql for an Sobject - you can include additional fields, filters, etc
55-
Sosl userSearch = new Sosl('my search term', userQuery); // Create a new Sosl instance with a search term & instance of Soql
56-
List<User> userSearchResults = userSearch.getFirstSearchResults(); // Sosl returns a list of lists of sobjects - getFirstSearchResults() returns the first list
77+
SobjectQueryBuilder userQuery = new SobjectQueryBuilder(Schema.User.SobjectType); // Create an instance of SobjectQueryBuilder for an Sobject - you can include additional fields, filters, etc
78+
SearchBuilder userSearch = new SearchBuilder('my search term', userQuery); // Create a new SearchBuilder instance with a search term & instance of SobjectQueryBuilder
79+
List<User> userSearchResults = userSearch.getFirstResults(); // SearchBuilder returns a list of lists of sobjects - getFirstResults() returns the first list
80+
81+
/****** Resulting output *******
82+
FIND 'my search term' IN ALL FIELDS RETURNING User(Id, Name)
83+
*******************************/
84+
85+
System.debug(userSearch.getSearch());
5786
```
5887

5988
**Advanced Usage:** Search several objects
6089

6190
```
62-
Soql accountQuery = new Soql(Schema.Account.SobjectType); // Create an instance of Soql for the Account object
63-
Soql contactQuery = new Soql(Schema.Contact.SobjectType); // Create an instance of Soql for the Contact object
64-
Soql leadQuery = new Soql(Schema.Lead.SobjectType); // Create an instance of Soql for the Lead object
65-
List<Soql> queries = new List<Soql>{accountQuery, contactQuery, leadQuery}; // Add the Soql queries to a list
91+
SobjectQueryBuilder accountQuery = new SobjectQueryBuilder(Schema.Account.SobjectType); // Create an instance of SobjectQueryBuilder for the Account object
92+
SobjectQueryBuilder contactQuery = new SobjectQueryBuilder(Schema.Contact.SobjectType); // Create an instance of SobjectQueryBuilder for the Contact object
93+
SobjectQueryBuilder leadQuery = new SobjectQueryBuilder(Schema.Lead.SobjectType); // Create an instance of SobjectQueryBuilder for the Lead object
94+
List<SobjectQueryBuilder> queries = new List<SobjectQueryBuilder>{contactQuery, accountQuery, leadQuery}; // Add the SobjectQueryBuilder queries to a list
95+
96+
SearchBuilder mySearch = new SearchBuilder('my search term', queries); // Create a new SearchBuilder instance with a search term & the list of SobjectQueryBuilder queries
97+
List<List<Sobject>> searchResults = mySearch.getResults(); // Returns all search results
98+
99+
/****** Resulting output *******
100+
FIND 'my search term' IN ALL FIELDS RETURNING Account(Id, Name), Contact(Id, Name), Lead(Id, Name)
101+
*******************************/
66102
67-
Sosl mySearch = new Sosl('my search term', queries); // Create a new Sosl instance with a search term & the list of Soql queries
68-
List<List<Sobject>> searchResults = mySearch.getSearchResults(); // Returns all search results
103+
System.debug(mySearch.getSearch());
69104
```

0 commit comments

Comments
 (0)