# Dates, times, and currency (/docs/framework/guides/literals)



Use Kysoql's literal helpers when a SOQL value has syntax that should not be represented by an ordinary JavaScript string.

## Date, DateTime, and Time values [#date-datetime-and-time-values]

```ts
import { soqlDate, soqlDateTime } from "@kysoql/core";
import { db } from "./db";

const query = db
  .selectFrom("Opportunity")
  .select(["Id", "CloseDate", "CreatedDate"])
  .where("CloseDate", ">=", soqlDate("2026-09-01"))
  .where("CreatedDate", "<", soqlDateTime("2026-10-01T00:00:00Z"));
```

| Helper                | Accepted shape                               | Example                                     |
| --------------------- | -------------------------------------------- | ------------------------------------------- |
| `soqlDate(value)`     | `YYYY-MM-DD`                                 | `soqlDate("2026-09-01")`                    |
| `soqlDateTime(value)` | Date plus time and `Z` or an explicit offset | `soqlDateTime("2026-09-01T09:00:00+10:00")` |
| `soqlTime(value)`     | `hh:mm:ssZ` or `hh:mm:ss.SSSZ`               | `soqlTime("09:30:00.000Z")`                 |

The helpers validate the input shape, calendar values, clock values, and timezone offsets. They preserve the value you pass rather than converting it to another timezone.

To use a JavaScript `Date`, convert it explicitly:

```ts
import { soqlDateTime } from "@kysoql/core";

const instant = soqlDateTime(new Date().toISOString());
```

Use a date literal with Date fields, a datetime literal with DateTime fields, and a time literal with Time fields.

## Relative date literals [#relative-date-literals]

```ts
import { soqlRelativeDate } from "@kysoql/core";
import { db } from "./db";

const query = db
  .selectFrom("Opportunity")
  .select(["Id", "CloseDate"])
  .where("CloseDate", "=", soqlRelativeDate("THIS_MONTH"))
  .where("CreatedDate", "=", soqlRelativeDate("LAST_N_DAYS", 30));
```

Common fixed literals include `TODAY`, `YESTERDAY`, `THIS_WEEK`, `LAST_MONTH`, `NEXT_QUARTER`, and the fiscal-calendar equivalents.

Parameterized families include `LAST_N_DAYS`, `NEXT_N_WEEKS`, `N_MONTHS_AGO`, and the matching quarter, year, and fiscal variants.

Pass the count separately:

```ts
import { soqlRelativeDate } from "@kysoql/core";

soqlRelativeDate("LAST_N_DAYS", 30)
```

Kysoql compiles that value as `LAST_N_DAYS:30`.

Salesforce evaluates relative date ranges on the server. Their exact calendar and timezone behaviour comes from Salesforce, not from the JavaScript runtime.

## Currency literals [#currency-literals]

Use `soqlCurrency()` when a multi-currency filter needs an explicit ISO code:

```ts
import { soqlCurrency } from "@kysoql/core";
import { db } from "./db";

const query = db
  .selectFrom("Opportunity")
  .select(["Id", "Amount"])
  .where("Amount", ">=", soqlCurrency("USD", 5000));
// WHERE Amount >= USD5000
```

The ISO code must be exactly three uppercase ASCII letters and the value must be finite. Kysoql validates that shape, but Salesforce still decides whether the currency is enabled in the org.

An `IN` or `NOT IN` list must use either normal numeric values or ISO-coded currency literals. Do not mix the two forms in one list.

For converting selected currency values into the querying user's currency, see [`convertCurrency()`](/docs/framework/guides/select-functions#currency-conversion).