Release Notes

Find your current version: docker logs <container> | grep "Semaphor v"

For upgrade procedures, see the Upgrade Guide.

v0.1.65

July 29, 2026

What's New

Expanded query editing. Authors can open SQL and Python in a larger focused editor, switch between both stages without losing the active editing session, and run the query directly from the expanded view.

Improvements

Permission-aligned dashboard actions. Create, duplicate, and validate actions now appear only when the current user has the corresponding project permission, and dashboard creation also enforces that permission on the server.
Git-aware dashboard duplication. Duplicating from the dashboard catalog now honors commit-on-save projects by requesting a commit message and clearly reporting partial failures when the duplicate is saved but its Git commit fails.
Permission-faithful tenant preview. View-as-tenant now enables editing only when the selected tenant user has edit access; otherwise it provides a read-only inspection mode with an explanation.
Actionable visual failures. Query and rendering failures now show consistent guidance across charts, KPIs, and custom visuals, including author diagnostics, viewer-facing next steps, and retry support where available.

Bug Fixes

Tenant preview session isolation. Switching preview actors now clears the previously selected dashboard state, preventing one tenant simulation from leaking stale dashboard context into the next.

Upgrade Notes

Schema changes: None.
New env vars: None.
Breaking changes: None.

v0.1.64

July 29, 2026

What's New

Machine-readable dashboard tags. Authors can classify dashboards with canonical tags in the console, while Management API and MCP clients can create, update, inspect, and filter accessible dashboards by exact all/any tag matches or dashboard kind; tags follow dashboards through duplication and new-target migration.
Persisted row-level security. Admins can author reusable Unified RLS rules, target tables by explicit list, schema, or shared column, and bind actor-specific values through assignments for organization users, all tenants, individual tenants, and tenant users.
Security validation and resolution preview. Admins and Management API clients can validate policy definitions and assignments without saving, preview the effective CLS, SLS, and RLS for an actor, and use structured diagnostics and remediation details to resolve conflicts or missing values.
Safer tenant simulation. View-as-tenant now discovers required plain and secret token inputs before loading a dashboard, and authorized admins can inspect card configuration and query setup with reversible, in-memory changes that never save to the dashboard or visual library.

Improvements

Consistent fail-closed enforcement. Invalid or unresolved Unified RLS now blocks token creation, queries, SQL, and metadata discovery before work reaches the data service, returning stable diagnostic codes and request IDs for administrator review.
Scalable dashboard discovery. Dashboard search, tag and kind filtering, authorization, totals, and pagination now run as one consistently ordered catalog query, improving accuracy and responsiveness for projects with large dashboard collections.

Bug Fixes

Semantic source selection. Dataset selection and AI context now distinguish identically named or identified datasets from different semantic domains, preventing the wrong source from being removed, deduplicated, or marked unreachable.
Table export column order. Local and asynchronous CSV exports now preserve the authored table field order and keep comparison columns beside the correct metric, including when metric labels repeat.

Upgrade Notes

Schema changes: Adds the Dashboard.tags string-array column. Run prisma migrate deploy before starting the new app image.
New env vars: None.
Breaking changes: Unified Security writes now fail closed with 422 when persisted RLS configuration is invalid, so API clients must handle the structured diagnostic error envelope. Dashboard-list clients must also send canonical, non-repeated scalar values for search, tagMatch, kind, limit, and offset; invalid or repeated values now return 400.

v0.1.61

July 20, 2026

What's New

Report display preferences. Viewers can choose a personal locale and default currency from Report preferences, while organization and tenant admins can set inherited defaults through settings or the Management API.
Dashboard currency controls. Authors can bind a manual currency-code control to an eligible KPI or table metric so viewers can switch its display currency without rerunning the query or converting the underlying value.
Consistent numeric presentation. Supported built-in KPIs, summaries, charts, standard, aggregate, pivot, and Matrix tables now apply the same authored formats, locale, default currency, and currency-control selection across the dashboard, table CSVs, PDFs, scheduled reports, and deterministic Briefing content.
Grand totals in delivered tables. Config-driven flat tables with Totals enabled now include one authoritative, fully filtered total row in on-demand CSV and PDF output and in one-time asynchronous CSV exports, including server-paginated and multi-chunk exports.

Improvements

Live report context. Calendar preference changes now take effect in the open dashboard without regenerating its token, and exports capture the Calendar and display preferences active when the export or recurring delivery is created.
Safer dashboard migration. Organization admins can migrate dashboards between accessible projects in the same organization, while inaccessible targets and cross-organization moves are rejected consistently during analysis and migration.

Bug Fixes

Semantic field labels. Moving fields between visual shelves now preserves customer-authored semantic labels instead of replacing them with labels derived from physical field names.
Embedded dashboard controls. Hiding Dashboard Hub now also hides the default-dashboard badge and toggle, preventing navigation-related controls from leaking into restricted embedded experiences.

Upgrade Notes

Schema changes: Adds nullable display-format preference storage for organization users, tenant users, tenants, and organizations. Run prisma migrate deploy before starting the new app image.
New env vars: None.
Breaking changes: Token clients must replace params.currencyFormat with params.valueFormatPreferences (locale and defaultCurrency). Deploy the app, react-semaphor, and scheduler changes together because asynchronous exports now require the new report-context formatting envelope; custom scheduler stacks must also apply the updated template granting export workers s3:GetObject access.

v0.1.60

July 14, 2026

What's New

Field date filter comparisons. Dashboard date filters tied to a specific field can now drive period comparisons for matching visuals, with options for Off, previous period, previous year, offsets, to-date comparison, and weekday alignment. Global Date still takes precedence when it governs the visual.
Embedded dashboard chrome controls. Token configuration can now hide Dashboard Hub navigation, dashboard sharing, and group-management controls independently, so embedded experiences can expose only the actions that fit the host workflow without changing permissions.
Dashboard version control in the Management API. Dashboard create, update, duplicate, and migrate operations can now commit saved dashboard templates to a connected GitHub repository, and a new commit endpoint lets API clients retry or explicitly commit the current saved dashboard.

Improvements

Safer commit-on-save workflow. Dashboard saves now persist before GitHub commit attempts; if GitHub fails, the saved dashboard is preserved, marked uncommitted, and can be retried instead of losing the change.
Date comparison reliability. KPI comparisons, dashboard summaries, and query execution now resolve inherited comparison settings consistently from the active dashboard date filter.

Bug Fixes

Dashboard access errors. Embedded dashboards now show clearer loading and access-error states with retry support when dashboard or token fetching fails.
GitHub disconnect cleanup. Disconnecting GitHub now also disables commit-on-save for affected projects, preventing future dashboard saves from being blocked by a missing repository connection.

Upgrade Notes

Schema changes: None.
New env vars: None.
Breaking changes: Management API clients that save, duplicate, or migrate dashboards in projects with commit-on-save enabled must send a non-empty commitMessage and handle versionControl results, including 502 partial-failure responses where the dashboard was saved but the Git commit failed.

v0.1.59

July 13, 2026

What's New

Briefings and scheduled reports. Create narrative business updates, attach dashboard PDFs or CSVs, preview and run them on demand, and deliver them on a schedule by email or Slack.
AI dashboard authoring. Build dashboards from a dataset or semantic domain using a natural-language prompt, review the proposed plan, and save the result from the product or an MCP client.
Hosted Data Apps. Create, version, publish, and run governed React data applications with reusable metrics, records, matrices, inputs, totals, and runtime validation.
Period comparisons. Compare metrics with previous or target periods using Global Date inheritance, fiscal and month-aligned calendars, comparison badges, tooltips, exports, and PDFs.
OAuth-backed MCP access. MCP clients can register through OAuth and use expanded tools for governed analysis, dashboard authoring, Data Apps, and semantic-model repair.

Improvements

Safer AI-generated analytics. Briefings, dashboards, and Data Apps now perform stronger grounding, source, relationship, field, filter, and query validation before saving or presenting results.
Date and time filtering. Date ranges support minute-level time selection and timezone-aware exports, while Global Date comparison activates only for valid finite ranges.
Project feature controls. Project admins can independently control access to the dashboard assistant, Data App Builder, analytical Briefings, and AI writing helpers.

Bug Fixes

Comparison accuracy. Missing history remains empty instead of becoming zero, mixed KPI cards retain their current values, date predicates stay correctly bounded, and comparison bookkeeping fields no longer leak into tables or exports.
Runtime reliability. Data App metric execution, dashboard error states, legacy SQL templates, and connection-test error reporting are more reliable.

Upgrade Notes

Schema changes: Adds project feature policy storage, hosted Data App versioning, dashboard kind/current Data App links, and MCP OAuth client/refresh-token tables. Run prisma migrate deploy before starting the new app image.
New env vars: BRIEFINGS_RUNNER_URL for generated-analysis Briefing dispatch, BRIEFINGS_EMAIL_SENDER_URL for Briefing email delivery through the scheduler, and LAMBDA_API_KEY for Briefing callbacks and internal Lambda authentication. Scheduler deployments also add Insight runner model configuration and automation-dispatch parameters in the SAM template.
Breaking changes: The legacy /api/v1/schedules/* and /api/v1/alerts/* routes are retired. Move scheduled-report and alert-style integrations to the Briefings and Automations APIs before upgrading custom clients. Custom scheduler deployments should also review the Node.js 22 runtime change and the Automation V2 dispatcher defaulting to enabled.

v0.1.56

May 6, 2026

What's New

Document sheets — pixel-perfect reports. A new sheet type for authoring multi-page report-style content alongside dashboards. Supports rich text sections, structured input variables, paginated flat tables with grand totals, headers/footers, and on-demand PDF export with stricter page-fit and readiness checks for reliable rendering. Scheduled and automation-triggered PDF exports now use this document mode for document sheets.
Conditional formatting for tables and document sections. Authoring controls for color scales, data bars, comparison rules, and top/bottom highlighting on flat-table visuals and document tables. A unified formatting model replaces the legacy per-card behavior.
Dashboard summary narratives with KPI contributors. Dashboards can render a narrative summary that highlights movement, drivers, and contributors for KPI cards. New per-request override controls let callers configure summary display, filter to supported cards, and skip cards that don't qualify.
Brand Studio at the organization level. Organization admins can now open Brand Studio directly from /project/brand-studio without picking a dashboard first, and configure the org-wide appearance (colors, fonts) once for every project. Org appearance is persisted, validated, and propagated through dashboards, custom visuals, and filter surfaces.
View-as-tenant for organization admins. Org admins can preview any dashboard exactly as a specific tenant user sees it, with tenant-scoped tokens and security context applied end-to-end. New tenant-preview routes and a tenant-only project-token mode back this flow.
Multi-column table sorting and frozen first column. Shift+click a column header to add up to two secondary sorts. A new card-menu toggle keeps the first visible column sticky during horizontal scroll.
Calculated fields authoring rework (Phase 1). A new formula-first authoring dialog with a templates menu replaces the legacy calculated-field editor, with stronger validation and clearer execution semantics for where each field is allowed to run.
like / not like operators in the explore API. String pattern matching is now available alongside the existing comparison and IN-style operators when building queries through the exploration endpoint.
Expanded MCP analytics surface. The Semaphor MCP read-only contract now covers semaphor_get_analysis_context, semaphor_query_spec (with previous-period and driver-mode variants), and a documented set of discovery tools (semaphor_list_*, semaphor_get_dataset_schema) for project-token sessions. See the MCP README for the full tool list and parameter reference.

Improvements

Project update error handling. Failed project updates now surface a specific error instead of a generic failure, making misconfigured permissions easier to diagnose.
Tenant project-token validation. Project tokens issued for tenant users carry richer context and are validated against organization-level access rules before resolving a dashboard.
Document filter handling. Dashboard filter and control behavior is consistent between document sheets and standard dashboards, including the dashboard filter picker.
PDF export reliability. The PDF generator runs stricter readiness and layout-fit checks for document sheets, with improved logging for export performance diagnostics.
RelativeDate stability. Relative date displays now use a fixed reference epoch, eliminating drift between server-rendered and client-rendered values on long-lived sessions.

Upgrade Notes

Schema changes: New Organization.appearance JSON column for the org-level Brand Studio. Run prisma migrate deploy (or your usual migration step) before starting the new images.
New env vars: None.
Breaking changes: None. Existing per-card formatting and calculated-field configurations continue to load; new authoring uses the unified models.

v0.1.50

April 23, 2026

What's New

Global date filter for semantic dashboards. You can now add a single date range filter at the dashboard level that applies to every eligible semantic card simultaneously. Each card uses the primary date field defined on its underlying dataset, so one control updates all charts at once. SQL cards and cards without a configured primary date field are not affected.
Primary date field on semantic datasets. The dataset editor now lets you designate one date dimension as the dataset's primary date field — the anchor the global date filter binds to. Once configured, any dashboard card using that dataset automatically participates in global date filtering.
Global date filter carried through scheduled reports and exports. Scheduled PDF and CSV reports and automation-triggered export jobs now capture and apply the dashboard's global date filter value, so delivered reports reflect the same date range shown on the live dashboard at the time of execution.

Improvements

Dataset API returns primary date field metadata. Each dataset in the /v1/datasets response now includes a primaryDateField object when one is configured, exposing the qualified field name, data type, entity source, and supported granularities. If the field reference is stale or unresolvable, a primaryDateFieldError is returned instead.

Upgrade Notes

Schema changes: None.
New env vars: None.
Breaking changes: None.

v0.1.45

April 21, 2026

What's New

Case-insensitive filter search with numeric support. Text filters now match regardless of case across all supported databases, and searching against numeric columns works without manual casting. Applies to semantic inline filters and calculated-field filters as well.
Direct Source toggle for embedded data-source selector. Hide or show the "Direct Source" option in the data-source selector via a new showDirectSource flag on the token ui_config. Defaults to shown.

Improvements

No duplicate PDF downloads. Triggering an export while one is already in flight now shows a "download in progress" state instead of starting a second job.

Upgrade Notes

Schema changes: None.
New env vars: None.
Breaking changes: None.

v0.1.43

April 20, 2026

What's New

SQL-backed control options. Populate dashboard control dropdowns from a live SQL query instead of a hardcoded list. The control's available values stay in sync with your data, with support for default values, runtime refresh, and graceful fallback when the query fails.
Password-protected scheduled PDFs. PDF exports can now be delivered as AES-encrypted files that require a password to open, print, or copy — available for both scheduled reports and on-demand exports.

Improvements

ClickHouse dialect detection. More accurate SQL dialect inference for ClickHouse connections, reducing query generation errors on ClickHouse-backed cards.

Upgrade Notes

Schema changes: None.
New env vars: None for standard deployments. Self-hosters running the PDF generation Lambda outside AWS may optionally set PDF_ENCRYPTION_BACKEND=pdf-lib to force the legacy encryption backend; the default uses bundled qpdf.
Breaking changes: None.

v0.1.42

April 19, 2026

What's New

Manual GitHub App installation ID entry. The GitHub admin page now accepts a manually entered installation ID for teams whose OAuth flow doesn't complete automatically, with clearer error messaging when a connection can't be resolved.

Improvements

Accurate dashboard tab counts. Organization and tenant dashboard counts are fetched in parallel, so tab badges reflect the real totals regardless of which tab is active.
Clearer onboarding flow. The first-run onboarding dialog is restructured around a quickstart mode selection, with updated step progression and messaging.

Upgrade Notes

Schema changes: None.
New env vars: None.
Breaking changes: None.

v0.1.41

April 17, 2026

What's New

Virtual datasets. Author SQL-backed datasets directly in your semantic domain. The new SQL Dataset mode in the Add Dataset dialog lets you write a query against any database connection, preview columns inline, and reconcile fields when the underlying SQL changes. Virtual datasets behave like physical tables in the field list, participate in auto-joins, and flow through filters and aggregations the same way. See Virtual Datasets.
Template expressions for dynamic SQL. Write dynamic SQL with {{ param('id') }} and {{ filter('name') }} expressions, {% if %} conditional blocks, and multi-value IN list expansion via .list. New accessors — .sql, .list, .list_sql, .value, .values, .present — let you branch on control values, gate optional predicates on filter presence, and supply explicit defaults. See Template Expressions for the full reference.
Inline calculated filters in SQL cards. SQL cards now evaluate inline calculated-field filters as part of query execution, so filters defined on derived fields apply correctly to raw SQL.

Improvements

Dashboard controls preserved in exports. Scheduled PDFs and on-demand exports now capture the full control context of the viewing card, so exported reports reflect exactly what the viewer has selected — across both dashboard-level and card-level controls.
Toolbar and filter UI consistency. Dashboard tabs, toolbar items, runtime control inputs, date range pickers, month pickers, multi-select filters, numeric inputs, and tab filters now share a unified height and spacing for cleaner alignment.

Upgrade Notes

Schema changes: None.
New env vars: None.
Breaking changes: None. The [[param.x]] placeholder and {{ filters | where }} helper continue to work unchanged — template expressions are an additive layer on top of them.

v0.1.38

April 12, 2026

Improvements

Calculated field management. Card-scoped and sheet-shared calculated field workflows are clearer, and Semaphor now detects naming conflicts with domain-defined fields automatically.
Data table pagination. Tables now remember your preferred page size across sessions. Dynamic page size options adapt to your dataset, making it easier to navigate large result sets.
Data table sorting and rendering. Column types are now auto-detected for smarter sorting (numeric vs. text), and overall table rendering is faster and more consistent.
Dashboard access control. Permission checks for dashboard editing are consolidated and more efficient, reducing overhead when loading dashboards.

Upgrade Notes

Schema changes: None.
New env vars: None.
Breaking changes: None.

v0.1.36

April 10, 2026

Improvements

Faster dashboard loading for embedded users. Optimized how dashboards resolve project context and retrieve data for embedded (OAuth) organization users, reducing load times.
Calculated field editor polish. Improved error messaging, layout consistency, and spacing across the calculated field editor and toolbar controls.

Upgrade Notes

Schema changes: None.
New env vars: None.
Breaking changes: None.

v0.1.34

April 8, 2026

What's New

Structured error logging. All errors and failures — query failures, dashboard load errors, token generation issues, assistant errors, and more — are now emitted as structured JSON to the container's standard output. Use docker logs to inspect them directly, or pipe them into your existing log aggregation tool (Datadog, Loki, CloudWatch, etc.) with no extra configuration.
Telemetry webhooks. Optionally forward those same error events to an external webhook endpoint in real time. Configure the webhook URL, choose which event types to subscribe to, and set a signing secret for request verification. Manage everything from Organization Settings.

Improvements

Version display on self-hosted home page. The self-hosted landing page now shows your current Semaphor version with a direct link to release notes, so you can quickly see what you're running and what's changed.
AI assistant conversation tracking. The AI assistant now maintains conversation context more reliably, improving follow-up responses within the same session.

Upgrade Notes

Schema changes: New telemetry_destinations table. Run prisma migrate deploy after upgrading.
New env var: ENTERPRISE_TELEMETRY_ENABLED — set to true to enable webhook delivery (defaults to disabled).

v0.1.33

April 7, 2026

What's New

Interactive API documentation. Full OpenAPI specifications are now published for all public endpoints — tokens, dashboards, visuals, domains, discovery, SQL execution, and unified security. Browse them from the new API Reference section.
Dynamic visuals in the AI assistant. The AI assistant can now generate custom data-driven visualizations on the fly, in addition to standard chart types.
Project and connection access controls. Only users with the appropriate role can create new projects or manage connections, preventing unauthorized changes.

Improvements

Navigation clarity. The "Multi-tenancy" sidebar item has been renamed to "Security" for clearer navigation.
MCP tool responses. MCP tool outputs now return structured content alongside text, making integration with MCP clients more reliable.
Plugin asset loading. Plugin URLs now use the configured application base URL, ensuring consistent behavior across cloud and self-hosted deployments.

Upgrade Notes

Schema changes: None.
Encryption key validation. The Docker entrypoint now validates that SYMMETRIC_ENCRYPTION_KEY is exactly 32 characters. If your existing key is a different length, startup will fail with a clear error message and instructions. Generate a valid key with openssl rand -hex 16.

v0.1.31

April 2, 2026

What's New

Custom visuals for self-hosted deployments. You can now publish and serve custom visualization plugins from your own S3-compatible storage. Set APPS_BUCKET_NAME and APPS_BUCKET_REGION in your Docker environment to enable plugin publishing.
Plugin management UI. Redesigned plugin page with improved navigation, upload dialogs, and permission controls.

Improvements

Plugin asset paths now use canonical ID-based URLs for consistency between cloud and self-hosted environments.

Upgrade Notes

Schema changes: None.
New env vars: APPS_BUCKET_NAME, APPS_BUCKET_REGION (required only if you want to publish custom visuals).

v0.1.25

March 24, 2026

What's New

Unified Security. New security model that combines column-level, row-level, and table-level policies into a single workflow. Create policies, assign them to users or groups, and preview the effective result — all from one place. See Security Definitions and Security Assignments.
Security assignment preview. Preview how security policies resolve for a specific user before saving, so you can verify access before it goes live.
Dashboard controls. Interactive parameter controls that let dashboard viewers filter and adjust data without editing the dashboard.

Improvements

Optimized security policy evaluation, reducing internal lookups during query execution.

Upgrade Notes

Schema changes: New database tables for Unified Security. Run prisma migrate deploy before starting the new version.
Breaking changes: None. Existing CLS, RCLS, and TLS policies continue to work. Unified Security is opt-in per connection.

v0.1.195 and earlier

Upgrade Notes

Minor internal schema cleanup. No impact for most deployments.
Versions before v0.1.195 are not tracked here. If upgrading from a significantly older version, back up your database and contact support@semaphor.cloud for guidance.

On this page