Calendar

Overview

Calendar preferences define how Semaphor interprets Calendar periods. They affect:

• relative date filters such as "this week", "last month", and "year to date";
• week boundaries and week-based grouping;
• the local date and offset used to display datetime values; and
• timezone-sensitive filtering and temporal grouping.

Open More options → Report preferences → Calendar to configure a personal timezone and first day of the week.

Calendar preferences do not select a date-format pattern such as DD/MM/YYYY. Locale-aware date and datetime style preferences are a separate display-format capability and are not active in built-in consumers yet.

Preference inheritance

Personal timezone and week-start preferences use the Report Preferences hierarchy. Each property resolves independently.

For a tenant user:

personal tenant-user preference
→ initial session value from the token
→ tenant default
→ tenant's organization default
→ system fallback

For an organization user:

personal user preference
→ initial session value from the token
→ user's organization default
→ system fallback

For example, a user can choose America/Chicago while continuing to inherit Monday as the first day of the week. Clearing the personal timezone reveals the next inherited timezone.

See Report Preferences for the complete inheritance model and live-session behavior.

Configure Calendar preferences

Personal preference

Open More options → Report preferences → Calendar. You can use the displayed inherited defaults or save a custom timezone and week start. A saved change updates the open report without generating a new token.

Initial embedded-session Calendar

Pass a complete calendarContext inside params when generating a token:

const requestBody = {
  dashboardId: DASHBOARD_ID,
  dashboardSecret: DASHBOARD_SECRET,
  params: {
    calendarContext: {
      tz: 'America/Chicago',
      weekStart: 0,
      anchor: 'now',
    },
  },
};

const response = await fetch(TOKEN_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(requestBody),
});

Token generation belongs on your server. Never expose DASHBOARD_SECRET or PROJECT_SECRET in browser code.

Tenant default

Set the inherited Calendar default for a tenant through the Management API:

curl -X PUT https://semaphor.cloud/api/management/v1/tenants/{tenantId} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "defaultCalendarContext": {
      "tz": "Europe/London",
      "weekStart": 1
    }
  }'

Organization administrators can configure the corresponding organization default in Semaphor administration or with the Management API.

How Calendar settings affect a report

Week start and relative filters

The weekStart value determines how "this week" and other week-relative filters are calculated.

For the week containing January 8, 2025:

It also determines the boundary of a week grouping.

Timezone and date boundaries

Timezone determines which local Calendar date contains an instant. Consider 2025-01-16T04:00:00Z:

The applicable timezone ensures filtering, grouping, and datetime display use the viewer's expected Calendar boundary.

Relative-date anchor

anchor defines the reference instant for relative date expressions. It is a session input, not an editable personal preference.

Use now for a live report:

{
  "tz": "America/New_York",
  "weekStart": 0,
  "anchor": "now"
}

Use a fixed ISO instant for a reproducible point-in-time session:

{
  "tz": "America/New_York",
  "weekStart": 0,
  "anchor": { "iso": "2025-01-15T00:00:00.000Z" }
}

Fiscal calendar

A token can optionally seed a month-aligned fiscal calendar:

{
  "tz": "America/New_York",
  "weekStart": 0,
  "anchor": "now",
  "fiscalCalendar": {
    "kind": "month_aligned",
    "yearStartMonth": 7
  }
}

Fiscal Calendar policy is not a personal Report Preferences field. Governed project or semantic-model policy can take precedence during query execution.

How dates work

Every date in a report follows the report's calendar: its timezone, its first day of the week and, for relative ranges, its anchor. The same rules apply to cards, dashboard filters, comparisons, scheduled reports and PDF exports.

Picking dates

The date picker shows the report's calendar, not your computer's. Its weeks start on the report's first day of the week, and today is today in the report's timezone. A day you pick is that day in the report's timezone, so on a report set to America/Chicago, picking October 1 means Chicago's October 1 whether you are in Chicago, London or Mumbai.

Ranges include their last day

A date range includes both of the days you pick, in full. October 1 to October 31 includes every moment of October 31, down to the smallest fraction of a second your database stores. A range on a date column includes both dates as written.

Daylight saving time

A day with a daylight saving change has 23 or 25 hours, and a range covers the whole day either way. A time that falls in the hour the clocks skip moves forward to the first time after it. A time in the hour that repeats means its first occurrence.

Timestamps without a timezone

When a range counts back from your latest data, its starting point is the newest timestamp in your database. A timestamp stored with a timezone or an offset means that moment. A timestamp stored without one is read as UTC, unless its column declares a timezone, such as a ClickHouse DateTime64(3, 'America/Chicago') column. A date is the start of that day in the report's timezone. See Ranges that follow your data.

February 29

A comparison with the previous year moves each date back one year. February 29 has no counterpart in most years, so a range that starts or ends on February 29 compares with one that starts or ends on February 28. In a chart by day, February 29 shows no previous-year value.

Calendar context properties

When provided in a token, calendarContext is a complete object:

The personal Report Preferences UI edits only tz and weekStart.

Related

• Report Preferences
• Display formats
• Filters
• Token API