Add support for N_QUARTERS_AGO date literal in SOQL queries

moxygen/main/default/classes/database/MockDatabaseTest.cls

@@ -7449,4 +7449,32 @@ private class MockDatabaseTest {
             'Incorrect number of opportunities'
         );
     }
+
+    @isTest
+    static void ensureNQuartersAgoWorksInWhereClause() {
+        List<Opportunity> oppList = new List<Opportunity>();
+        Date startOfThisFiscalQuarter = Gmt.startOfThisFiscalQuarter();
+        for (Integer i = 0; i < 36; i++) {
+            oppList.add(
+                new Opportunity(
+                    Name = 'Opp' + i,
+                    CloseDate = startOfThisFiscalQuarter.addMonths(-i)
+                )
+            );
+        }
+
+        MockDatabase.doInsert(oppList, true);
+
+        Test.startTest();
+        List<Opportunity> opportunities = MockDatabase.query(
+            'SELECT Id, CloseDate FROM Opportunity WHERE CloseDate = N_QUARTERS_AGO:2'
+        );
+        Test.stopTest();
+
+        Assert.areEqual(
+            3,
+            opportunities.size(),
+            'Incorrect number of opportunities'
+        );
+    }
 }

moxygen/main/default/classes/database/Token.cls

@@ -144,6 +144,7 @@ public with sharing class Token {
     public final static String LAST_QUARTER_LITERAL = 'last_quarter';
     public final static String NEXT_QUARTER_LITERAL = 'next_quarter';
     public final static String NEXT_N_QUARTERS_LITERAL = 'next_n_quarters';
+    public final static String N_QUARTERS_AGO_LITERAL = 'n_quarters_ago';
     public final static String THIS_YEAR_LITERAL = 'this_year';
     public final static String THIS_FISCAL_YEAR_LITERAL = 'this_fiscal_year';
     public final static String LAST_N_FISCAL_YEARS_LITERAL = 'last_n_fiscal_years';
@@ -184,6 +185,7 @@ public with sharing class Token {
         LAST_QUARTER_LITERAL,
         NEXT_QUARTER_LITERAL,
         NEXT_N_QUARTERS_LITERAL,
+        N_QUARTERS_AGO_LITERAL,
         THIS_YEAR_LITERAL,
         THIS_FISCAL_YEAR_LITERAL,
         LAST_N_FISCAL_YEARS_LITERAL,

moxygen/main/default/classes/database/dml-engine/mock-dml-handlers/MockDMLHandler.cls-meta.xml

@@ -2,4 +2,4 @@
 <ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
     <apiVersion>62.0</apiVersion>
     <status>Active</status>
-</ApexClass>
+</ApexClass>

moxygen/main/default/classes/database/soql-engine/interpreter/operator-handler/date-literal-comparable/DateLiteralComparableFactory.cls

@@ -43,7 +43,8 @@ public with sharing class DateLiteralComparableFactory {
         Token.LAST_N_YEARS_LITERAL => LastNYearsComparable.class,
         Token.LAST_YEAR_LITERAL => LastYearComparable.class,
         Token.NEXT_N_YEARS_LITERAL => NextNYearsComparable.class,
-        Token.LAST_N_QUARTERS_LITERAL => LastNQuartersComparable.class
+        Token.LAST_N_QUARTERS_LITERAL => LastNQuartersComparable.class,
+        Token.N_QUARTERS_AGO_LITERAL => NQuartersAgoComparable.class
     };
 
     @TestVisible

moxygen/main/default/classes/database/soql-engine/interpreter/operator-handler/date-literal-comparable/NQuartersAgoComparable.cls

@@ -0,0 +1,19 @@
+/**
+ * @description Comparable class for N_QUARTERS_AGO
+ * @author Zackary Frazier
+ * @since 2/12/2025
+ * @group Soql Engine
+ */
+public with sharing class NQuartersAgoComparable extends DateLiteralComparable {
+    public override Boolean isGreaterThan(DateTime fieldValue) {
+        DateTime nQuartersAgo = Gmt.startOfThisCalendarQuarter()
+            .addMonths(-3 * this.n);
+        return fieldValue >= nQuartersAgo.addMonths(3);
+    }
+
+    public override Boolean isLessThan(DateTime fieldValue) {
+        DateTime nQuartersAgo = Gmt.startOfThisCalendarQuarter()
+            .addMonths(-3 * this.n);
+        return fieldValue < nQuartersAgo;
+    }
+}

moxygen/main/default/classes/database/soql-engine/interpreter/operator-handler/date-literal-comparable/NQuartersAgoComparable.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>62.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

moxygen/main/default/classes/database/soql-engine/interpreter/operator-handler/date-literal-comparable/NQuartersAgoComparableTest.cls

@@ -0,0 +1,72 @@
+@isTest
+private class NQuartersAgoComparableTest {
+    @isTest
+    static void ensureIsLessThanWorks() {
+        DateLiteralComparable nQuartersAgoComparable = new NQuartersAgoComparable()
+            .withToken('n_quarters_ago:2');
+        Assert.isFalse(
+            nQuartersAgoComparable.isLessThan(Gmt.startOfThisCalendarQuarter()),
+            'This quarter should not be less than N_QUARTERS_AGO:2'
+        );
+        Assert.isFalse(
+            nQuartersAgoComparable.isLessThan(
+                Gmt.startOfThisCalendarQuarter().addMonths(-3)
+            ),
+            'Last quarter should not be less than N_QUARTERS_AGO:2'
+        );
+        Assert.isFalse(
+            nQuartersAgoComparable.isLessThan(
+                Gmt.startOfThisCalendarQuarter().addMonths(-6)
+            ),
+            '2 quarters ago should not be less than N_QUARTERS_AGO:2'
+        );
+        Assert.isTrue(
+            nQuartersAgoComparable.isLessThan(
+                Gmt.startOfThisCalendarQuarter().addMonths(-9)
+            ),
+            '3 quarters ago should be less than N_QUARTERS_AGO:2'
+        );
+        Assert.isFalse(
+            nQuartersAgoComparable.isLessThan(
+                Gmt.startOfThisCalendarQuarter().addMonths(-6).addDays(45)
+            ),
+            'Middle of 2 quarters ago should not be less than N_QUARTERS_AGO:2'
+        );
+    }
+
+    @isTest
+    static void ensureIsGreaterThanWorks() {
+        DateLiteralComparable nQuartersAgoComparable = new NQuartersAgoComparable()
+            .withToken('n_quarters_ago:2');
+        Assert.isTrue(
+            nQuartersAgoComparable.isGreaterThan(
+                Gmt.startOfThisCalendarQuarter()
+            ),
+            'This quarter should be greater than N_QUARTERS_AGO:2'
+        );
+        Assert.isTrue(
+            nQuartersAgoComparable.isGreaterThan(
+                Gmt.startOfThisCalendarQuarter().addMonths(-3)
+            ),
+            'Last quarter should be greater than N_QUARTERS_AGO:2'
+        );
+        Assert.isFalse(
+            nQuartersAgoComparable.isGreaterThan(
+                Gmt.startOfThisCalendarQuarter().addMonths(-6)
+            ),
+            '2 quarters ago should not be greater than N_QUARTERS_AGO:2'
+        );
+        Assert.isFalse(
+            nQuartersAgoComparable.isGreaterThan(
+                Gmt.startOfThisCalendarQuarter().addMonths(-9)
+            ),
+            '3 quarters ago should not be greater than N_QUARTERS_AGO:2'
+        );
+        Assert.isFalse(
+            nQuartersAgoComparable.isGreaterThan(
+                Gmt.startOfThisCalendarQuarter().addMonths(-6).addDays(45)
+            ),
+            'Middle of 2 quarters ago should not be greater than N_QUARTERS_AGO:2'
+        );
+    }
+}

moxygen/main/default/classes/database/soql-engine/interpreter/operator-handler/date-literal-comparable/NQuartersAgoComparableTest.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>62.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

moxygen/main/default/classes/database/soql-engine/parser/ParserTest.cls

@@ -896,4 +896,22 @@ private class ParserTest {
         }
         Test.stopTest();
     }
+
+    @isTest
+    static void ensureNQuartersAgoCanBeParsed() {
+        Parser p = new Parser();
+        String soqlQuery = 'SELECT Id FROM Opportunity WHERE CreatedDate = N_QUARTERS_AGO:5';
+        Test.startTest();
+        try {
+            p.parse(soqlQuery);
+        } catch (Exception e) {
+            Assert.fail(
+                'Expected no exception but got ' +
+                    e.getMessage() +
+                    ' for ' +
+                    soqlQuery
+            );
+        }
+        Test.stopTest();
+    }
 }