Skip to main content
Version: 0.0.42

Operations

The Operations tab manages the semantic layer of a Custom Model. The semantic layer is a structured representation built from the connected data sources that enables the AI to understand and query your data intelligently.

Operations require Admin or Builder role.

Semantic Layer Operations​

Create Semantic Model​

Builds the semantic layer for the first time based on the connected data sources and their configured filters. Run this operation after:

  • All data sources are connected in the Data Sources tab
  • Custom Model filters are configured in the Filters tab

The operation analyzes all connected data sources, generates cross-source semantic metadata (tables, columns, hierarchies, descriptions), and makes the model ready for querying.

Update Semantic Model​

Refreshes the semantic layer to reflect changes. Run this operation when:

  • Data source schemas have changed (new columns, renamed tables, added tables)
  • Custom Model filters were modified in the Filters tab
  • A new data source was connected or disconnected

Scheduling updates: If your underlying data sources change frequently, create a Job Definition in the Operations area to schedule regular updates. Navigate to the link shown after enabling the update operation to configure the schedule and cron interval. The right frequency depends on your data sources — some schemas change daily, others remain stable for months.

For static models where the semantic layer is expected to remain unchanged, schedule updates only when schema changes occur. Locking the model after validation helps protect against accidental modifications and signals to users that the model is stable and production-ready.

Delete Semantic Model​

Removes the semantic layer entirely. After deletion, the model cannot answer data queries until the semantic layer is rebuilt with Create Semantic Model.

Deleting the semantic model affects all dependent content

Deleting the semantic model removes the foundation that all charts and dashboards built on this model rely on. Charts and dashboards will lose their data connection and become non-functional.

Only delete the semantic model if you intend to fully reset and rebuild the model's configuration. In production environments, avoid deletion unless there is no alternative.

If you need to update the semantic layer, use Update Semantic Model instead.

Materialization (Performance)​

Enabling Materialization for a model converts its Star-Views into ClickHouse refreshable Materialized Views, trading extra storage for faster chart and dashboard queries. It is Builder/Admin-controlled and opt-in per model.

  • Materialized Star-Views refresh automatically after each data source load — they are never dropped during normal operation, so dependent charts keep working.
  • Toggling materialization off restores plain views in place, preserving the view name. Charts continue to work across both transitions.
  • Materialization does not protect against Delete Semantic Model: deleting the semantic layer removes the views and their stored definitions regardless of materialization.

Data Loads and the Semantic Layer​

Running a data load (full or incremental) on a connected data source is designed to preserve the semantic layer and keep all dependent charts and dashboards functional.

  • Incremental load — appends new rows to existing data, causing no structural changes. The semantic layer is unaffected.
  • Full reload — replaces the dataset by truncating and rewriting the underlying data. The table structure and all dependent semantic views remain in place. Charts and dashboards continue to work throughout the reload.

After a data load completes, any Materialized Star-Views automatically refresh to reflect the new data (if Materialization is enabled on the model).

Schema changes require a semantic update

A data load does not automatically detect schema changes (new columns, renamed or removed tables). If the schema of a connected data source has changed, run Update Semantic Model after the load to incorporate the new schema into the semantic layer.

For a new Custom Model:

  1. Connect data sources (Data Sources tab)
  2. Configure Custom Model filters (Filters tab)
  3. Run Create Semantic Model — builds the initial semantic layer
  4. Review the generated metadata (Descriptions, Hierarchies tabs)
  5. Test the model with representative queries before sharing
  6. Lock the model to protect the configuration

For an existing model after schema changes:

  1. Update data source filters if needed (Filters tab on the data source)
  2. Update Custom Model filters if needed (Filters tab on the model)
  3. Run Update Semantic Model
  4. Re-validate representative queries

Deciding on Update Frequency​

There is no universal update interval. Consider your situation:

ScenarioRecommendation
Schema changes rarely (stable production DB)Manual update only, triggered when changes occur
Schema changes regularly (active development)Schedule weekly or after each deployment
Schema changes never (static CSV/file source)No updates needed; lock the model
Multiple data sources with different change ratesSchedule by the most frequently changing source

Best Practices​

  • Always run Create Semantic Model after the initial data source and filter setup — do not share the model before the semantic layer exists.
  • Use Update Semantic Model instead of Delete + Create whenever possible to preserve any manually enriched descriptions and hierarchies.
  • Lock the model after validating a stable production configuration to prevent accidental changes.
  • If update jobs are scheduled via Job Definitions, monitor the Job Runs area regularly to detect failures early.