Data quality and the semantic layer

Wrong answers are often data problems rather than reasoning problems: a date stored as text, duplicate order rows or several spellings for one category. The quality report identifies those risks; the semantic layer and controlled transforms make the resulting definitions reusable.

Inspect quality

Open a dataset under Data → Files to run the read-only quality check. It reports a quality score and grade, including:

• the share of nulls and empty strings, plus blank or constant columns;
• mixed types and values that cannot be parsed;
• exact duplicate rows and repeated values in suspected unique-key columns; and
• columns that look like dates, numbers or booleans.

Recommendations are not automatic decisions. A duplicated order row usually does not raise an execution error; it quietly inflates totals. Confirm that duplicates are truly invalid before applying a deduplication rule.

Quality snapshots are refreshed after imports, source refreshes and re-profiling. The Data page shows both time coverage and the current health grade.

The semantic layer

Automatic profiling gives each column a machine-readable profile. In Data Mart, you can correct the business meaning:

• Display name — the name business users should see, rather than the export's original column name.
• Semantic type / role — date, category, measure or identifier. This guides the metric editor and query engine toward valid filters, groups and time logic.
• Description — the definition, unit and boundaries, such as “net of refunds” or “tax included.”

A semantic role does not repair the underlying value. Convert text dates or numbers to the appropriate storage type first, then assign the semantic role. Gen by AI can draft names and descriptions from column names and samples; review every draft. Workspace time settings — week start, fiscal calendar and time zone — determine what phrases such as “this week” and “last quarter” mean.

Safe cleaning and reversible transforms

The quality panel can clean datasets whose rows are owned locally. Common operations include:

• deduplicate whole rows or a confirmed key, keeping the first, latest or an arbitrary row;
• convert text or numeric dates to dates or timestamps, and convert columns to numeric, boolean or text types;
• drop blank or constant columns;
• standardize category aliases, trim whitespace and normalize text;
• fill nulls with a value or add a null-indicator column; and
• add an IQR or z-score outlier flag without automatically deleting outlier rows.

Each transform creates a new version, preserves the pre-transform snapshot, updates the semantic profile and invalidates cached metric runs that depend on the dataset. A write failure leaves the old version intact. The history records the operator, and the interface allows undo only for the most recent transform that is still applied; undo restores the earlier version and recalculates its dependencies.

Connector snapshot rows belong to the upstream source, so a local cleaning operation would be overwritten by the next refresh. Fix Google Sheets, Feishu, S3 or Snowflake upstream, then refresh. External (zero-copy) S3 datasets have no local rows and reject cleaning, column deletion, append and re-upload rather than pretending those changes are permanent.

Re-imports, refreshes and metric safety

Local file re-imports support Replace and Append, require matching columns and use versioned writes with rollback protection. Normal connector and URL refreshes also require an exact column match. If an upstream source adds, removes or renames columns, the refresh reports a schema mismatch; only an explicitly confirmed forced re-import rebuilds the structure, and metrics that use old columns may become invalid.

A metric's formula.datasetId is its explicit dataset link. Cleaning or undoing a transform invalidates dependent metric caches so they are recalculated. When you delete a dataset, you can keep dependent metric definitions and mark them needsData, or delete those metrics as well. A definition with no data source is not treated as runnable.

Governance boundaries

• Any authorized workspace member can view a quality report. Applying transforms, re-importing and refreshing data requires a workspace owner or admin.
• Cleaning from chat is off by default. A workspace owner or admin can enable it in governance settings; even then, only the agent's owner can run a data-changing clean-up. Members and clients cannot.
• A workspace can use Explore, Governed or Hybrid data mode. Explore permits raw-data tools; Governed answers from approved (certified) catalog metrics and hides raw SQL/file tools; Hybrid prefers governed metrics but may fall back to raw data with an ungoverned label. Governance settings can separately disable raw SQL and record exports while retaining governed detail reads.
• The catalog distinguishes proposed, draft, certified and deprecated metrics. Agent metric selection defaults to certified metrics and hides deprecated ones. Owners or admins can assign metric owners and reviewers, aliases and deprecation notes, and place metrics in one or more catalogs.
• Selecting a catalog or explicit data scope in the agent builder limits the datasets it can read. Approve and catalog the right metrics before assigning them; an upload does not open data to every agent.

A short checklist before you build

• Date columns are parseable date/time values, with time zone and fiscal settings matching your team's conventions.
• Unique keys are actually unique, and duplicate rows have been confirmed as errors rather than valid detail.
• Every column the agent will use has a clear display name, semantic role, unit and description.
• Metric formulas still reference existing columns and the correct dataset; names, filters and catalogs are unambiguous.
• Connector problems are fixed upstream; after refreshing, review the health score and schema status again.

Next

• Create an agent
• Verify and evaluate