Semantic layer issues

Astrato reports semantic-layer validation problems and upstream schema changes in both the Semantic Layer Editor and MCP. The editor collects them in the Issues panel. Over MCP, use the validation and upstream-schema tools described in Semantic layer workflows.

Find issues in the editor

Open Issues from the editor toolbar. Its first line says how many issues Publish is waiting on, and each of those rows is marked Blocks publishing; other rows say where the finding comes from. You can search issue text, including where it comes from, or narrow the list by:

• severity: errors or warnings;
• area: Tables & Fields, Joins, Measures, Dimensions and the other parts of the layer, with Layer & sources for layer settings and source checks.

Expand an issue and select Open to open the affected item in the editor. A list of three issues or fewer opens expanded. When an upstream datatype issue offers Apply suggested fix, review the reported old and new types before applying it.

A semantic layer imported from a Snowflake semantic view also lists changes made to that view since the import, each with an action to take the change. See When an imported Snowflake semantic view changes.

Repair a legacy measure calculation

A layer imported from an existing semantic layer can contain a row calculation that the editor cannot parse, such as DATEDIFF(day, {f1}, CURRENT_DATE()). The layer still opens. Astrato preserves the original formula and its field bindings, shows the formula in the measure preview, and reports an error against that measure in Issues. Publishing remains blocked while the error exists.

Select the measure from Issues to inspect the error. Its normal Edit button is disabled because the visual editor cannot represent the preserved formula; its tooltip explains why. Click the Developer View chip in the error to open the JSON source with the affected options.calculation property selected. Repair its definition using the supported measure expressions. If you replace the operand with a supported expression, remove the old options.calculation too: it remains the effective row formula while present. Apply the repaired draft and confirm that the issue clears before publishing. Other measures and tables remain available while you repair the affected measure.

This recovery preserves malformed row-formula text; it does not make unsupported formulas valid or recover files whose document structure cannot be recognized.

Repair through Nash or external MCP

astrato_semantic_layer_validate returns the affected measure, operand path, and validation error. Prepare a change with astrato_semantic_layer_prepare_measure_change, naming the affected measure. Its target includes the original definition, ordered field bindings, and repair guidance, including in compact responses. Use astrato_semantic_layer_apply_measure_change with operation: "patch" and a complete supported calculation in patch.calculation, using the prepared target and revision. This replaces the broken calculation and preserves the measure’s presentation metadata. You do not need Developer View. Validate again after repair; an unsupported formula must not be copied into a new definition or silently replaced with a guessed calculation.

Understand the origin

Semantic layer issues come from validating the current document. They include invalid settings, references, expressions, joins, dimensions, measures, and functions. When live capability discovery succeeds, measure validation also reports an unavailable aggregation, a field or expression datatype that the aggregation cannot accept, and unsupported distinct usage. The editor, MCP validation, and publish use this same datasource-specific contract. If live capabilities cannot be loaded, Astrato skips these datasource-specific checks rather than inventing a support matrix.

Filter values are checked against the datatype of their referenced field or dimension. For example, a text value in an integer filter is reported on the affected table or measure, appears in Issues, and prevents publishing. A publish rejection names the affected semantic entity.

Upstream source issues mean the database confirmed that a referenced object is missing, a physical datatype changed, or Astrato found one likely replacement column whose name differs only in casing or separators. Missing objects remain in the semantic layer so you can repair them without losing downstream definitions. Astrato does not apply detected datatype or rename changes until you accept the suggested fix.

A finding that offers a suggested fix is reported against the field, with a severity that reflects what accepting that fix would cost. When applying it introduces no new validation errors, it is a warning: the document and the database disagree, but every consumer still validates. When accepting it would leave a measure, dimension, table filter, or other consumer unable to run — summing a column the database now reports as text, for example — the field is an error instead, its message names how many consumers are affected, and each affected consumer also gets its own entry naming the rule it would break. The suggested fix is still offered in both cases: accepting the database’s word remains your decision.

This covers renames as well as datatype changes, because accepting a rename writes the replacement column’s datatype along with its name. A rename onto a column of a different type can therefore be reported as an error, even though the finding itself describes only the change of name.

Astrato determines this by validating the document that applying the fix would produce, so the verdict follows the same datasource-specific contract as ordinary validation. Breakage that only the live contract can establish — an aggregation the new type cannot accept — therefore goes unreported when capabilities cannot be loaded, and such a change stays a warning. Breakage the document alone proves, such as a filter parameter whose type would no longer match its field, is reported either way.

For a field with a datasource-native datatype override, the check compares that override with the raw datatype reported by the database. It suppresses only the expected semantic/native difference; if the database column changes to another native datatype, Astrato reports ordinary datatype drift.

Source check issues mean the metadata check failed, could not verify an object, or did not receive the required metadata. They do not mean that the object was deleted. Check source access and availability before changing the semantic layer.

Applying a datatype or rename fix updates the physical field as an ordinary semantic-layer edit. Astrato recalculates the result types of dependent dimensions and measures automatically, so they do not require separate confirmation.

The global source status opens a compact summary with its status, last checked time, and a Check now action. It does not repeat individual findings: all findings appear in Issues, so document and source problems can be reviewed together.

Review issues over MCP

• Use astrato_semantic_layer_validate for semantic-document errors and warnings, including aggregation support when live capability discovery succeeds for the layer’s active data connection.
• Use astrato_semantic_layer_check_source_schema for database drift and source-check failures. A fresh check requires write access and can record confirmed missing or restored objects in a new draft revision.
• Treat datatype and conservative rename findings as suggestions. Review the old and new values, then call astrato_semantic_layer_apply_source_schema_fix only after confirmation. A finding reported as an error is one that would break a consumer if applied as-is — a rename included, since applying one also writes the replacement column’s datatype; read the accompanying consumer entries before deciding whether to apply the fix or repair the consumer first.
• Identify the field a source-check finding or issue is about by its viewName and fieldName. Do not split entityKey: it joins the two names with a dot, and either name can contain a dot itself. A field issue without viewName and fieldName comes from a report that did not record them, where more than one view name followed by a dot begins entityKey. It stays unattached even when only one of those fields still exists, so do not treat that field as its target.

After applying a fix, validate the layer again and confirm that the issue is resolved.