Setting Date Range

When a data source extracts time-sensitive data, you need to tell Dataddo which time period to load. Instead of fixed dates, Dataddo uses a dynamic date range: a rule defined relative to the extraction time, such as "yesterday" or "last month". The rule is evaluated at every extraction, so the time window moves forward automatically with each run.

For example, a source configured with the date range Yesterday and a daily sync always loads the previous day's data: on July 10 it loads July 9, on July 11 it loads July 10, and so on. Combined with an appropriate write mode (such as append or upsert), this is how you build an incrementally growing dataset from any time-based API.

This article explains how to configure the date range beyond the standard date picker, using date range expressions directly in your source configuration.

Where Date Range Expressions Are Used

For most connectors, you simply pick a date range (Today, Yesterday, Last 7 days, Last month, etc.) in the source configuration and never need expressions. Use expressions when:

• The range you need is not offered by the date picker (e.g., "last 45 days" or "next 7 days").
• You are configuring a custom API source and need to insert dates into the request URL, body, or headers (on the Sources page, click your data source and open the Advanced Settings tab).
• You are writing a Custom SQL Query for a database source and need incremental date filtering in the statement.
• You want to partition destination files or database tables by date, e.g. write each day's data to its own file or table (see Partitioning Files and Tables by Date).

Quick Start

To pass the configured date range to an API, insert the {{dateRange}} placeholder into the request URL:

https://api.service.com/endpoint?startDate={{dateRange}}&endDate={{dateRange}}

At extraction time, Dataddo resolves the placeholders using the date range selected in the source configuration:

https://api.service.com/endpoint?startDate=2026-07-03&endDate=2026-07-09

Two rules govern the resolution:

• The first occurrence is replaced with the start date of the range and the second occurrence with the end date. A single occurrence resolves to the start date.
• A single field (URL, request body, or header) can contain at most two placeholders. If you need the dates more often, or the end date before the start date, use the dateRangeStart() and dateRangeEnd() functions.

Date Range Expressions

Instead of the {{dateRange}} placeholder, you can write the date range rule itself, in the format:

{{<start><unit><stop>}}

Weeks, months, and years are calendar-aligned: weeks run Monday to Sunday, months from the first to the last day, and years from January 1 to December 31. The start of a range always resolves to the beginning of its period (00:00:00) and the end to the end of its period (23:59:59).

Examples

Assuming the extraction runs on Friday, July 10, 2026:

The same positional rules apply as for {{dateRange}}: first occurrence is the start date, second is the end date. For example, to always extract the last 30 full days:

https://api.service.com/endpoint?startDate={{30d1}}&endDate={{30d1}}

Formatting the Output

By default, dates are inserted in the ISO 8601 date format (Y-m-d, e.g. 2026-07-09). If your API requires a different format, append a PHP date format after a pipe character. This works with both the {{dateRange}} placeholder and explicit expressions.

For a date resolving to July 9, 2026:

dateRangeStart() and dateRangeEnd() Functions

For full control over which date appears where, use the dateRangeStart() and dateRangeEnd() functions. Unlike the positional placeholders, they can be used any number of times, in any order:

https://api.service.com/endpoint?to={{ dateRangeEnd('7d1', 'Y-m-d') }}&from={{ dateRangeStart('7d1', 'Y-m-d') }}

• The first argument is a date range expression (see above), or ':value' to inherit the date range configured in the source.
• The second argument (optional) is the output date format. The default is Y-m-d.

These functions are also the recommended way to implement incremental extraction in a Custom SQL Query for database sources:

SELECT id, status, total, updated_at
FROM orders
WHERE updated_at >= '{{ dateRangeStart('1d0', 'Y-m-d H:i:s') }}'
  AND updated_at <  '{{ dateRangeEnd('1d0', 'Y-m-d H:i:s') }}'

Partitioning Files and Tables by Date

Date placeholders are not limited to sources. They also work in destination configurations, where they let you split continuously synced data into date-based partitions:

File-based destinations

E.g. SFTP, Amazon S3, Google Cloud Storage. Use placeholders in the file name or path to write each run's data to its own file or folder:

exports/orders/{{today|Y/m/d}}/orders.csv     ->  exports/orders/2026/07/10/orders.csv
orders-{{yesterday}}.csv                      ->  orders-20260709.csv

Database destinations

Use placeholders in the table name to write each period's data into its own table:

orders_{{yesterday}}     ->  orders_20260709   (one table per day)
orders_{{today|Ym}}      ->  orders_202607     (one table per month)

Because the placeholders are re-evaluated at every run, a scheduled flow automatically rolls over to a new file or table when the date changes, with no manual maintenance.

Choosing the Right Window

The date range must be at least as wide as the interval between two extractions, otherwise data that arrives between runs is silently missed: