Skip to content

Open source, privacy-first web analytics. Lightweight, cookie-free Google Analytics alternative. Self-hosted or cloud.

Extract building query date ranges (#6474)

Artur Pata7d91433e4ca5
diff --git a/lib/plausible/stats/query_builder.ex b/lib/plausible/stats/query_builder.ex
index fb41016866..0784bac368 100644
--- a/lib/plausible/stats/query_builder.ex
+++ b/lib/plausible/stats/query_builder.ex
@@ -15,11 +15,10 @@ defmodule Plausible.Stats.QueryBuilder do
TableDecider,
DateTimeRange,
QueryError,
- QueryInclude
+ QueryInclude,
+ QueryPeriod
}
- alias Plausible.Times
-
@doc """
Runs various validations and builds a `%Query{}` from already parsed params.
@@ -85,70 +84,6 @@ defmodule Plausible.Stats.QueryBuilder do
end
end
- defp build_datetime_range(input_date_range, _site, _relative_date, now)
- when input_date_range in [:realtime, :realtime_30m] do
- duration_minutes =
- case input_date_range do
- :realtime -> 5
- :realtime_30m -> 30
- end
-
- first_datetime = DateTime.shift(now, minute: -duration_minutes)
- last_datetime = DateTime.shift(now, second: 5)
-
- DateTimeRange.new!(first_datetime, last_datetime)
- end
-
- defp build_datetime_range(:day, site, relative_date, now) do
- if Date.compare(Times.to_date(now, site.timezone), relative_date) == :eq do
- DateTimeRange.new!(relative_date, now, site.timezone)
- else
- DateTimeRange.new!(relative_date, relative_date, site.timezone)
- end
- end
-
- defp build_datetime_range(:"24h", _site, _relative_date, now) do
- from = DateTime.shift(now, hour: -24)
- DateTimeRange.new!(from, now)
- end
-
- defp build_datetime_range(:month, site, relative_date, _now) do
- first = relative_date |> Date.beginning_of_month()
- last = relative_date |> Date.end_of_month()
- DateTimeRange.new!(first, last, site.timezone)
- end
-
- defp build_datetime_range(:year, site, relative_date, _now) do
- first = relative_date |> Plausible.Times.beginning_of_year()
- last = relative_date |> Plausible.Times.end_of_year()
- DateTimeRange.new!(first, last, site.timezone)
- end
-
- defp build_datetime_range(:all, site, relative_date, _now) do
- start_date = Plausible.Sites.stats_start_date(site) || relative_date
- DateTimeRange.new!(start_date, relative_date, site.timezone)
- end
-
- defp build_datetime_range({:last_n_days, n}, site, relative_date, _now) do
- last = relative_date |> Date.add(-1)
- first = relative_date |> Date.add(-n)
- DateTimeRange.new!(first, last, site.timezone)
- end
-
- defp build_datetime_range({:last_n_months, n}, site, relative_date, _now) do
- last = relative_date |> Date.shift(month: -1) |> Date.end_of_month()
- first = relative_date |> Date.shift(month: -n) |> Date.beginning_of_month()
- DateTimeRange.new!(first, last, site.timezone)
- end
-
- defp build_datetime_range({:date_range, from, to}, site, _relative_date, _now) do
- DateTimeRange.new!(from, to, site.timezone)
- end
-
- defp build_datetime_range({:datetime_range, from, to}, _site, _relative_date, _now) do
- DateTimeRange.new!(from, to)
- end
-
defp do_build(parsed_query_params, site, debug_metadata) do
parsed_query_params
|> ParsedQueryParams.to_query!()
@@ -169,11 +104,9 @@ defmodule Plausible.Stats.QueryBuilder do
defp set_now(query), do: query
defp set_utc_time_range(query, site, relative_date) do
- relative_date = relative_date || Times.to_date(query.now, site.timezone)
-
utc_time_range =
query.input_date_range
- |> build_datetime_range(site, relative_date, query.now)
+ |> QueryPeriod.build_range_for_site(site, relative_date, query.now)
|> DateTimeRange.to_timezone("Etc/UTC")
Query.set(query, utc_time_range: utc_time_range)
diff --git a/lib/plausible/stats/query_period.ex b/lib/plausible/stats/query_period.ex
new file mode 100644
index 0000000000..4b06b10ba5
--- /dev/null
+++ b/lib/plausible/stats/query_period.ex
@@ -0,0 +1,228 @@
+defmodule Plausible.Stats.QueryPeriod do
+ @moduledoc """
+ Builds the time range covered by a stats query from parsed parameters.
+ """
+
+ alias Plausible.Stats.DateTimeRange
+ alias Plausible.Times
+
+ @doc """
+ Resolves an `input_date_range` for the site and builds the corresponding
+ `%DateTimeRange{}` anchored to the site's timezone.
+
+ `relative_date` may be `nil`, in which case it defaults to today in the
+ site's timezone.
+ """
+ def build_range_for_site(input_date_range, %Plausible.Site{} = site, relative_date, now) do
+ relative_date = relative_date || Times.to_date(now, site.timezone)
+
+ input_date_range
+ |> resolve_input_date_range(site, relative_date)
+ |> build_datetime_range(site.timezone, relative_date, now)
+ end
+
+ @doc """
+ For some query periods, `now` or `relative_date` or both are irrelevant
+ for resolving the date range. This dispatcher ensures that
+ """
+ def build_datetime_range(:realtime, timezone, _relative_date, now),
+ do: build_realtime_range(timezone, now, 5)
+
+ def build_datetime_range(:realtime_30m, timezone, _relative_date, now),
+ do: build_realtime_range(timezone, now, 30)
+
+ def build_datetime_range(:day, timezone, relative_date, now),
+ do: build_day_range(timezone, relative_date, now)
+
+ def build_datetime_range(:"24h", timezone, _relative_date, now),
+ do: build_24h_range(timezone, now)
+
+ def build_datetime_range(:month, timezone, relative_date, _now),
+ do: build_month_range(timezone, relative_date)
+
+ def build_datetime_range(:year, timezone, relative_date, _now),
+ do: build_year_range(timezone, relative_date)
+
+ def build_datetime_range({:last_n_days, n}, timezone, relative_date, _now),
+ do: build_last_n_days_range(timezone, n, relative_date)
+
+ def build_datetime_range({:last_n_months, n}, timezone, relative_date, _now),
+ do: build_last_n_months_range(timezone, n, relative_date)
+
+ def build_datetime_range({:date_range, from, to}, timezone, _relative_date, _now),
+ do: build_date_range(timezone, from, to)
+
+ def build_datetime_range({:datetime_range, from, to}, timezone, _relative_date, _now),
+ do: build_range_from_datetimes(timezone, from, to)
+
+ @doc """
+ Resolves any site-dependent shape (currently only `:all`, which needs the
+ site's stats start date) into a shape `build_datetime_range/4` can handle
+ from a timezone alone. Other shapes pass through unchanged.
+ """
+ def resolve_input_date_range(:all, %Plausible.Site{} = site, relative_date) do
+ start_date = Plausible.Sites.stats_start_date(site) || relative_date
+ {:date_range, start_date, relative_date}
+ end
+
+ def resolve_input_date_range(input_date_range, _site, _relative_date),
+ do: input_date_range
+
+ @doc """
+ Builds a realtime window of `duration_minutes` ending slightly after `now`.
+
+ ## Examples
+
+ iex> QueryPeriod.build_realtime_range("Etc/UTC", ~U[2026-05-05 12:30:00Z], 5)
+ %DateTimeRange{first: ~U[2026-05-05 12:25:00Z], last: ~U[2026-05-05 12:30:05Z]}
+
+ iex> QueryPeriod.build_realtime_range("Etc/UTC", ~U[2026-05-05 12:30:00Z], 30)
+ %DateTimeRange{first: ~U[2026-05-05 12:00:00Z], last: ~U[2026-05-05 12:30:05Z]}
+ """
+ def build_realtime_range(timezone, now, duration_minutes) do
+ first_datetime = DateTime.shift(now, minute: -duration_minutes)
+ last_datetime = DateTime.shift(now, second: 5)
+
+ DateTimeRange.new!(first_datetime, last_datetime)
+ |> DateTimeRange.to_timezone(timezone)
+ end
+
+ @doc """
+ Builds the range for a single calendar day. When `date` matches today in
+ `timezone`, the range is truncated at `now`; otherwise it spans the full
+ local day.
+
+ ## Examples
+
+ iex> QueryPeriod.build_day_range("Etc/UTC", ~D[2026-05-05], ~U[2026-05-05 12:30:00Z])
+ %DateTimeRange{first: ~U[2026-05-05 00:00:00Z], last: ~U[2026-05-05 12:30:00Z]}
+
+ iex> QueryPeriod.build_day_range("Etc/UTC", ~D[2026-05-04], ~U[2999-01-01 00:00:00Z])
+ %DateTimeRange{first: ~U[2026-05-04 00:00:00Z], last: ~U[2026-05-04 23:59:59Z]}
+
+ iex> QueryPeriod.build_day_range("Europe/Tallinn", ~D[2026-01-15], ~U[2999-01-01 00:00:00Z]) |> DateTimeRange.to_timezone("Etc/UTC")
+ %DateTimeRange{first: ~U[2026-01-14 22:00:00Z], last: ~U[2026-01-15 21:59:59Z]}
+ """
+ def build_day_range(timezone, date, now) do
+ if Date.compare(Times.to_date(now, timezone), date) == :eq do
+ DateTimeRange.new!(date, now, timezone)
+ else
+ DateTimeRange.new!(date, date, timezone)
+ end
+ end
+
+ @doc """
+ Builds the 24-hour window ending at `now`.
+
+ ## Examples
+
+ iex> QueryPeriod.build_24h_range("Etc/UTC", ~U[2026-05-05 12:30:00Z])
+ %DateTimeRange{first: ~U[2026-05-04 12:30:00Z], last: ~U[2026-05-05 12:30:00Z]}
+ """
+ def build_24h_range(timezone, now) do
+ from = DateTime.shift(now, hour: -24)
+
+ DateTimeRange.new!(from, now)
+ |> DateTimeRange.to_timezone(timezone)
+ end
+
+ @doc """
+ Builds the range spanning the calendar month containing `date`.
+
+ ## Examples
+
+ iex> QueryPeriod.build_month_range("Etc/UTC", ~D[2026-05-15])
+ %DateTimeRange{first: ~U[2026-05-01 00:00:00Z], last: ~U[2026-05-31 23:59:59Z]}
+
+ iex> QueryPeriod.build_month_range("Europe/Tallinn", ~D[2026-01-15]) |> DateTimeRange.to_timezone("Etc/UTC")
+ %DateTimeRange{first: ~U[2025-12-31 22:00:00Z], last: ~U[2026-01-31 21:59:59Z]}
+ """
+ def build_month_range(timezone, date) do
+ first = Date.beginning_of_month(date)
+ last = Date.end_of_month(date)
+ DateTimeRange.new!(first, last, timezone)
+ end
+
+ @doc """
+ Builds the range spanning the calendar year containing `date`.
+
+ ## Examples
+
+ iex> QueryPeriod.build_year_range("Etc/UTC", ~D[2026-05-15])
+ %DateTimeRange{first: ~U[2026-01-01 00:00:00Z], last: ~U[2026-12-31 23:59:59Z]}
+
+ iex> QueryPeriod.build_year_range("Europe/Tallinn", ~D[2026-05-15]) |> DateTimeRange.to_timezone("Etc/UTC")
+ %DateTimeRange{first: ~U[2025-12-31 22:00:00Z], last: ~U[2026-12-31 21:59:59Z]}
+ """
+ def build_year_range(timezone, date) do
+ first = Times.beginning_of_year(date)
+ last = Times.end_of_year(date)
+ DateTimeRange.new!(first, last, timezone)
+ end
+
+ @doc """
+ Builds a range spanning `n` full calendar days ending the day before
+ `end_date`.
+
+ ## Examples
+
+ iex> QueryPeriod.build_last_n_days_range("Etc/UTC", 7, ~D[2026-05-08])
+ %DateTimeRange{first: ~U[2026-05-01 00:00:00Z], last: ~U[2026-05-07 23:59:59Z]}
+
+ iex> QueryPeriod.build_last_n_days_range("Europe/Tallinn", 7, ~D[2026-05-08]) |> DateTimeRange.to_timezone("Etc/UTC")
+ %DateTimeRange{first: ~U[2026-04-30 21:00:00Z], last: ~U[2026-05-07 20:59:59Z]}
+ """
+ def build_last_n_days_range(timezone, n, end_date) do
+ last = Date.add(end_date, -1)
+ first = Date.add(end_date, -n)
+ DateTimeRange.new!(first, last, timezone)
+ end
+
+ @doc """
+ Builds a range spanning `n` full calendar months ending the month
+ before `end_date`'s month.
+
+ ## Examples
+
+ iex> QueryPeriod.build_last_n_months_range("Etc/UTC", 3, ~D[2026-05-15])
+ %DateTimeRange{first: ~U[2026-02-01 00:00:00Z], last: ~U[2026-04-30 23:59:59Z]}
+
+ iex> QueryPeriod.build_last_n_months_range("Europe/Tallinn", 3, ~D[2026-05-15]) |> DateTimeRange.to_timezone("Etc/UTC")
+ %DateTimeRange{first: ~U[2026-01-31 22:00:00Z], last: ~U[2026-04-30 20:59:59Z]}
+ """
+ def build_last_n_months_range(timezone, n, end_date) do
+ last = end_date |> Date.shift(month: -1) |> Date.end_of_month()
+ first = end_date |> Date.shift(month: -n) |> Date.beginning_of_month()
+ DateTimeRange.new!(first, last, timezone)
+ end
+
+ @doc """
+ Builds a range from explicit start/end calendar dates,
+ from start of first day to end of last day in `timezone`.
+
+ ## Examples
+
+ iex> QueryPeriod.build_date_range("Etc/UTC", ~D[2026-05-01], ~D[2026-05-10])
+ %DateTimeRange{first: ~U[2026-05-01 00:00:00Z], last: ~U[2026-05-10 23:59:59Z]}
+
+ iex> QueryPeriod.build_date_range("Europe/Tallinn", ~D[2026-05-01], ~D[2026-05-10]) |> DateTimeRange.to_timezone("Etc/UTC")
+ %DateTimeRange{first: ~U[2026-04-30 21:00:00Z], last: ~U[2026-05-10 20:59:59Z]}
+ """
+ def build_date_range(timezone, from, to) do
+ DateTimeRange.new!(from, to, timezone)
+ end
+
+ @doc """
+ Builds a range from explicit start/end datetimes, which may have any time zone,
+ then shifts them to be in `timezone`.
+
+ ## Examples
+
+ iex> QueryPeriod.build_range_from_datetimes("Etc/UTC", ~U[2026-05-01 06:00:00Z], ~U[2026-05-01 18:00:00Z])
+ %DateTimeRange{first: ~U[2026-05-01 06:00:00Z], last: ~U[2026-05-01 18:00:00Z]}
+ """
+ def build_range_from_datetimes(timezone, from, to) do
+ DateTimeRange.new!(from, to)
+ |> DateTimeRange.to_timezone(timezone)
+ end
+end
diff --git a/test/plausible/stats/query_period_test.exs b/test/plausible/stats/query_period_test.exs
new file mode 100644
index 0000000000..fd2084caa1
--- /dev/null
+++ b/test/plausible/stats/query_period_test.exs
@@ -0,0 +1,131 @@
+defmodule Plausible.Stats.QueryPeriodTest do
+ use ExUnit.Case, async: true
+
+ alias Plausible.Stats.{DateTimeRange, QueryPeriod}
+
+ doctest QueryPeriod, import: true
+
+ @now_irrelevant ~U[2999-01-01 00:00:00Z]
+
+ describe "build_datetime_range/4" do
+ test "the day period truncates at \"now\" when the date is today" do
+ now = ~U[2026-05-05 12:30:00Z]
+ range = QueryPeriod.build_datetime_range(:day, "Etc/UTC", ~D[2026-05-05], now)
+ assert range.first == ~U[2026-05-05 00:00:00Z]
+ assert range.last == now
+ end
+
+ test "a custom date range in Tallinn correctly spans a DST transition (EET to EEST)" do
+ range =
+ QueryPeriod.build_datetime_range(
+ {:date_range, ~D[2026-03-15], ~D[2026-04-15]},
+ "Europe/Tallinn",
+ ~D[2026-04-01],
+ @now_irrelevant
+ )
+
+ assert DateTime.to_iso8601(range.first) == "2026-03-15T00:00:00+02:00"
+ assert DateTime.to_iso8601(range.last) == "2026-04-15T23:59:59+03:00"
+ end
+
+ for timezone <- ["Etc/UTC", "America/New_York", "Europe/Tallinn", "Asia/Tokyo"] do
+ test "the last 24 hours window covers the same UTC moments regardless of timezone (#{timezone})" do
+ now = ~U[2026-05-05 12:30:00Z]
+
+ utc_range =
+ QueryPeriod.build_datetime_range(:"24h", unquote(timezone), ~D[2026-05-05], now)
+ |> DateTimeRange.to_timezone("Etc/UTC")
+
+ assert utc_range.first == ~U[2026-05-04 12:30:00Z]
+ assert utc_range.last == now
+ end
+ end
+
+ test "the month period spans 28 days in a non-leap-year February" do
+ range =
+ QueryPeriod.build_datetime_range(:month, "Etc/UTC", ~D[2026-02-10], @now_irrelevant)
+
+ assert range.first == ~U[2026-02-01 00:00:00Z]
+ assert range.last == ~U[2026-02-28 23:59:59Z]
+ end
+
+ test "the month period spans 29 days in a leap-year February" do
+ range =
+ QueryPeriod.build_datetime_range(:month, "Etc/UTC", ~D[2024-02-10], @now_irrelevant)
+
+ assert range.first == ~U[2024-02-01 00:00:00Z]
+ assert range.last == ~U[2024-02-29 23:59:59Z]
+ end
+
+ test "the year period still ends December 31 in a leap year" do
+ range =
+ QueryPeriod.build_datetime_range(:year, "Etc/UTC", ~D[2024-06-15], @now_irrelevant)
+
+ assert range.first == ~U[2024-01-01 00:00:00Z]
+ assert range.last == ~U[2024-12-31 23:59:59Z]
+ end
+ end
+
+ describe "build_range_for_site/4" do
+ test "anchors the range in the site's timezone" do
+ site = %Plausible.Site{timezone: "America/New_York"}
+
+ range = QueryPeriod.build_range_for_site(:day, site, ~D[2026-05-04], @now_irrelevant)
+
+ assert range.first.time_zone == "America/New_York"
+ assert range.last.time_zone == "America/New_York"
+ assert DateTime.to_iso8601(range.first) == "2026-05-04T00:00:00-04:00"
+ assert DateTime.to_iso8601(range.last) == "2026-05-04T23:59:59-04:00"
+ end
+
+ test "the \"all\" period starts at the site's stats start date" do
+ site = %Plausible.Site{timezone: "Etc/UTC", stats_start_date: ~D[2024-01-15]}
+
+ range = QueryPeriod.build_range_for_site(:all, site, ~D[2026-05-05], @now_irrelevant)
+
+ assert DateTime.to_date(range.first) == ~D[2024-01-15]
+ assert DateTime.to_date(range.last) == ~D[2026-05-05]
+ end
+
+ test "without a relative date, uses today in the site's timezone" do
+ site = %Plausible.Site{timezone: "Etc/UTC"}
+ now = ~U[2026-05-05 12:30:00Z]
+
+ range = QueryPeriod.build_range_for_site(:day, site, nil, now)
+
+ assert range.first == ~U[2026-05-05 00:00:00Z]
+ assert range.last == now
+ end
+
+ test "a Tallinn site's month range is anchored to Tallinn local time" do
+ site = %Plausible.Site{timezone: "Europe/Tallinn"}
+
+ range = QueryPeriod.build_range_for_site(:month, site, ~D[2026-01-15], @now_irrelevant)
+
+ assert range.first.time_zone == "Europe/Tallinn"
+ assert range.last.time_zone == "Europe/Tallinn"
+ assert DateTime.to_iso8601(range.first) == "2026-01-01T00:00:00+02:00"
+ assert DateTime.to_iso8601(range.last) == "2026-01-31T23:59:59+02:00"
+ end
+ end
+
+ describe "resolve_input_date_range/3" do
+ test "the \"all\" period resolves to a concrete date range using the site's stats start date" do
+ site = %Plausible.Site{stats_start_date: ~D[2024-01-15]}
+
+ assert QueryPeriod.resolve_input_date_range(:all, site, ~D[2026-05-05]) ==
+ {:date_range, ~D[2024-01-15], ~D[2026-05-05]}
+ end
+
+ test "other periods pass through unchanged" do
+ site = %Plausible.Site{stats_start_date: ~D[2024-01-15]}
+
+ assert QueryPeriod.resolve_input_date_range(:day, site, ~D[2026-05-05]) == :day
+
+ assert QueryPeriod.resolve_input_date_range({:last_n_days, 7}, site, ~D[2026-05-05]) ==
+ {:last_n_days, 7}
+
+ assert QueryPeriod.resolve_input_date_range(:realtime, site, ~D[2026-05-05]) == :realtime
+ end
+ end
+end