Skip to content

Written for: For developersUsing Astrato instead? Read the product guide

Semantic layer authoring reference

7 min read · Updated 17 Nov 2026

The forms below are what the MCP authoring tools accept and what the Semantic Layer Editor stores. The steps an agent follows to use them are in Author a semantic layer over MCP.

Deterministic integrations that need the whole model use the snapshot returned by astrato_semantic_layer_get_summary instead of paginating every detail collection. The snapshot is the complete current draft as Semantic Layer Document V3 JSON, including measure definitions that compact detail pages intentionally omit.

After initializing the MCP connection, send this JSON-RPC request:

{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "astrato_semantic_layer_get_summary",
"arguments": {
"semanticLayerId": "11111111-1111-4111-8111-111111111111",
"includeSnapshot": true
}
}
}

Find the item in result.content whose type is resource_link and whose uri equals the text result’s data.snapshotResourceUri, then pass that uri to resources/read. Match the URI rather than the type alone, because a result can carry more than one resource link:

{
"jsonrpc": "2.0",
"id": 2,
"method": "resources/read",
"params": {
"uri": "nash-mcp://resources/<resource-id>"
}
}

Read the resource in the same MCP session that created the link. Parse result.contents[0].text as JSON; it is the complete fileVersion: 3 document. The text result also contains these artifact fields:

  • filename, mimeType and UTF-8 size;
  • snapshotRevision, the exact draft revision in the resource;
  • publishedRevision, or null when the layer has never been published;
  • publicationState: published, unpublished_changes, never_published, superseded, or unknown when the published model could not be read from the engine; unknown does not mean the layer was never published.

The text result’s data.resourceUri and data.snapshotResourceUri contain the same URI when the attachment is requested. Without includeSnapshot: true, the server does not serialize or store a snapshot and neither URI is present. Omit the flag for ordinary summaries and bounded detail reads.

superseded means a newer revision was published while this point-in-time snapshot was being prepared. Read the summary again before claiming that snapshot is current. The resource is JSON; serialize it to YAML locally when a YAML artifact is required.

Use the same expression forms as the visual measure editor:

  • Arithmetic supports +, -, *, / and parentheses, with numeric values, numeric parameters, and compatible aggregates or stored measures. Negative numbers such as -0.1 are supported; negating a reference or group, such as -(Revenue + Cost), is not.
  • One row aggregation can wrap arithmetic over fields, for example SUM(Price * Quantity). Values, parameters and nested aggregations are not supported inside that row expression. Choose an aggregation from the datasource capabilities; use the aggregation’s distinct setting rather than inventing a function name such as COUNT_DISTINCT. When the connection’s COUNT supports distinct values, a request for COUNT_DISTINCT, countDistinct, COUNTD or DISTINCT_COUNT is refused with a message that names COUNT with distinct: true.
  • The fields of one row expression must sit on one row: one of their views reaches every other through many-to-one or one-to-one joins, followed in their declared direction. Quantity × a part’s retail price, over an order line joined many-to-one to its part, passes. Supply cost × quantity, across a part-supplier view and order lines with no join from one to the other, is refused as cross-grain-row-expression, because the engine would read one side as empty and return a wrong total. Add a many-to-one join on every field that identifies the other view’s row (a composite join), or a custom SQL view that computes the value; for separate totals, aggregate each view in its own operand. An aggregation with fanout: "allow" or fanout: "reduceToRelation" also reaches across many-to-many joins. Both enable fanout; reduceToRelation additionally reduces to the relation’s dimensionality. Neither bridges two views that only share an attribute, such as both joining to a part.
  • IF requires a condition, THEN value and ELSE value. Conditions use measure comparisons or null checks, joined with AND/OR and parentheses. Branches can contain compatible measure references, literal values or another IF. Arithmetic and parameters inside IF are not supported, and IF cannot be embedded in arithmetic.
  • Numeric values must be finite and filled in. Comparison and branch types must be compatible; a null branch needs a non-null alternative. Text, Boolean and null literal comparisons support equality/inequality or null checks.
  • General scalar functions such as DATEDIFF, CURRENT_DATE, ABS, ROUND and COALESCE are not stored-measure expression functions. SQL fields and aggregate filters have separate rules.

The examples above describe the calculation; typed authoring expressions refer to the input IDs provided in definition.inputs. Authoring tools reject unsupported expressions with a measure and expression-path diagnostic. Manually edited YAML can remain saved as a repairable draft with errors; publication requires a data connection with available capabilities and those errors to be resolved.

A filter on an aggregate input, and each rule of a custom-group (mapping) dimension, is a list of conditions, each naming a field, an operator and a value. They are stored exactly as the editor’s filter builder stores them. Values are typed from the field, so no data type needs to be supplied.

Operator Value
equals, not_equals, greater_than, greater_than_or_equal, less_than, less_than_or_equal one value, another field, or a single date (below)
contains, not_contains, like, not_like one text value
between, not_between two values, [from, to]; between also a date range
in, not_in a list of one or more values
is_set, is_not_set, hide_not_set none; hide_not_set drops null and zero or empty values
geo_intersects a polygon, on a geography field

A single-value operator given a list is refused; use in or not_in for a list.

like and not_like ignore case and use Astrato’s search syntax, not SQL: * matches any run of characters, ? matches one character, and \ escapes either. % and _ match themselves, so LG* keeps text starting with LG and *BRASS text ending with BRASS. A value with no * or ? matches anywhere in the text, as contains does.

A value written with a SQL % wildcard, such as LG%, would match only text containing “LG%”: like would keep no rows and not_like every row. astrato_data_execute_query refuses one, and so does an MCP authoring tool when its edit writes a value the layer does not already hold; each names the pattern to send instead. An edit that keeps a stored value, such as renaming the measure or a field it filters on, is not refused. To match a literal %, use contains or write \%. Layer validation shows the same problem as a warning on filters already stored.

A custom group rule is the exception: it still compiles like as SQL LIKE, so there % and _ are the wildcards and * and ? match themselves. See Search and wildcards in filters for more examples.

To compare two fields of the same row, give {"kind": "field", "field": {"view": ..., "field": ...}} with equals, not_equals or one of the four comparisons, for example orders shipped after they were due. Both fields must be of the same kind (number, date, text or Boolean).

An aggregate filter on another view’s field works only when each row the measure aggregates joins at most one row of that view, directly or through other views. When a row joins many, the filter cannot be evaluated: the measure still saves, but a question that uses it is refused when it executes; see Filters that cannot reach a measure’s rows.

A date or timestamp field also takes a generated date, resolved when the query runs:

  • {"kind": "relative_period", "period": ...} with between: year_to_date, month_to_date, quarter_to_date, week_to_date, their previous_…_to_date forms, extract_year_to_date and extract_month_to_date (the same to-date span in every year or month), last_12_months, last_90_days, last_30_days, last_7_days, current_year, current_quarter, current_month, current_week, previous_year, previous_quarter, previous_month, previous_week, today, yesterday, and minimum_date and maximum_date (the earliest or latest date in the data).
  • {"kind": "predefined_date", "date": ...} with equals, not_equals or a comparison: beginning_of_year, beginning_of_quarter, beginning_of_month, beginning_of_week, their beginning_of_previous_… forms, end_of_year, end_of_quarter, end_of_month, end_of_week, today and yesterday.
  • {"kind": "relative_date", "unit": "month", "offset": -1}, compared like a predefined date.
  • {"kind": "relative_range", "unit": "day", "from": -7, "to": 0} with between; from must not be after to.

Units are year, quarter, month, week, day, hour, minute and second. An operator a date form cannot take is refused with the one to use. A fixed date is written YYYY-MM-DD. Custom-group rules are compiled into a column once, so they accept fixed dates only.

geo_intersects takes {"kind": "polygon", "points": [[longitude, latitude], ...]}: at least four points, the last repeating the first, with longitudes from -180 to 180 and latitudes from -90 to 90.

The user attributes $userEmail and $userGroupNames are refused in both places. A stored measure would compare the parameter’s stored default rather than the requesting user, and a custom group would compile that default into its column. To restrict rows per viewer, add a security rule to the table in the editor, where the attribute resolves to the requesting user.