Release Notes

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

For upgrade procedures, see the Upgrade Guide.

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.

Release Notes

On this page