Date Literal
A date literal is a SOQL keyword that represents a relative date or date range, evaluated at query time against the current date in the user's locale.
Definition
A date literal is a SOQL keyword that represents a relative date or date range, evaluated at query time against the current date in the user's locale. TODAY, YESTERDAY, LAST_WEEK, THIS_QUARTER, LAST_FISCAL_YEAR, and parameterized forms like LAST_N_DAYS:30 cover most operational queries you would otherwise build with hardcoded date arithmetic. Reports, list views, and dashboards use the same literal vocabulary in their date filters.
Date literals exist because hardcoding a date into a query (CloseDate = 2026-05-20) freezes that query to a single point in time. The literal expands at execution into the right calendar boundaries, accounting for time zones, fiscal year setup, and the user's locale. A scheduled report filtered to LAST_QUARTER produces the right window every quarter without anyone editing it.
Working with SOQL date literals in queries and reports
The literal catalog: relative ranges, fiscal periods, and N-ago variants
Salesforce supports a few dozen date literals organized around three axes: direction (LAST, THIS, NEXT, N_AGO), unit (DAYS, WEEKS, MONTHS, QUARTERS, YEARS, FISCAL_QUARTERS, FISCAL_YEARS), and parameterization (fixed like LAST_QUARTER vs parameterized like LAST_N_QUARTERS:4). TODAY, YESTERDAY, and TOMORROW are the only single-day literals. Combine literals with comparison operators (= TODAY, > LAST_MONTH, IN: LAST_90_DAYS) to filter records into the window you need.
How date literals expand at query time
When Salesforce evaluates a query containing LAST_WEEK, it computes the boundary based on the running user's locale and time zone. For someone in a US English locale, LAST_WEEK is Sunday through Saturday of the previous week; in a UK English locale, it can be Monday through Sunday. THIS_MONTH always starts on the 1st of the current month and ends on the last day, regardless of locale. The expansion is invisible: your query reads LAST_WEEK, the database receives a range condition with concrete timestamps.
Fiscal date literals and the fiscal year setup
THIS_FISCAL_QUARTER, LAST_FISCAL_YEAR, and their N-variant cousins respect your org's fiscal year configuration. By default that is January through December with four calendar quarters, but if Setup has custom fiscal years enabled, the literals follow the configured fiscal calendar (which can have non-standard quarter lengths or 13-period accounting calendars). Always confirm what fiscal setup the org uses before writing fiscal-period reports, because the same query against two different orgs can return different rows.
N_DAYS_AGO, NEXT_N_DAYS, and the off-by-one debate
Parameterized literals take a colon and a number: LAST_N_DAYS:30 means the last 30 days including today, while N_DAYS_AGO:30 means exactly 30 days ago (a single day). LAST_N_DAYS:7 and LAST_WEEK return different windows because LAST_WEEK is calendar-week-aligned and LAST_N_DAYS:7 is a rolling 7 days. Pick the literal that matches the business question, not the one that sounds right; this is where most date-literal bugs hide.
Date literals with DateTime fields
On Date fields, literals expand to date-only ranges (one day for TODAY, seven days for LAST_WEEK). On DateTime fields, the platform expands them to timestamp ranges with hour, minute, and second boundaries. TODAY on CreatedDate means 00:00:00.000 through 23:59:59.999 in the user's time zone. This is why CreatedDate = TODAY can miss a record created one second after midnight in a different time zone: the boundary is locale-specific.
Where date literals do not work
SOQL date literals do not work in formula fields, validation rules, or workflow conditions. Those expressions use Salesforce formula functions (TODAY(), NOW(), DATE()) instead. A custom report filter accepts date literals, but a custom-button formula does not. Confusing the two contexts produces a class of bugs where LAST_WEEK becomes literal text the platform tries to compare to a Date value, which fails silently or returns nothing.
Date literals in Apex queries
In an Apex SOQL query string, date literals work exactly as in the Developer Console: [SELECT Id FROM Account WHERE LastModifiedDate >= LAST_N_DAYS:30] returns the right records. The literal is not a String constant in Apex; it is parsed by SOQL. You cannot stash it in a variable. Dynamic SOQL needs the literal inside the constructed SOQL string, not passed as a bind variable.
How to use date literals in a SOQL query or report filter
Date literals replace hardcoded dates in queries and report filters, keeping the window relative to today. Pick the right literal for the question you are asking and you eliminate most date-rollover maintenance.
- Identify the date or datetime field
Open the object's schema and confirm whether you are filtering a Date field (CloseDate, Birthdate) or a DateTime field (CreatedDate, LastModifiedDate, SystemModstamp). The literal vocabulary is the same; the expansion semantics differ slightly.
- Match the business question to a literal
Last 30 days? LAST_N_DAYS:30. Last calendar quarter? LAST_QUARTER. Last fiscal quarter? LAST_FISCAL_QUARTER. Today's records? CreatedDate = TODAY. Each business question maps to exactly one right literal.
- Write the SOQL filter
Use comparison operators (=, !=, >, >=, <, <=) for single-date literals like TODAY. Use range syntax (>= LAST_N_DAYS:30 AND <= TODAY) for explicit windows. Date literals are unquoted: LAST_WEEK, not 'LAST_WEEK'.
- Test in Developer Console
Run the query in Developer Console's Query Editor with a known dataset. Verify the row count against the same window in a report or list view. Mismatches usually mean a fiscal-vs-calendar confusion or a time-zone boundary.
- Apply the same literal to reports if applicable
In a report filter, the literal vocabulary is identical. If the SOQL gives the right count, the report filter matches. This consistency is intentional: the same date-literal engine powers reports, list views, and SOQL.
TODAY, YESTERDAY, TOMORROW. Use with = or != operators when you want exactly one day.
LAST_WEEK, THIS_MONTH, NEXT_QUARTER, LAST_90_DAYS. Aligned to calendar boundaries in the user's locale.
THIS_FISCAL_QUARTER, LAST_FISCAL_YEAR, LAST_N_FISCAL_QUARTERS:n. Respect the org's fiscal year configuration.
LAST_N_DAYS:n, N_MONTHS_AGO:n, NEXT_N_WEEKS:n. Take a colon and an integer to define the window length.
- TODAY against a DateTime field expands to the full day in the user's time zone, not the server's. A record created at 11pm UTC by a user in PST may not match the same user's TODAY filter.
- LAST_WEEK and LAST_N_DAYS:7 return different rows. LAST_WEEK is calendar-week-aligned; LAST_N_DAYS:7 is rolling. Pick the one that matches the business question.
- Fiscal literals fail silently if your org's fiscal year setup is wrong. Always confirm Setup, Company Information, Fiscal Year before relying on them.
- Date literals do not work in formula fields, validation rules, or workflow conditions. Use TODAY() and NOW() formula functions in those contexts instead.
Trust & references
Straight from the source - Salesforce's reference material on Date Literal.
- Date Formats and Date LiteralsSalesforce Developers
- Filter Reports by Relative Date ValuesSalesforce Help
Hands-on resources to go deeper on Date Literal.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is a Date Literal in SOQL?
Q2. Why use date literals?
Q3. Which date literal would you use for the past 30 days?
Discussion
Loading discussion…