Skip to main content
Version: Next

Semantic metadata operations

Authority and scope​

Metadata maintenance resolves a stored semantic-view UUID and its owning connection. It requires the existing SemanticView read permission, SemanticLayer read/write permissions, view/layer data access, and permission to modify the connection. Per FR-015, all three maintenance routes deliberately use a SemanticView read gate, while their commands require write on the owning SemanticLayer and connection-modify authority; mapping the routes to write would add a SemanticView-write requirement outside that contract. View editorship alone does not grant connection maintenance. Anonymous and embedded guest principals cannot perform maintenance. Ordinary chart access retains its canonical guest/dashboard/viewer/editor policy.

All controls require SEMANTIC_LAYERS, the default-off SEMANTIC_LAYER_METADATA_REFRESH_ENABLED, trusted tenant namespace, and provider support. Provider construction happens after authorization. Fresh metadata DB sessions recheck the persisted principal, view binding and connection configuration before publication; request transactions are neither committed nor discarded. Metadata DB connection/statement timeouts remain operator requirements.

Separate operations​

Use POST with {} and the stored view UUID for:

  • /api/v1/semantic_view/<uuid>/refresh_metadata/: acquire and publish the connection catalog. Response contains status (changed or unchanged) and observed_at. Even unchanged discovery gets a fresh cache token internally.
  • /api/v1/semantic_view/<uuid>/invalidate_catalog/: retire the catalog and older writer authority without fetching. Later authorized reads refill it.
  • /api/v1/semantic_view/<uuid>/invalidate_compatibility/: retire compatibility entries only. Catalog and query-result identities stay unchanged.

No endpoint accepts raw keys, tenant/configuration overrides or unsaved edits. No operation runs a chart or saves its settings. These commands are independent of any particular UI. Existing query force-refresh remains separately authorized.

POST /api/v1/semantic_view/<uuid>/cache_metadata/ with {"kind":"catalog"} or {"kind":"compatibility","selected_metrics":[],"selected_dimensions":[]} returns the scoped CacheEntryInfo. Inspection never fills the catalog, creates a generation or renews expiry. Backend limitations are reported explicitly. Redis inspection requires the configured bounded reader for the same data cache; unsupported custom URL/options configurations report unsupported expiry inspection.

Result diagnostics: captured identities only​

InspectQueryResultCommand accepts a host-prepared query context and query index. The normal result-key path records the private identity in the HTTP request. Inspection rechecks canonical context access and the subject/query/RLS fingerprint. It never recomputes a provider UID or fetches metadata. A fresh request, changed scope, annotation query or worker-only context returns unsupported. This is an intentional limit; there is no standalone raw-key or reconstruction endpoint. Internal callers can inspect during the same request after normal key construction. Captured identities disappear with that request and are never returned to clients.

Failures and rollout​

Discovery and maintenance map typed service failures consistently: 409 for active refresh/configuration changes, 502 for upstream/invalid catalogs, 503 for unavailable storage/database or unconfirmed outcomes, 504 for deadline expiry, and 422 for unsupported/incomplete configuration. Existing access/missing-resource errors stay 403/404. Errors never include provider payloads, credentials or database statements.

The same typed error mapping applies to datasource metadata, query and column-value requests, Explore context loading, and chart-data requests (including result cache-key construction). Access checks still precede discovery. Unrelated database and validation errors retain each endpoint's existing handling.

Dashboard dataset loading retains its per-datasource failure isolation: if a semantic provider fails during discovery, the response still contains the healthy datasets with HTTP 200. It omits the failed semantic view and logs a safe warning instead of failing metadata loading for every chart on the dashboard.

The chart-context factory authorizes the full semantic context before column discovery. Later query validation/access checks remain in place. The default-off store alone did not provide this earlier boundary; enablement requires this command slice plus compatible provider/fleet configuration. MCP/async/CLI adaptation, operator timeouts, topology/load checks and UI/live-provider acceptance remain separate rollout gates. No database migration or role grant is added.

Provisional editor interaction​

The semantic-view editor exposes Sync metadata next to its tabs when the server reports maintenance capability and a stored UUID. This action refreshes metadata without saving the description or cache-timeout draft. It preserves the active tab. If publication succeeds but local reload fails, Reload fields retries the read only. An unconfirmed sync also offers Reload fields and disables another sync until the reload succeeds. This refreshes both the editor and Explore without publishing again or claiming that sync succeeded; the draft stays intact. The frontend store remembers an unconfirmed sync by semantic-view UUID. Closing and reopening that view keeps the warning and Sync lock until an explicit reload confirms the fields, or a full page reload resets frontend state. Other views remain independent. Closing or switching editors discards stale completions. Explore reloads datasource fields and compatibility for the current selection; it does not save chart settings or automatically run a chart query. Controls use their normal validation against the refreshed choices. If that removes or changes a selected value, version history records the actual control change; an unchanged selection creates no unsaved-change entry.

The Cache metadata tab provides explicit, read-only inspection of catalog and compatibility timing, including creation, source observation, inspection time, and estimated expiry. Compatibility inspection uses an empty selection; it does not describe a particular chart's selected metrics. Missing or unavailable entries and unknown or unlimited expiry remain distinct. Displayed TTL is the observation at inspection time, not a live countdown. Inspection does not fill or refresh caches. Sync/save resets displayed observations so users can inspect again. Independent invalidation remains available through the operations above. Result-cache inspection is not exposed in this editor because a fresh request has no captured query identity. Other interfaces can use the same operations.

Local component tests use mocked HTTP. Live-provider, multi-worker, browser and Big Number acceptance remain separate enablement gates; this UI does not by itself establish fleet-wide or production acceptance.