Document period-to-date filter

guides/filters.mdx

@@ -54,6 +54,7 @@ To learn more about using filters, check out our docs on limiting data using fil
 | not in the next    | Only pulls in rows where the dates for the field selected are not in the next time period you entered.                                                                                  |
 | in the current     | Only pulls in rows where the dates for the field selected are in the current time period you entered: "in the current day", "in the current week", "in the current quarter" etc.        |
 | not in the current | Only pulls in rows where the dates for the field selected are not in the current time period you entered.                                                                               |
+| is period-to-date | Only pulls in rows where the dates for the field selected are at or before the current position within their period, across *all* periods (e.g. "in the month-to-date" returns rows up to today's day-of-month for every month, not just this month). Supports `week`, `month`, `quarter`, and `year`. See [In the period-to-date](#in-the-period-to-date). |
 | is before          | Only pulls in rows where the dates for the field selected are strictly before the date you entered.                                                                                     |
 | is on or before    | Only pulls in rows where the dates for the field selected are on or before the date you entered.                                                                                        |
 | is after           | Only pulls in rows where the dates for the field selected are strictly after the date you entered.                                                                                      |
@@ -165,6 +166,24 @@ The below examples show possible date/timestamp filter combinations and their co
    - You can configure this to a different day in your database connection settings
    - Week boundaries are always at midnight (00:00:00)
 
+#### Is period-to-date
+
+The **is period-to-date** filter returns rows at or before the current position within their period, across every period in your data. Pick a unit — `week`, `month`, `quarter`, or `year` — and Lightdash filters each period down to the same relative point as today.
+
+For example, if today is the 15th of the month, **in the month-to-date**:
+- Includes rows dated on or before the 15th of *any* month (Jan 1–15, Feb 1–15, Mar 1–15, …), not just this month.
+- Is designed for like-for-like comparisons across periods, such as this MTD versus the same MTD in prior months.
+
+**When to use `in the period-to-date` vs. `in the current`:**
+
+| You want to…                                                              | Use                    |
+| :------------------------------------------------------------------------ | :--------------------- |
+| Compare month-to-date, quarter-to-date, or year-to-date across periods    | `in the period-to-date` |
+| Restrict data to only the current period (this month, this quarter, etc.) | `in the current`        |
+
+<Info>
+  `is period-to-date` is only available on Explore, chart, and dashboard filters. It is not supported as a YAML metric filter in your dbt project.
+</Info>
 
 ## Date filter examples
 

references/metrics.mdx

@@ -2057,6 +2057,14 @@ filters:
   - created_at: 'inTheCurrent month'
 ```
 
+<Note>
+  The **in the period-to-date** filter (e.g. month-to-date, year-to-date) is only available on charts and dashboards — it is not supported as a YAML metric filter.
+
+  It filters to the same position within *every* period (for example, "day of month" across all months), not to the current period only. Use it to compare like-for-like across periods (e.g. this MTD vs. last MTD). If you want to restrict data to only the current period, use `in the current` instead.
+
+  See [Filters reference](/guides/filters#in-the-period-to-date) for details.
+</Note>
+
 ### Special characters in filters
 
 To use special characters such as `%!_>` in your filter value you can either put the value in quotes, or escape special characters with a backslash `\`. For example, if you wanted to filter for subscription status of `is_subscribed` you can write the metric in one of these ways: