Report Preferences

Overview

Report preferences let each viewer control how Semaphor interprets Calendar periods and presents formatted values. Open More options → Report preferences from a dashboard to find two independent tabs:

Display formats controls locale and default currency.
Calendar controls timezone and the first day of the week.

These tabs share an inheritance model, but they do different jobs:

Preference area	Controls	Can affect the data query?
Calendar	Timezone, week boundaries, relative periods, and temporal grouping	Yes, when timezone or week boundaries change filtering or grouping
Display formats	Separators, symbol placement, and the fallback currency for currency-intent values	No; these settings change presentation only

One typed value, two responsibilities

Your warehouse produces the typed value. Semaphor carries its meaning, resolves the applicable report and authored presentation policy, and renders it consistently.

Settings available today

Setting	Personal Report preferences	Initial token input	Tenant or organization default
Locale	Yes	`params.valueFormatPreferences.locale`	Yes
Default currency	Yes	`params.valueFormatPreferences.defaultCurrency`	Yes
Timezone	Yes	`params.calendarContext.tz`	Yes
Week starts on	Yes	`params.calendarContext.weekStart`	Yes
Relative-date anchor	No	`params.calendarContext.anchor`	No
Fiscal calendar	No	Optional `params.calendarContext.fiscalCalendar`; governed project or model policy can take precedence	Governed separately

Date and datetime style fields exist in the underlying preference contract, but built-in viewer controls and consumers do not apply them yet. They will be documented when the corresponding rendering capability ships.

How preference inheritance works

Semaphor resolves each preference property independently. The first defined value wins.

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

A project-only or dashboard-only session without an identified user starts with its token input, then uses the authorized resource organization's default and the system fallback.

Inheritance is property by property

A user can choose de-DE as their locale while continuing to inherit EUR from the tenant. Clearing the personal locale reveals the inherited locale; Semaphor does not copy that inherited value into the user's record.

Token values initialize the session

Token inputs are developer-authored starting values for the report session. They do not freeze the resolved preference hierarchy inside the token. When an identified viewer saves or clears a personal preference, the open dashboard uses the newly resolved value without generating a new token.

When supplying calendarContext, provide its complete required shape:

const requestBody = {
  dashboardId: DASHBOARD_ID,
  dashboardSecret: DASHBOARD_SECRET,
  params: {
    calendarContext: {
      tz: 'Europe/Berlin',
      weekStart: 1,
      anchor: 'now',
    },
    valueFormatPreferences: {
      locale: 'de-DE',
      defaultCurrency: 'EUR',
    },
  },
};

Run token generation on your server. Never expose a dashboard or project secret in browser code.

How display precedence works

Preference inheritance produces the viewer's report defaults. An individual value can then have more specific authored formatting:

system fallback
→ resolved report preference
→ semantic field format
→ saved card or column format
→ explicitly bound currency control

Later applicable layers win property by property.

For example:

A viewer inherits locale de-DE and default currency EUR.
A currency-intent metric without an authored currency can render as 1.000,00 €.
If the semantic metric explicitly specifies GBP, GBP wins over the viewer default.
If a table column explicitly specifies USD, the column setting wins.
If an author binds a currency control to that exact column, the selected control value is the final currency override for that target.

An ordinary number does not acquire a currency symbol from the report default. An unbound control does not affect a visual.

Currency presentation is not conversion

Changing USD to EUR changes the currency identity used for symbols, separators, and currency precision. It does not apply an exchange rate or change the underlying numeric value. Perform currency conversion in your warehouse or query.

Locale and currency are also independent. A viewer can use en-GB numeric conventions while displaying USD, or use de-DE conventions while displaying GBP.

Configure defaults

Viewer: Open More options → Report preferences. Each personal choice shows the inherited value it will otherwise use.
Tenant administrator: Configure adjacent Display format defaults and Calendar defaults for the tenant.
Organization administrator: Configure organization-level defaults for users and tenants that do not override them.
Embedding developer: Supply initial values through params.calendarContext and params.valueFormatPreferences.