You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
SOQL Lib has 3 different modules: [SOQL](/soql/getting-started), [SOQL Cache](/cache/getting-started), and [SOQL Evaluator](/evaluator/getting-started). SOQL Evaluator was created for developers who don't want to learn a new syntax but still want to benefit from features like mocking and result functions. You can use [this module](https://github.com/beyond-the-cloud-dev/soql-lib/tree/main/force-app/main/default/classes/main/soql-evaluator) without switching to an entirely new syntax.
9
+
10
+
```apex
11
+
Set<Id> accountIds = SOQLEvaluator.of([SELECT Id FROM Account]).toIds();
12
+
List<String> accountNames = SOQLEvaluator.of([SELECT Id, Name FROM Account]).toValuesOf(Account.Name);
13
+
```
14
+
15
+
### It's Not That Complicated
16
+
17
+
#### Documentation
18
+
19
+
SOQL Lib provides comprehensive online documentation with the [playground](./playground) and numerous [examples](/soql/examples/select). You can also use the search feature in the top-right corner to find what you're looking for. The Fluent API was designed to stay as close to traditional SOQL syntax as possible. However, due to Apex's `Identifier name is reserved` restriction, some keywords like `select`, `where`, and `limit` couldn't be used.
20
+
21
+
#### Interfaces
22
+
23
+
"Do I need to go to the documentation and spend a lot of time searching for what I need?"
24
+
25
+
No. At the top of [SOQL.cls](https://github.com/beyond-the-cloud-dev/soql-lib/blob/main/force-app/main/default/classes/main/standard-soql/SOQL.cls), we've placed all the interfaces you can interact with. Even as the author, I don't remember all the methods. However, I can quickly navigate to [SOQL.cls](https://github.com/beyond-the-cloud-dev/soql-lib/blob/main/force-app/main/default/classes/main/standard-soql/SOQL.cls) and identify what I need in seconds. Everything important is at the top—you don't have to scroll through the entire class searching for methods. Just focus on the interfaces.
26
+
27
+
#### Use AI
28
+
29
+
A simple prompt in your IDE integrated with AI can be very helpful: "Based on SOQL.cls and SOQL_Test.cls, understand how SOQL Lib works. Write an inline query that returns all accounts with Employee Number greater than 100." Voilà! That's it. You don't need to read documentation or check interfaces manually.
30
+
31
+
### Less Complicated Than Traditional SOQL
32
+
33
+
#### Result Functions
34
+
35
+
SOQL Lib provides numerous [result functions](/soql/examples/result) that make your code easier to read and understand. Most operations you typically perform on SOQL results are available as methods in SOQL Lib. Instead of repeating the same transformations throughout your codebase, simply use result methods.
36
+
37
+
**Apex**
38
+
39
+
```apex
40
+
Map<String, List<Account>> industryToAccounts = new Map<String, List<Account>>();
41
+
42
+
for (Account acc : [SELECT Id, Name, Industry FROM Account]) {
43
+
if (!industryToAccounts.containsKey(acc.Industry)) {
44
+
industryToAccounts.put(acc.Industry, new List<Acccount>());
Without SOQL Lib, approximately 90% of your queries use traditional SOQL. The remaining 10% need to be dynamic, requiring numerous string operations. Your code typically looks like this:
61
+
62
+
```apex
63
+
String accountName = '';
64
+
65
+
String query = 'SELECT Id, Name WHERE BillingCity = \'Krakow\'';
66
+
67
+
if (String.isNotEmpty(accountName)) {
68
+
query += ' AND Name LIKE \'%' + accountName +'\%';
69
+
}
70
+
71
+
query += ' FROM Account';
72
+
73
+
Database.query(query);
74
+
```
75
+
76
+
This code is difficult to read and maintain. With SOQL Lib, you can refactor it to:
This is much easier to read. Additionally, the `ignoreWhen` function automatically checks if accountName is empty and ignores the condition accordingly—no more if statements cluttering your code.
91
+
92
+
## Additional Processing Time
93
+
94
+
SOQL Lib builds a query string and passes it to the `Database.queryWithBinds` method. How long do you think it takes to build a string like `SELECT Id, Name FROM Account`?
95
+
96
+
Not much. While dynamic code can be CPU-intensive, we've run extensive performance tests (full results coming soon). Here's a preview:
97
+
98
+
### Result Functions
99
+
100
+
Building a complex query dynamically with SOQL Lib consumes less than **2ms**, and around **1ms** for simple queries.
101
+
Even if you execute 100 complex queries in one transaction (101 SOQL queries per synchronous transaction), in the worst-case scenario, SOQL Lib uses only ~200ms out of the 10,000ms CPU limit available.
102
+
103
+
Additionally, SOQL Lib can be faster than your own implementation. We perform internal optimizations for certain result functions.
104
+
For instance:
105
+
106
+
```apex
107
+
Set<String> accountNames = new Set<String>();
108
+
109
+
for (Account acc : [SELECT Name FROM Account]) {
110
+
accountNames.add(acc.Name);
111
+
}
112
+
```
113
+
114
+
The SOQL Lib version is approximately 2x faster because we use internal aggregation optimizations. Learn more about this technique: https://salesforce.stackexchange.com/questions/393308/get-a-list-of-one-column-from-a-soql-result
How long does it take to run Apex unit tests with all test data inserted? Typically seconds, or even minutes.
123
+
124
+
How long does it take to run Apex unit tests when query results are mocked and there's no need to create test data? Milliseconds to seconds—definitely not minutes.
125
+
126
+
I don't need to emphasize the benefits of writing fast, reliable unit tests. Instead of spending time figuring out how to set fields so validation rules pass, or determining what setup is needed to avoid trigger errors, mocking allows you to return query results without any database operations.
127
+
128
+
With mocking, you not only save hours on test data creation but also reduce test execution time by minutes. If someone argues that SOQL Lib consumes CPU time, they should consider that they cannot afford NOT to mock query results.
129
+
130
+
## It's Just a Query Builder
131
+
132
+
No, it's much more than that.
133
+
134
+
The query builder is just one component of SOQL Lib. SOQL Lib itself is a lightweight yet powerful alternative to FFLib Selectors. It provides all the benefits of FFLib and significantly more. The main advantage is that it's extremely easy to use compared to FFLib.
135
+
136
+
**You can:**
137
+
- Mock your queries
138
+
- Cache your query results
139
+
- Build your own lightweight selectors
140
+
- Control Field-Level Security (FLS)
141
+
- Control sharing rules
142
+
- Use result functions to make your code cleaner and faster
143
+
- Use the query builder to avoid string concatenation
const[soqlInput,setSoqlInput]=useState('SELECT Id, Name, Industry, BillingCity\nFROM Account\nWHERE Industry = \'Technology\' \n AND BillingCity = \'San Francisco\'\nORDER BY Name ASC\nLIMIT 10\nWITH USER_MODE');
query: `SELECT Id, Name, (SELECT Id, Name FROM Contacts)
1202
-
FROM Account
1203
-
WITH USER_MODE`
1167
+
query: "SELECT Id, Name, (SELECT Id, Name FROM Contacts)\nFROM Account\nWITH USER_MODE"
1204
1168
},
1205
1169
{
1206
1170
name: "Complex WHERE",
1207
-
query: `SELECT Id
1208
-
FROM Account
1209
-
WHERE Industry = 'IT'
1210
-
AND ((Name = 'My Account' AND NumberOfEmployees >= 10)
1211
-
OR (Name = 'My Account 2' AND NumberOfEmployees <= 20))
1212
-
WITH USER_MODE`
1171
+
query: "SELECT Id\nFROM Account\nWHERE Industry = 'IT'\n AND ((Name = 'My Account' AND NumberOfEmployees >= 10)\n OR (Name = 'My Account 2' AND NumberOfEmployees <= 20))\nWITH USER_MODE"
1213
1172
},
1214
1173
{
1215
1174
name: "LIKE Patterns",
1216
-
query: `SELECT Id, Name
1217
-
FROM Account
1218
-
WHERE Name LIKE 'Test%'
1219
-
AND BillingCity LIKE '%Francisco%'
1220
-
WITH USER_MODE`
1175
+
query: "SELECT Id, Name\nFROM Account\nWHERE Name LIKE 'Test%'\n AND BillingCity LIKE '%Francisco%'\nWITH USER_MODE"
1221
1176
},
1222
1177
{
1223
1178
name: "IN Operator",
1224
-
query: `SELECT Id, Name
1225
-
FROM Account
1226
-
WHERE Industry IN ('Technology', 'Healthcare', 'Finance')
1227
-
WITH USER_MODE`
1179
+
query: "SELECT Id, Name\nFROM Account\nWHERE Industry IN ('Technology', 'Healthcare', 'Finance')\nWITH USER_MODE"
1228
1180
},
1229
1181
{
1230
1182
name: "ORDER BY Multiple",
1231
-
query: `SELECT Id, Name, Industry
1232
-
FROM Account
1233
-
ORDER BY Name DESC, Industry ASC
1234
-
LIMIT 50
1235
-
WITH USER_MODE`
1183
+
query: "SELECT Id, Name, Industry\nFROM Account\nORDER BY Name DESC, Industry ASC\nLIMIT 50\nWITH USER_MODE"
1236
1184
},
1237
1185
{
1238
1186
name: "Complex Query",
1239
-
query: `SELECT Id, Name
1240
-
FROM Account
1241
-
WHERE (Industry = 'Technology' OR Industry = 'Healthcare')
1242
-
AND NumberOfEmployees > 100
1243
-
ORDER BY Name
1244
-
LIMIT 20
1245
-
WITH USER_MODE`
1187
+
query: "SELECT Id, Name\nFROM Account\nWHERE (Industry = 'Technology' OR Industry = 'Healthcare')\n AND NumberOfEmployees > 100\nORDER BY Name\nLIMIT 20\nWITH USER_MODE"
0 commit comments