Written for: For developersUsing Astrato instead? Read the product guide
Semantic layer authoring reference
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.
Read the complete V3 document
Section titled “Read the complete V3 document”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,mimeTypeand UTF-8size;snapshotRevision, the exact draft revision in the resource;publishedRevision, ornullwhen the layer has never been published;publicationState:published,unpublished_changes,never_published,superseded, orunknownwhen the published model could not be read from the engine;unknowndoes 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.
Stored measure expression rules
Section titled “Stored measure expression rules”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.1are 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 asCOUNT_DISTINCT. When the connection’sCOUNTsupports distinct values, a request forCOUNT_DISTINCT,countDistinct,COUNTDorDISTINCT_COUNTis refused with a message that namesCOUNTwithdistinct: 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 withfanout: "allow"orfanout: "reduceToRelation"also reaches across many-to-many joins. Both enable fanout;reduceToRelationadditionally reduces to the relation’s dimensionality. Neither bridges two views that only share an attribute, such as both joining to a part. IFrequires 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,ROUNDandCOALESCEare 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.
Filter conditions
Section titled “Filter conditions”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": ...}withbetween:year_to_date,month_to_date,quarter_to_date,week_to_date, theirprevious_…_to_dateforms,extract_year_to_dateandextract_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, andminimum_dateandmaximum_date(the earliest or latest date in the data).{"kind": "predefined_date", "date": ...}withequals,not_equalsor a comparison:beginning_of_year,beginning_of_quarter,beginning_of_month,beginning_of_week, theirbeginning_of_previous_…forms,end_of_year,end_of_quarter,end_of_month,end_of_week,todayandyesterday.{"kind": "relative_date", "unit": "month", "offset": -1}, compared like a predefined date.{"kind": "relative_range", "unit": "day", "from": -7, "to": 0}withbetween;frommust not be afterto.
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.
What next
Section titled “What next”- Author a semantic layer over MCP — the prepare and apply workflows that send these forms.
- Semantic layer entity model — what a V3 document holds and how its entities reference each other.