Open source, privacy-first web analytics. Lightweight, cookie-free Google Analytics alternative. Self-hosted or cloud.
TypeScript analyticsanalytics-dashboardclickhouseelixirgoogle-analyticsmarketingopen-source-analyticsphoenixplausible-analyticspostgresqlprivacyprivacy-friendlyself-hostedsimple-analyticsstatisticstailwindcssweb-analyticswebsite-analyticswebsite-statswebsite-tracking
Extract building query date ranges (#6474)
Artur Pata7d91433e4ca5
diff --git a/lib/plausible/stats/query_builder.ex b/lib/plausible/stats/query_builder.exindex 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 doTableDecider,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 doendend- 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) doparsed_query_params|> ParsedQueryParams.to_query!()@@ -169,11 +104,9 @@ defmodule Plausible.Stats.QueryBuilder dodefp set_now(query), do: querydefp 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.exnew file mode 100644index 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+enddiff --git a/test/plausible/stats/query_period_test.exs b/test/plausible/stats/query_period_test.exsnew file mode 100644index 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