151 |
152 | Options:
153 | -a, --allow-apex allow apex bind variables
154 | -p, --allow-partial allow partial queries
155 | -j, --json output as JSON
156 | -h, --help output usage information
157 | ```
158 |
--------------------------------------------------------------------------------
/docs/docs/examples.md:
--------------------------------------------------------------------------------
1 | ---
2 | sidebar_position: 4
3 | ---
4 |
5 | # Other Examples
6 |
7 | ### Parsing Queries
8 |
9 | Parsing a SOQL query can be completed by calling `parseQuery(soqlQueryString)`. A `Query` data structure will be returned.
10 |
11 | ```typescript
12 | import { parseQuery } from '@jetstreamapp/soql-parser-js';
13 |
14 | const soql = `
15 | SELECT UserId, COUNT(Id)
16 | FROM LoginHistory
17 | WHERE LoginTime > 2010-09-20T22:16:30.000Z
18 | AND LoginTime < 2010-09-21T22:16:30.000Z
19 | GROUP BY UserId
20 | `;
21 |
22 | console.log(JSON.stringify(soqlQuery, null, 2));
23 | ```
24 |
25 |
26 | Results (click to show)
27 |
28 | ```json
29 | {
30 | "fields": [
31 | {
32 | "type": "Field",
33 | "field": "UserId"
34 | },
35 | {
36 | "type": "FieldFunctionExpression",
37 | "functionName": "COUNT",
38 | "parameters": ["Id"],
39 | "isAggregateFn": true,
40 | "rawValue": "COUNT(Id)"
41 | }
42 | ],
43 | "sObject": "LoginHistory",
44 | "where": {
45 | "left": {
46 | "field": "LoginTime",
47 | "operator": ">",
48 | "value": "2010-09-20T22:16:30.000Z",
49 | "literalType": "DATETIME"
50 | },
51 | "operator": "AND",
52 | "right": {
53 | "left": {
54 | "field": "LoginTime",
55 | "operator": "<",
56 | "value": "2010-09-21T22:16:30.000Z",
57 | "literalType": "DATETIME"
58 | }
59 | }
60 | },
61 | "groupBy": {
62 | "field": "UserId"
63 | }
64 | }
65 | ```
66 |
67 |
68 |
69 | ### Parsing a partial query
70 |
71 | Added support for `allowPartialQuery` in version `4.4.0`
72 |
73 | ```typescript
74 | import { parseQuery } from '@jetstreamapp/soql-parser-js';
75 |
76 | const soql = `
77 | WHERE LoginTime > 2010-09-20T22:16:30.000Z
78 | AND LoginTime < 2010-09-21T22:16:30.000Z
79 | GROUP BY UserId
80 | `;
81 |
82 | const soqlQuery = parseQuery(soql, { allowPartialQuery: true });
83 |
84 | console.log(JSON.stringify(soqlQuery, null, 2));
85 | ```
86 |
87 |
88 | Results (click to show)
89 |
90 | ```json
91 | {
92 | "where": {
93 | "left": {
94 | "field": "LoginTime",
95 | "operator": ">",
96 | "value": "2010-09-20T22:16:30.000Z",
97 | "literalType": "DATETIME"
98 | },
99 | "operator": "AND",
100 | "right": {
101 | "left": {
102 | "field": "LoginTime",
103 | "operator": "<",
104 | "value": "2010-09-21T22:16:30.000Z",
105 | "literalType": "DATETIME"
106 | }
107 | }
108 | },
109 | "groupBy": {
110 | "field": "UserId"
111 | }
112 | }
113 | ```
114 |
115 |
116 |
117 | ### Validating Queries
118 |
119 | ```typescript
120 | import { isQueryValid } from '@jetstreamapp/soql-parser-js';
121 |
122 | const invalidSoql = `SELECT UserId, COUNT(Id) Account`;
123 | const validSoql = `SELECT UserId, COUNT(Id) Account`;
124 |
125 | console.log(isQueryValid(soql));
126 | console.log(isQueryValid(soql));
127 | ```
128 |
129 | ### Composing Queries
130 |
131 | Build a `Query` data structure to have it converted back into a SOQL query.
132 |
133 | Composing a query will turn a Query object back to a SOQL query string. The exact same data structure returned from `parseQuery()` can be used,
134 | but depending on your use-case, you may need to build your own data structure to compose a query.
135 | These examples show building your own Query object with the minimum required fields.
136 |
137 | Some utility methods have been provided to make it easier to build the field data structures.
138 |
139 | **Note:** Some operators may be converted to uppercase (e.x. NOT, AND)
140 |
141 | **Note:** There are a number of fields populated on the Query object when `parseQuery()` is called that are not required to compose a query. Look at the examples below and the comments in the data model for more information.
142 |
143 | ```typescript
144 | import { composeQuery, getField, Query } from '@jetstreamapp/soql-parser-js';
145 |
146 | // Build a subquery
147 | const oppLineItemsSubquery = {
148 | fields: [
149 | getField('Quantity'),
150 | getField('ListPrice'),
151 | getField({
152 | field: 'UnitPrice',
153 | relationships: ['PricebookEntry'],
154 | }),
155 | getField({
156 | field: 'Name',
157 | relationships: ['PricebookEntry'],
158 | }),
159 | ],
160 | relationshipName: 'OpportunityLineItems',
161 | };
162 |
163 | // build the main query and add the subquery as a field
164 | const soqlQuery: Query = {
165 | fields: [
166 | getField('Id'),
167 | getField('Name'),
168 | getField({
169 | functionName: 'FORMAT',
170 | parameters: 'Amount',
171 | alias: 'MyFormattedAmount',
172 | }),
173 | getField({ subquery: oppLineItemsSubquery }),
174 | ],
175 | sObject: 'Opportunity',
176 | where: {
177 | left: {
178 | field: 'CreatedDate',
179 | operator: '>',
180 | value: 'LAST_N_YEARS:1',
181 | },
182 | operator: 'AND',
183 | right: {
184 | left: {
185 | field: 'StageName',
186 | operator: '=',
187 | value: 'Closed Won',
188 | // literalType is optional, but if set to STRING and our value is not already wrapped in "'", they will be added
189 | // All other literalType values are ignored when composing a query
190 | literalType: 'STRING',
191 | },
192 | },
193 | },
194 | limit: 150,
195 | };
196 |
197 | const composedQuery = composeQuery(soqlQuery, { format: true });
198 |
199 | console.log(composedQuery);
200 | ```
201 |
202 | **Results**
203 |
204 | ```sql
205 | SELECT Id, Name, FORMAT(Amount) MyFormattedAmount,
206 | (
207 | SELECT Quantity, ListPrice, PricebookEntry.UnitPrice,
208 | PricebookEntry.Name
209 | FROM OpportunityLineItems
210 | )
211 | FROM Opportunity
212 | WHERE CreatedDate > LAST_N_YEARS:1
213 | AND StageName = 'Closed Won'
214 | LIMIT 150
215 | ```
216 |
217 | ### Composing a partial query
218 |
219 | Starting in version `4.4`, compose will not fail if there are missing `SELECT` and `FROM` clauses in your query.
220 |
221 | Partial compose support it supported without any additional steps.
222 |
223 | ```typescript
224 | import { Compose, parseQuery } from '@jetstreamapp/soql-parser-js';
225 |
226 | const soql = `WHERE Name LIKE 'A%' AND MailingCity = 'California`;
227 | const parsedQuery = parseQuery(soql, { allowPartialQuery: true });
228 |
229 | // Results of Parsed Query:
230 | /**
231 | {
232 | where: {
233 | left: { field: 'Name', operator: 'LIKE', value: "'A%'", literalType: 'STRING' },
234 | operator: 'AND',
235 | right: { left: { field: 'MailingCity', operator: '=', value: "'California'", literalType: 'STRING' } },
236 | },
237 | }
238 | */
239 |
240 | const composedQuery = composeQuery(soqlQuery, { format: true });
241 |
242 | console.log(composedQuery);
243 | ```
244 |
245 | **Results**
246 |
247 | ```sql
248 | WHERE Name LIKE 'A%' AND MailingCity = 'California
249 | ```
250 |
251 |
252 | See the alternate way to compose partial queries by calling the Compose class directly
253 |
254 | If you need to compose just a part of a query instead of the entire query, you can create an instance of the Compose class directly.
255 |
256 | For example, if you just need the `WHERE` clause from a query as a string, you can do the following:
257 |
258 | ```typescript
259 | import { Compose, parseQuery } from '@jetstreamapp/soql-parser-js';
260 |
261 | const soql = `SELECT Id FROM Account WHERE Name = 'Foo'`;
262 | const parsedQuery = parseQuery(soql);
263 |
264 | // Results of Parsed Query:
265 | // const parsedQuery = {
266 | // fields: [
267 | // {
268 | // type: 'Field',
269 | // field: 'Id',
270 | // },
271 | // ],
272 | // sObject: 'Account',
273 | // where: {
274 | // left: {
275 | // field: 'Name',
276 | // operator: '=',
277 | // value: "'Foo'",
278 | // literalType: 'STRING',
279 | // },
280 | // },
281 | // };
282 |
283 | // Create a new instance of the compose class and set the autoCompose to false to avoid composing the entire query
284 | const composer = new Compose(parsedQuery, { autoCompose: false });
285 |
286 |
287 | const whereClause = composer.parseWhereOrHavingClause(parsedQuery.where);
288 |
289 | console.log(whereClause);
290 | }
291 | ```
292 |
293 | #### Available methods on the `Compose` class
294 |
295 | These are used internally, but are public and available for use.
296 |
297 | ```typescript
298 | parseQuery(query: Query | Subquery): string;
299 | parseFields(fields: FieldType[]): { text: string; typeOfClause?: string[] }[];
300 | parseTypeOfField(typeOfField: FieldTypeOf): string[];
301 | parseWhereOrHavingClause(whereOrHaving: WhereClause | HavingClause, tabOffset = 0, priorConditionIsNegation = false): string;
302 | parseGroupByClause(groupBy: GroupByClause | GroupByClause[]): string;
303 | parseOrderBy(orderBy: OrderByClause | OrderByClause[]): string;
304 | parseWithDataCategory(withDataCategory: WithDataCategoryClause): string;
305 | ```
306 |
307 |
308 |
309 | ## Format Query
310 |
311 | This function is provided as a convenience and just calls parse and compose.
312 | [Check out the demo](https://paustint.github.io/soql-parser-js/) to see the outcome of the various format options.
313 |
314 | ```typescript
315 | import { formatQuery } from '@jetstreamapp/soql-parser-js';
316 |
317 | const query = `SELECT Id, Name, AccountNumber, AccountSource, AnnualRevenue, BillingAddress, BillingCity, BillingCountry, BillingGeocodeAccuracy, ShippingStreet, Sic, SicDesc, Site, SystemModstamp, TickerSymbol, Type, Website, (SELECT Id, Name, AccountId, Amount, CampaignId, CloseDate, CreatedById, Type FROM Opportunities), (SELECT Id, Name, AccountNumber, AccountSource, AnnualRevenue, BillingAddress, Website FROM ChildAccounts) FROM Account WHERE Name LIKE 'a%' OR Name LIKE 'b%' OR Name LIKE 'c%'`;
318 |
319 | const formattedQuery1 = formatQuery(query);
320 | const formattedQuery2 = formatQuery(query, {
321 | fieldMaxLineLength: 20,
322 | fieldSubqueryParensOnOwnLine: false,
323 | whereClauseOperatorsIndented: true,
324 | });
325 | const formattedQuery3 = formatQuery(query, { fieldSubqueryParensOnOwnLine: true, whereClauseOperatorsIndented: true });
326 | ```
327 |
328 | ```sql
329 | -- formattedQuery1
330 | SELECT Id, Name, AccountNumber, AccountSource, AnnualRevenue,
331 | BillingAddress, BillingCity, BillingCountry, BillingGeocodeAccuracy,
332 | ShippingStreet, Sic, SicDesc, Site, SystemModstamp, TickerSymbol, Type,
333 | Website,
334 | (
335 | SELECT Id, Name, AccountId, Amount, CampaignId, CloseDate,
336 | CreatedById, Type
337 | FROM Opportunities
338 | ),
339 | (
340 | SELECT Id, Name, AccountNumber, AccountSource, AnnualRevenue,
341 | BillingAddress, Website
342 | FROM ChildAccounts
343 | )
344 | FROM Account
345 | WHERE Name LIKE 'a%'
346 | OR Name LIKE 'b%'
347 | OR Name LIKE 'c%'
348 |
349 | -- formattedQuery2
350 | SELECT Id, Name,
351 | AccountNumber, AccountSource,
352 | AnnualRevenue, BillingAddress,
353 | BillingCity, BillingCountry,
354 | BillingGeocodeAccuracy, ShippingStreet,
355 | Sic, SicDesc, Site,
356 | SystemModstamp, TickerSymbol, Type,
357 | Website,
358 | (SELECT Id, Name,
359 | AccountId, Amount, CampaignId,
360 | CloseDate, CreatedById, Type
361 | FROM Opportunities),
362 | (SELECT Id, Name,
363 | AccountNumber, AccountSource,
364 | AnnualRevenue, BillingAddress,
365 | Website
366 | FROM ChildAccounts)
367 | FROM Account
368 | WHERE Name LIKE 'a%'
369 | OR Name LIKE 'b%'
370 | OR Name LIKE 'c%'
371 |
372 |
373 | -- formattedQuery3
374 | SELECT Id, Name, AccountNumber, AccountSource, AnnualRevenue,
375 | BillingAddress, BillingCity, BillingCountry, BillingGeocodeAccuracy,
376 | ShippingStreet, Sic, SicDesc, Site, SystemModstamp, TickerSymbol, Type,
377 | Website,
378 | (
379 | SELECT Id, Name, AccountId, Amount, CampaignId, CloseDate,
380 | CreatedById, Type
381 | FROM Opportunities
382 | ),
383 | (
384 | SELECT Id, Name, AccountNumber, AccountSource, AnnualRevenue,
385 | BillingAddress, Website
386 | FROM ChildAccounts
387 | )
388 | FROM Account
389 | WHERE Name LIKE 'a%'
390 | OR Name LIKE 'b%'
391 | OR Name LIKE 'c%'
392 | ```
393 |
--------------------------------------------------------------------------------
/docs/docusaurus.config.js:
--------------------------------------------------------------------------------
1 | // @ts-check
2 | // Note: type annotations allow type checking and IDEs autocompletion
3 |
4 | const { themes } = require('prism-react-renderer');
5 |
6 | const lightCodeTheme = themes.github;
7 | const darkCodeTheme = themes.shadesOfPurple;
8 |
9 | /** @type {import('@docusaurus/types').Config} */
10 | const config = {
11 | title: 'SOQL Parser JS',
12 | tagline: 'Parse and generate SOQL queries',
13 | url: 'https://soql-parser-js.getjetstream.app',
14 | baseUrl: '/',
15 | onBrokenLinks: 'throw',
16 | onBrokenMarkdownLinks: 'warn',
17 | favicon: 'img/favicon.ico',
18 |
19 | // GitHub pages deployment config.
20 | // If you aren't using GitHub pages, you don't need these.
21 | organizationName: 'jetstreamapp',
22 | projectName: 'soql-parser-js',
23 | deploymentBranch: 'gh-pages',
24 | trailingSlash: false,
25 |
26 | // Even if you don't use internalization, you can use this field to set useful
27 | // metadata like html lang. For example, if your site is Chinese, you may want
28 | // to replace "en" with "zh-Hans".
29 | i18n: {
30 | defaultLocale: 'en',
31 | locales: ['en'],
32 | },
33 |
34 | presets: [
35 | [
36 | 'classic',
37 | /** @type {import('@docusaurus/preset-classic').Options} */
38 | ({
39 | docs: {
40 | sidebarPath: require.resolve('./sidebars.js'),
41 | // Please change this to your repo.
42 | // Remove this to remove the "edit this page" links.
43 | editUrl: 'https://github.com/jetstreamapp/soql-parser-js/docs/docs/',
44 | },
45 | theme: {
46 | customCss: require.resolve('./src/css/custom.css'),
47 | },
48 | }),
49 | ],
50 | ],
51 |
52 | themeConfig:
53 | /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
54 | ({
55 | colorMode: {
56 | defaultMode: 'dark',
57 | respectPrefersColorScheme: true,
58 | },
59 | navbar: {
60 | title: '',
61 | logo: {
62 | alt: 'Logo',
63 | src: 'img/soql-parser-js-logo.svg',
64 | },
65 | items: [
66 | {
67 | type: 'doc',
68 | docId: 'overview',
69 | position: 'left',
70 | label: 'Documentation',
71 | },
72 | { to: '/playground', label: 'Playground', position: 'left' },
73 | {
74 | href: 'https://github.com/jetstreamapp/soql-parser-js',
75 | label: 'GitHub',
76 | position: 'right',
77 | },
78 | ],
79 | },
80 | footer: {
81 | style: 'dark',
82 | links: [
83 | {
84 | title: 'Links',
85 | items: [
86 | {
87 | label: 'Documentation',
88 | to: '/docs/overview',
89 | },
90 | {
91 | label: 'GitHub',
92 | href: 'https://github.com/jetstreamapp/soql-parser-js',
93 | },
94 | ],
95 | },
96 | ],
97 | },
98 | markdown: {
99 | mdx1Compat: {
100 | comments: false,
101 | admonitions: false,
102 | headingIds: false,
103 | },
104 | },
105 | prism: {
106 | theme: lightCodeTheme,
107 | darkTheme: darkCodeTheme,
108 | },
109 | additionalLanguages: ['javascript', 'json', 'sql'],
110 | }),
111 | };
112 |
113 | module.exports = config;
114 |
--------------------------------------------------------------------------------
/docs/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "docs",
3 | "version": "0.0.0",
4 | "private": true,
5 | "scripts": {
6 | "docusaurus": "docusaurus",
7 | "start": "docusaurus start",
8 | "build": "docusaurus build",
9 | "swizzle": "docusaurus swizzle",
10 | "deploy": "docusaurus deploy",
11 | "clear": "docusaurus clear",
12 | "serve": "docusaurus serve",
13 | "write-translations": "docusaurus write-translations",
14 | "write-heading-ids": "docusaurus write-heading-ids",
15 | "typecheck": "tsc"
16 | },
17 | "dependencies": {
18 | "@docusaurus/core": "3.4.0",
19 | "@docusaurus/preset-classic": "3.4.0",
20 | "@jetstreamapp/soql-parser-js": "^6.2.0",
21 | "@mdx-js/react": "^3.0.1",
22 | "clsx": "^2.1.1",
23 | "prism-react-renderer": "^2.3.1",
24 | "react": "^18.3.1",
25 | "react-dom": "^18.3.1"
26 | },
27 | "devDependencies": {
28 | "@docusaurus/module-type-aliases": "3.4.0",
29 | "@docusaurus/tsconfig": "3.4.0",
30 | "@docusaurus/types": "3.0.0",
31 | "@types/react": "^18.3.3",
32 | "typescript": "~5.4.5"
33 | },
34 | "browserslist": {
35 | "production": [
36 | ">0.5%",
37 | "not dead",
38 | "not op_mini all"
39 | ],
40 | "development": [
41 | "last 1 chrome version",
42 | "last 1 firefox version",
43 | "last 1 safari version"
44 | ]
45 | },
46 | "engines": {
47 | "node": ">=18.0"
48 | }
49 | }
50 |
--------------------------------------------------------------------------------
/docs/sidebars.js:
--------------------------------------------------------------------------------
1 | /**
2 | * Creating a sidebar enables you to:
3 | - create an ordered group of docs
4 | - render a sidebar for each doc of that group
5 | - provide next/previous navigation
6 |
7 | The sidebars can be generated from the filesystem, or explicitly defined here.
8 |
9 | Create as many sidebars as you want.
10 | */
11 |
12 | // @ts-check
13 |
14 | /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
15 | const sidebars = {
16 | // By default, Docusaurus generates a sidebar from the docs folder structure
17 | tutorialSidebar: [{ type: 'autogenerated', dirName: '.' }],
18 | };
19 |
20 | module.exports = sidebars;
21 |
--------------------------------------------------------------------------------
/docs/src/components/ComposeQueries/ParsedOutput/index.tsx:
--------------------------------------------------------------------------------
1 | import React from 'react';
2 | import { Highlight } from '../../Utilities/Highlight';
3 |
4 | export interface ParsedOutputProps {
5 | query: string;
6 | }
7 |
8 | export default function ParsedOutput({ query }: ParsedOutputProps): JSX.Element {
9 | return (
10 |
11 | {query && (
12 | <>
13 |
Output
14 |
15 |
16 | )}
17 |
13 |