Skip to content

Written for: For developers

Semantic layer entity model

44 min read · Updated 17 Nov 2026

Semantic Layer Document V3 is the authoring model used by the editor, its Dev tab, revisions, and MCP changes. It separates physical data structure from reusable business meaning while keeping every reference explicit.

Use Author a semantic layer over MCP for task-oriented MCP guidance. This page explains what the model contains and how its parts relate.

Check a Developer View edit before applying it
  1. The Developer View source editor showing the layer as JSON

    Developer View holds the whole layer as one JSON document; with the text untouched, Reset, Format, Diff and Apply stay inert. Change this measure's display label to begin.

  2. An edited label line in the JSON source editor

    Changing this measure's display label leaves the edit pending in the text and turns on Reset, Format, Diff and Apply; open Diff to see what will change.

  3. The pending changes diff with one changed label line

    Diff sets the current document beside your text, counts the lines that change, and offers Revert block to put a changed block back; Apply writes your text to the model.

  4. The diff reporting no line changes after Apply

    Apply replaces the model with the text you wrote: the button reads Applied, then goes inert, and the diff reports no line changes. Check the result under Business Context.

  5. The Measures list showing the measure under its new display label

    Measures lists the measure under the display label you typed as text, so the edit reached the ordinary editor; open the row to see both halves.

  6. The measure panel with its name and display label fields

    Opening the measure shows both halves of what you edited: the label controls its display text, while Name stays the key other entities reference.

New documents and exports use fileVersion: 3. V2 documents remain readable: loading migrates their supported calculations and result-filter references to canonical V3; subsequent saves write V3. This is not a promise that older editors can read V3. Keep older clients from rewriting migrated documents. See migration and compatibility for ambiguous-filter handling and retained history. The document version is independent of the MCP tool contract.

Named filters live in root filters. Each defines either filters or associativeFilters, with no type. A consumer uses reference: { filter: name } in its regular or associative filter slot. Invalid references remain visible as document errors; selectors prevent incompatible choices.

Business questions have a complete YAML reference.

The optional dataActions collection is a feature-gated Private Preview draft contract, marked in its schema and documentation. New or changed definitions require the data-actions feature flag; existing definitions remain readable and removable when it is disabled.

While this contract remains draft and feature-gated, breaking changes are allowed without automatic migrations. Affected definitions may need manual repair or recreation. This exception applies to data actions; the rest of the V3 document retains its documented compatibility rules. Saving or publishing a layer does not stabilize this contract. No draft-version field is added to saved documents.

Current definitions register a mapped table source’s writable operations and fields, or an existing stored procedure’s ordered warehouse arguments. Registration metadata is editor-owned. Data Actions have no separate access mode or user/group ACL. SQL or procedure code must enforce business access using trusted caller context; a view’s read filter does not automatically restrict writes. Table actions cannot target inline or custom-SQL views. Procedure schema, name, parameter names and warehouse type text must contain a nonwhitespace character; meaningful native identifier spacing is preserved.

Earlier draft definitions containing access are rejected. Remove that property and put the business authorization in the implementation; no automatic migration is provided. Discovery and status lookup are unavailable. Authoring, validation and preparation do not execute warehouse mutations, and publishing does not execute a definition. A published action runs through the Private Preview astrato_semantic_layer_run_data_action tool or from a published App.

Table-action references participate in field rename analysis and lineage. Writable tables and virtual procedures show authored field, dimension and measure context, plus mapped reads, writes and row-count checks derived from virtual-procedure SQL. A native stored-procedure workflow links only to its warehouse procedure through Calls; its body effects remain unknown, and parameter context adds no table or field edges. Workflow and warehouse-procedure nodes follow the data-actions feature flag. Missing references remain diagnostics, and the current usage catalog does not report workflow usage.

When the feature is enabled, Business Context → Business Workflows lists the registrations after Lineage. Search by name, description, category or target, or filter by kind or category. Group by category files each workflow under every category it carries, with those that have none last; Flat list is the default. Select a workflow to inspect its saved properties and version history. Create and edit writable-table registrations in this tab, or use Developer View or an imported document. Table registrations reference tables already included in the semantic map. The table picker offers mapped warehouse tables; an invalid saved target remains visible so you can repair it. Uncommitted name or description input prevents collaboration updates from replacing local work. The property panel has collapsible definition, table, operations and fields sections. Select a native stored procedure from the connection catalog to register its target and ordered signature. Selecting it again refreshes the signature; the catalog supplies native types. Business access belongs to the SQL or procedure implementation.

Stored workflow diagnostics remain available in Issues while the feature is disabled, including warnings that do not block publication. Open the issue link to inspect the definition in the Dev tab or remove the registration. Adding or changing a workflow still requires the feature flag.

Procedure catalog reads are limited to 2,000 entries. A larger result fails explicitly instead of returning an incomplete list; select a narrower schema before checking registrations. Catalog reads do not execute the stored procedures. Catalog signatures preserve nested native types and quoted argument names, including PostgreSQL array and user-defined types and Databricks precision and nested definitions. Malformed responses fail as unavailable catalogs. Unnamed inputs use a positional $1, $2, … label; Redshift uses these labels for every input because its catalog view reports ordered types without parameter names. Redshift signatures at the catalog’s 512-byte limit are rejected as potentially incomplete.

The procedure picker groups entries by schema and shows their parameter types. You can open and search it while metadata loads. Reload refreshes procedures and schema or dataset choices, including newly created or granted schemas. BigQuery requires a dataset selection before loading procedures. Other connections can browse all schemas or select one schema, including when the whole catalog exceeds the limit. Procedures with multiple signatures for the same native schema and name cannot be registered by name.

Publishing checks each registered procedure against the current catalog, including its exact schema and name, ordered parameters and return type. A missing, ambiguous, changed or unavailable signature blocks publication. Catalog checks are snapshots and do not prevent later warehouse changes.

In Private Preview, the optional writeback.mode setting selects dataSource or dataActions. When the feature is enabled, Settings → Business Workflows offers Business Workflows or Data connection permissions (marked Legacy). Each selection saves an explicit mode. An absent setting means dataSource, preserving connection-governed writes. Both modes are saved authoring and preparation metadata. Existing explicit table-write and procedure APIs remain governed by their own permissions and do not execute these definitions. This setting is also draft and requires the data-actions feature flag when changed or imported, including version restores.

New layers and imports use dataActions when the feature is enabled. Opening an existing layer does not select a new mode, even if its model is empty. Copies retain their source mode, including an absent setting.

With MCP tool contract 6.66.0 or later and the data-actions feature flag enabled (Private Preview), use astrato_semantic_layer_set_writeback_mode with a layer ID and mode: dataSource or mode: dataActions. It requires sl:write, stores either choice explicitly in the draft, and publishes nothing. Integrated authorization also requires permission to edit the layer. Nash uses the same tool. The tool is omitted from discovery and refused at invocation while the flag is disabled.

Writable fields have two scopes: All fields or an explicit selection. Clearing the selection permits no writable fields. Changing tables or cascading a field deletion preserves an empty restriction instead of changing it to all fields. Cascading a table deletion removes the registrations that target it; keeping broken references retains them for repair.

In Private Preview, MCP and Nash author registrations with astrato_semantic_layer_list_data_actions, astrato_semantic_layer_get_data_action, astrato_semantic_layer_prepare_data_action_change and astrato_semantic_layer_apply_data_action_change. Prepare returns a target and current revision; apply atomically creates, replaces, updates, renames or deletes a registration. Native schema/procedure spellings must match the catalog exactly, and BigQuery needs a selected dataset. These tools execute no warehouse mutation. The workflow-policy tool also accepts an optional expected revision and changes registration admission without adding action ACLs.

Version compare lists action changes under Business Workflows and shows their operations, fields, procedure signature and key-field scope. When the feature is disabled, existing actions remain inspectable, but restoring an action addition or modification is unavailable. Removing an action and restoring unrelated changes remain available. Importing edits from the earlier engine format preserves the registered actions and writeback.mode.

dataActions is an optional top-level map keyed by workflow name, each key holding at least one non-blank character. Its sibling writeback holds only mode, either dataSource or dataActions.

A workflow requires kind and implementation, and may carry description, categories, parameters, fields and returns. categories is an optional list of free-text labels, each used once; the editor’s Categories field and the MCP categories argument set the same property. kind is table, storedProcedure or virtualProcedure — the Add menu’s Writable table, Stored procedure and Virtual procedure. Writable table is offered disabled, with the reason Add a table to the layer first, on a layer with no mapped table.

implementation has ten optional properties and no required one, so {} is well-shaped:

Property Holds
view The target table, on a writable table
operation insert, update or delete — Insert rows, Update rows, Delete rows
keys The Key fields binding map, keyed by field name
values The Writable fields binding map
bindings The virtual procedure’s binding map; a non-empty one is refused elsewhere
dialects At least one dialect entry, keyed by dialect name
expectRows Accepted and stored, and read by nothing
transaction A boolean; absent means transactional
batch One required mode, perItem or set; stored, and read by nothing
result What the workflow returns

dialects is keyed by one of exactly thirteen names — snowflake, dremio, postgres, supabase, redshift, google_bigquery, databricks, clickhouse, trino, athena, duckdb, gsheet-duckdb, gsheet — and an unknown key is refused as unknown authored SQL dialect. Each entry holds exactly one of procedure or statements, plus optional database, schema, arguments and result; both or neither is refused as expected exactly one procedure or statements. A statement requires name and sql and may carry a non-negative expectRows, which is the editor’s Expected rows — left out entirely rather than set to zero when no count is wanted. Instead of a fixed count, a statement may carry expectRowsFromList, the name of a list parameter or binding: the step expects one row per distinct non-null item in that list on each run. A statement sets one of the two, and a name that is not a list is refused.

transaction defaults to all-or-nothing. An absent property reads back as the editor’s All or nothing; only an explicit false reads as Statement by statement. The checkbox is All statements commit or none.

A result requires mode — rows, scalar, affectedRows or none — and may carry statement, field, nativeDataType and encoding. encoding is json or string and is legal only on a scalar.

The Returns picker writes three of the four modes, into the active connection’s dialect rather than the implementation. Affected row count is { mode: 'affectedRows' } and is also what an absent result reads back as; Rows of the last statement is { mode: 'rows' } naming that statement; Nothing is { mode: 'none' }. A result the picker cannot express — a scalar, or a rows naming a statement that is not the last — reads back as a fourth, unselectable label, Explicit result, and is preserved untouched. The picker is disabled while the layer’s connection maps to none of the thirteen dialect names, because a write would then have nowhere to go.

A workflow’s parameters are an ordered array. Each requires name and dataType and may carry description, reference, default, nullable and evaluation. An omitted default is not the same as an explicit null, false or 0, because the check is for the property’s presence. evaluation is accepted by both shape checks and by MCP, and read nowhere.

A binding holds exactly one of reference or value, plus optional dataType, nullable and encoding, whose only accepted value here is json — unlike a result’s encoding, which also takes string. A reference carries exactly one key: parameter, naming one of the workflow’s declared parameters; context, an identity string; or input: 'rows', which is the only value that key takes.

The trusted identity contexts the editor writes are user.email, user.id and user.name. The Value picker lists them as Email, User ID and Name under a User attribute group, beside Any value and Explicit binding; the closed control and the summary line spell the three as User attribute: Email, User attribute: User ID and User attribute: Name, so the menu and the summary do not read alike.

An identity source is selectable only where the declared type can hold one: a parameter typed as text — varchar, nvarchar, char, nchar, character, character varying, string or text, in any case and with or without a length — or uuid for User ID alone, and a writable-table field whose layer type is exactly string. Elsewhere the three stay in the menu but cannot be chosen, and the option reads Requires a text parameter, or a UUID with User ID. That rule lives in the picker alone: a definition written in the Dev tab or through MCP can bind an identity to a parameter of any type, and no issue reports it.

A reference’s dataType and nullable are for one context class. A context beginning customer. must declare dataType, and is the only reference that may carry nullable, or override the native type of a procedure argument; both are refused elsewhere as reference datatype/nullability overrides require customer context. A dataType on any other reference in a keys, values or bindings map is accepted, because there is no native type there to override. Nothing in the editor writes a customer. context; it is there for a document authored outside it.

A default on a parameter, and a value on a binding, may be a JSON scalar or an array of scalars. A nested object or a non-finite number is refused as expected a JSON scalar or scalar array.

fields and returns describe a workflow rather than drive it. fields maps a field name to a note holding description and reference, and nothing else — the editor’s Note and Refers to pair. returns holds one required fields map, from an output name to a required dataType and an optional nullable; it declares an output shape and is unrelated to implementation.result, which chooses what a run hands back.

A reference on a parameter or a field note takes a different shape from a binding’s: exactly one of { parameter }, { dimension }, { measure }, { businessQuestion }, or the two-key { view, field }. The two keys spelled parameter resolve in different scopes. On a parameter or a field note it names an SQL parameter declared on a view or a measure anywhere in the layer; on a binding it must name one of the workflow’s own declared parameters.

dialects.<dialect>.arguments is ordered: position n binds the procedure’s nth argument. Each entry is a binding plus a required nativeDataType. A value argument, and one bound to a customer. context, must also declare dataType; a parameter or input reference must not, because it inherits its type and nullability. MCP enforces the same two rules in its own words: Literal and customer arguments require dataType. and Parameter and input references inherit their type and nullability.

What publishing requires is in the validator rather than the schema, and differs by kind:

Kind Needed to publish
table An implementation.view naming a mapped physical-table view, one operation, and keys bindings when that operation is update or delete. Every name in keys, values and fields must be a field of that view, and a fields note needs a key or value binding to sit on.
storedProcedure At least one dialect entry, each carrying a procedure. Where an entry matches the connection’s own dialect, names a schema and that schema’s catalogue has been read, its procedure must appear there with the same argument count and the same ordered native types; a catalogue that cannot be read is reported in its place.
virtualProcedure At least one dialect entry, each carrying at least one named statement.

Three rules apply to every kind: a parameter declared twice, a binding naming a parameter the workflow does not declare, and a reference pointing at an entity the layer no longer holds are each reported against the workflow.

astrato_semantic_layer_apply_data_action_change takes one of five operations — create, replace, update, rename and delete. An update carries a patch in which an omitted property keeps its value and null clears optional metadata; implementation is the exception, replaced whole rather than merged, and it cannot be cleared.

MCP copying requires the data-actions feature; ordinary empty-layer creation remains available while it is disabled.

Copying an older layer keeps its valid stored filters, business questions, datasets, map layout and authoring settings and skips invalid fields. If the source changes during the copy, or the new layer is opened before the copy completes, the copy fails and cleanup is attempted. A copy that returns no usable layer ID is reported as a failure; check the layer list before retrying. If an HTTP error includes cleanupFailed: true and createdId, delete that incomplete layer before retrying. A document import fails in the same way instead of dropping editor-owned content. MCP errors name the layer when cleanup fails. Otherwise, retry to copy the current definition.

flowchart LR
connection[Data connection] -. routing context .-> layer[Semantic layer]
layer --> views[Views]
layer --> joins[Joins]
layer --> dimensions[Dimensions]
layer --> measures[Measures]
layer --> udfs[Functions]
layer --> questions[Business questions]
layer --> storedFilters[Stored filters]
views --> fields[Fields]
views --> filters[View filters]
joins --> views
fields --> dimensions[Dimensions]
fields --> measures[Measures]
dimensions --> dimensions
measures --> measures
dimensions --> questions[Business questions]
measures --> questions
fields --> questions
fields --> storedFilters
storedFilters --> questions
udfs[Functions] --> queries[Query expressions]
acl[Access grants] -. protect .-> layer

Solid arrows show containment or semantic references. Dotted arrows show platform context that is stored outside the V3 entity collections.

Entity Identity and ownership Important properties References
Semantic layer An external semanticLayerId identifies the resource. The ID is not embedded in V3. name, description, datasource, locale, queryFeatures Routes to one data connection through datasource.
View Keyed by name under views. A view owns its fields, SQL parameters, and row filter. source, description, sqlAlias, singleGrain, filter, filterMode A source names a physical object, contains custom SQL, or contains inline data.
Field Keyed by name under a non-inline view. Inline columns are the fields of their view and preserve array order. source, dataType, optional native type, label, description, precision, enabled state Always belongs to one view. Other entities use { view, field } references.
Join Ordered entry under joins; its two endpoints provide its semantic identity. views, cardinality, ordered conditions Connects exactly two views. Each condition compares expressions, normally fields from the endpoints.
Dimension Keyed by name under dimensions. Common metadata plus the properties of its variant A field or bucket dimension references a field. A drillthrough contains ordered field or dimension levels.
Measure Keyed by name under measures. Its class is derived, not stored. resultType, formula expression, m1… operand blocks, format, parameters, metadata Operands may reference fields, measures, or measure-local parameters.
Function Keyed by name under udfs. Function signature order is significant. kind, path, resultType, ordered parameters, supportsDistinct, metadata Query expressions bind arguments to signature parameters. Stored measures do not publish function calls in the current model.
Business question Keyed by name under businessQuestions; top-level and independent of datasets. Meaning and business-value prose, selections, filters, sorting, chart recommendations, defaults Selects fields or dimensions and measures; follow-ups reference other questions by name.
Dataset Keyed by name under datasets. Editor-owned; it is not sent to the query engine. description, categories, ordered dimensions and measures, filters Lists existing dimensions and measures by reference. Filters are pre-aggregation conditions on fields or dimensions, as on a business question.
Stored filter Keyed by name under filters, across both types. Editor-owned; it is not sent to the query engine. description, categories, and exactly one associativeFilters or filters body A set filter keeps target values; a regular filter holds conditions. Consumers use reference: { filter: name } in the matching existing slot.
Data action Keyed by workflow name under dataActions. A draft contract, behind the data-actions feature. kind, implementation, and optional description, parameters, fields and returns A writable table names a view and its fields; a virtual procedure binds its own parameters. See Data action properties.

Eight top-level properties are required: fileVersion, name, views, joins, dimensions, measures, udfs and layout. Everything else is optional. The V3 document has no top-level object, relationship, security-rule, or table-limit collection, and an unsupported top-level property is rejected instead of being silently discarded.

Dimensions, measures and functions share a metadata block: label, description, categories and synonyms, the last an array of unique strings.

Synonyms are a live setting with no editor control. The MCP query catalogue matches a search against an item’s name, label, synonyms and description, and scores candidates by them — so a synonym is how someone’s own word for a measure finds it. Nothing in the editor authors them: the measure editor’s input is switched off, and the dimension panel’s editable list is wired to Categories. They reach a layer from a Snowflake or Databricks import, from MCP, or from a Dev tab or YAML document, and they survive an edit in the editor even though nothing shows them.

A view has exactly one source variant:

Source kind Stored source Field ownership
Physical table or view type: table plus table, and optionally database, schema, and objectType The view’s name-keyed fields map describes physical or expression fields.
Custom SQL type: sql, a statement, and optional typed parameter defaults Result fields are stored in the view’s fields map.
Inline data type: inline, ordered columns, and header-bearing csv columns are the fields; an inline view does not have a second fields map.

Physical source identifiers preserve the exact casing supplied by the data source. Source discovery metadata is temporary catalog context, not part of the semantic-layer document. Confirmed missing source objects can be marked on the affected view, field, or function so the draft remains repairable; see Semantic layer issues.

A view’s singleGrain accepts only auto. In the table panel, the Use inner join checkbox under Join type sets it; clearing the checkbox removes the property. The section appears only when Settings → General → Enable inner join for tables is on. Turning that off hides the section and leaves any singleGrain already set in place.

The Orders table selected on the map, with the Use inner join checkbox outlined under Join type in the panel on the right

Custom SQL int parameter defaults must be within the exact integer range −9,007,199,254,740,991 to 9,007,199,254,740,991. Values outside that range are rejected instead of rounded. Boolean defaults are stored as true or false and keep that representation when you reopen and save them.

For a list parameter, use {ids:int_list} or {labels:string_list} in your Custom SQL and enter a comma-separated default such as 1,2 or ok,other. Validate SQL checks the statement using those defaults. After validation succeeds, Run SQL preview runs the same statement with the same defaults and shows its first 20 records. Keep the list type in the SQL token; you do not need to change it to int or string to validate or preview.

A field’s dataType is the engine’s own enum, matched exactly and in lower case. Sixteen values are accepted:

string, int, integer, float, number, decimal, date, time, time_tz, timestamp, timestamp_tz, boolean, bool, json, geography, unhandled.

An inline view’s columns take a narrower nine: date, timestamp, timestamp_tz, string, int, float, number, boolean and bool. Both checks print the whole accepted list in the error, so the valid set is on screen at the point of failure: source.columns[2].dataType: dataType "json" is not supported. Use one of: date, timestamp, ….

The accepted set is wider than the one the product offers. The type picker on a field row offers eight — boolean, date, float, int, string, time, timestamp, timestamp_tz — so a decimal or a json written in the Dev tab validates but cannot be reached through the picker afterwards. It is shown rather than hidden, but decimal and bool have no display name of their own, so a field carrying either shows no type icon and its raw value as its label.

A physical column may additionally opt into a driver’s native type, stored as nativeDataType beside its dataType; the picker then displays the native name in place of the canonical one. The pairing is checked against the connection’s driver, and one combination exists today: BigQuery’s INT64, which pairs with dataType: string. Anything else is a validation error naming the native types that driver accepts, or (none) where it accepts none. The check needs the layer’s connection; a draft with no resolved connection does not report a bad pairing.

Two derived kinds narrow it further, and these two comparisons are case-insensitive:

  • A bucket dimension’s source must be int, integer, float, number or decimal — “Select a numeric source field for the bucket dimension.”
  • A period axis source must be date, timestamp or timestamp_tz — “Select a date or timestamp source field for the period axis.”

A join key is checked the same way: two sides must carry either the same type or two numeric-family types.

An inline table authored in the editor offers six types, and timestamp_tz, number and bool are not among them. Writing one by hand is accepted by validation here but may still be refused further down: the CSV importer rejects timestamp_tz and bool, and takes json only to fail when the row is written.

Set a dimension’s optional label alongside its kind. The label controls its display text; the dimension’s map key remains its identity for references. Publishing and importing preserve the label across dimension variants.

Kind Meaning Relationship
field Reusable semantic name for one physical or calculated field References one { view, field }. Date level, date part, and formatting are optional.
bucket Evenly spaced numeric groups References one field and owns a bucketing block of five required settings.
mapping Custom groups evaluated in order; the first matching rule wins References a base field and owns filters, typed group values, and an optional default.
drillthrough Ordered hierarchy for moving from summary to detail Contains one or more field or dimension references. Level order is semantic.
periodAxis Reusable date window for period-aware calculations Owns periodAxis.sources, period, and level.

A drillthrough may reference ordinary field dimensions. Cycles and drillthrough-to-drillthrough nesting are invalid because the ordered field sequence must be deterministic.

A period axis uses the same block globally and inside a named business question. See Period axes reference for the full YAML contract, relative dates, multiple sources, compatibility rules and examples.

A bucket dimension’s bucketing requires all five of minValue, maxValue, buckets, bucketNo and outerBuckets — the first three finite numbers, the last two booleans. Miss two or more and the error states the whole shape at once rather than one key at a time:

bucket dimension is missing `bucketing.bucketNo`, `bucketing.outerBuckets`. It needs resultType,
reference: {view, field} and bucketing: {minValue, maxValue, buckets, bucketNo, outerBuckets}

bucketNo decides what a row reads as — the bucket’s number when true, the value the bucket starts at when false. outerBuckets decides whether values outside the range get buckets of their own or fall out of the result.

A bucket excludes its maxValue. A row exactly at maxValue is outside the range, so with outerBuckets false it reads as null. When the editor or MCP fills in the range from the field, the maximum is the next whole number above the field’s highest value: a field measuring 1 to 100 gets 1 to 101. Set a range yourself with the same rule in mind.

Those two flags have three spellings. The document stores bucketNo and outerBuckets. MCP authoring and the filter transform below call them includeBucketNumber and includeOuterBuckets, and an MCP create defaults both to false when they are omitted, because the document requires them. The MCP query catalogue reports them as enumerations rather than booleans: value is bucketNumber or bucketStart, and outOfRange is outerBucket or null.

A bucket dimension’s authored resultType is ignored. The schema requires it, but the compiler overwrites it from bucketNo on every load: int when true, float when false. Writing resultType: int beside bucketNo: false does not make the dimension an integer; it makes the two disagree until the next load silently settles it.

Validation adds two rules the shape check does not: the range must increase, and the count must be a positive whole number. So buckets: 0 or buckets: 2.5 is a well-shaped document that fails to publish, with “Enter an increasing bucket range and a positive whole-number bucket count.” The editor’s Buckets box clamps what you type to at least 1 but does not round it, and MCP refuses a count that is not a positive integer, so a zero count arrives only from the Dev tab or a YAML import.

In the editor, Distribution holds Min value, Max value, Buckets and Include out-of-range buckets; a new bucket dimension starts at 0 to 100 in 5 buckets with both flags off. There is no control for bucketNo anywhere, so a bucket that reports numbers rather than range starts can only be written in the Dev tab or imported.

A filter subject can carry the same banding as a transform, under different names: transform: { bucket: { minimum, maximum, count, includeBucketNumber, includeOuterBuckets } }. You rarely write it: the compiler derives it when it opens a legacy filter that carried its own bucketing.

Custom-group rules preserve empty text and null as distinct values. Equality with null checks for a missing value. A list containing null and text matches either, including an explicitly authored empty string. Exclusions follow ordinary filter behavior: excluding non-null values retains null rows; excluding only null matches non-null rows.

Integer group values and defaults use the same exact integer range as SQL parameter defaults. Out-of-range values remain available for correction in the editor and block publication.

Date and time comparisons carry their type with their text, for example { value: '2026-09-23', dataType: date }. Simple and advanced editing preserve that type. Rules containing null comparisons or empty-string list members open in advanced mode so those values remain distinguishable. Legacy millisecond literals cannot be compiled into custom-group rules; replace them with explicit date or time text and its matching type. Validation reports this before publication.

Choose date grouping by the question you want to answer:

Setting Meaning Across years
dateLevel: month A date-valued monthly time bucket January 2025 and January 2026 remain separate.
datePart: month The numeric month of the year Both Januaries share the same value, useful for seasonal comparisons.

A chronological monthly trend can span years without changing its date level. Use date parts when you intend recurring calendar categories, rather than choosing them from the number of years in the data. Date grouping and period comparisons serve different purposes.

Set a measure’s optional label alongside its expression and resultType. The label controls its display text; the measure’s map key remains its identity for references. Publishing and importing preserve the display label, including for derived, conditional and period measures.

measures:
Order Count:
label: Distinct orders
resultType: int
expression: '{m1}'
m1:
aggregate: COUNT
distinct: true
arguments:
- reference:
view: Orders
field: Order ID

Every measure uses the same readable formula plus operand-block representation. Its compatibility class is derived from the formula and references:

Derived class Rule
Aggregate Contains no named-measure reference.
Derived References named aggregate measures and contains no conditional if expression.
Conditional Contains an if expression and at least one named-measure reference.

Measure formulas refer to sibling blocks such as {m1} and {m2}. Nested definitions may use qualified names such as {m2m1}; these names resolve only inside their own calculation. An operand can be a reference, scalar or date value, operator, aggregate, or function call. Aggregate operand keys below lists everything an aggregate may own. Measure-local parameters are name-keyed typed defaults referenced from operands or aggregate filters.

The aggregate’s fanout option is omitted by default. fanout: allow enables fanout; fanout: reduceToRelation enables fanout with reduction to the relation’s dimensionality. Those are the only two values; any other is refused as expected allow or reduceToRelation. Publishing and YAML import preserve both parts of the reduced-fanout setting. Check results at each intended grouping: a correct ungrouped total does not establish that results across a many-to-many join are correct.

Structured comparison operators use textual names such as notEquals. Measure expression strings use formula symbols: =, !=, >, >=, <, and <=. For example, if({m1} != 'External Calculation', 'Not required', 'Required') compares the referenced measure to a string. Each textual comparison has one formula spelling; notEquals renders as !=. Legacy <> comparisons remain readable and normalize to != when rendered for execution.

Timestamp parameter defaults are independent of your device timezone. Use a full ISO date and time with seconds and at most three fractional digits. A timestamp without an offset keeps its wall-clock value; an explicit offset is normalized to UTC. A timestamp_tz must include Z or an explicit UTC offset, for example 2026-01-02T03:04:05+13:00. The editor does not guess an offset from the model timezone. Existing numeric defaults remain epoch milliseconds. Invalid calendar dates and values finer than millisecond precision are rejected rather than silently changed.

The model’s locale.timezone accepts named IANA timezones such as Pacific/Auckland, including supported aliases such as US/Pacific. Names are case-sensitive: US/pacific is invalid. Timezone-aware timestamp grouping and relative date boundaries use the model timezone, including its daylight-saving rules. Date-only and unzoned timestamp values retain their own type-specific behavior.

When the entire locale is omitted, query compilation uses the engine’s Europe/London default. If locale is present, set timezone to a string: use UTC or an empty string for UTC, or a named zone. A missing timezone inside a present locale, invalid names, standalone offsets and the machine-dependent Local value are reported as settings errors. An existing invalid setting remains visible in a draft so you can repair it before publishing.

An aggregate measure can add a stored period comparison while keeping the same formula and operand blocks:

dimensions:
Order Timeline:
kind: periodAxis
resultType: date
periodAxis:
sources:
- reference: { view: Orders, field: Order Date }
period: currentYear
level: month
measures:
Sales growth:
resultType: float
expression: '{m1}'
m1:
aggregate: SUM
arguments:
- reference: { view: Orders, field: Amount }
periodAxis:
reference: { dimension: Order Timeline }
comparisonPeriod: year
periodComparison:
type: growth
reference: { dimension: Order Timeline }

Stored period comparisons accept current, value, diff, ratio, and growth. They reference a period-axis dimension. An explicit comparison offset belongs to the measure-local periodAxis binding. Named periods can retain their built-in previous interval by omitting the offset; relative periods require an explicit offset. Explicit reduction belongs to the sibling nestedCalculation property.

An aggregate operand accepts seventeen keys and refuses any other by path. aggregate is a required non-empty string and arguments a non-empty array; parameter is shared with every other expression node and is how a measure-local parameter is attached.

Key Accepts
distinct, absolute, cacheResult, geoMakePoint boolean
scope total and nothing else
filteredOutValue zero or null
delimiter string
geoSimplify, options object
orderBy array of { reference, direction? }
partitionBy array of { reference }
withinGroup a single { reference, direction? }
filter, fanout a filter block, and the fanout setting described above

filteredOutValue: null is accepted by the shape check on any aggregate but by validation only on a SUM: anything else reports “Use null in measure filter is supported only for SUM.”

orderBy, partitionBy and withinGroup reach the engine as the ORDER BY, PARTITION BY and WITHIN GROUP clauses of a windowing function, and its contract states that a partitionBy omits the GROUP BY the query would otherwise carry. An aggregate’s partitionBy is not the partitionBy of a business question’s advanced calculation, which names that question’s own dimension keys; see the business question YAML reference for that one.

The measure panel and formula editor expose Total (scope: total), Abs (absolute: true) and Fanout. Fanout has three modes:

Mode Document value Behavior
Disabled fanout omitted Uses the measure’s normal relationship rules.
Allow fanout fanout: allow Allows joined rows to repeat before aggregation.
Allow fanout with relation reduction fanout: reduceToRelation Reduces repeated joined rows at the relation’s dimensionality before aggregation.

Count distinct and other supported distinct aggregations set distinct: true independently. They aggregate unique values; relation reduction operates on the joined rows and their relation keys. A measure can use both. Changing either setting preserves the other. Imported fanout modes remain selected when you edit a measure, and version comparison shows fanout for each operand, including embedded calculations. Row-expression aggregates offer the same fanout modes.

Use null in measure filter writes filteredOutValue: 'null'. The formula editor offers it on single-field aggregates and disables it outside SUM; the measure panel disables it until there is a filter. Validation requires SUM. Clearing an option removes its key.

delimiter, cacheResult, geoMakePoint, geoSimplify, withinGroup, partitionBy and options have no control anywhere in the editor. They are not casualties of that: MCP preserves them deliberately when it replaces an operand that aggregates the same thing, and they round-trip from legacy layers. Five reach the engine verbatim; partitionBy and withinGroup are rewritten into the engine’s own field-key shape on the way.

The options the editor does write are renamed for the engine, so an aggregate in the document and the same aggregate in an engine request do not read alike: fanout: allow becomes allowFanOut: true, fanout: reduceToRelation adds reduceToRelationDimensionality: true beside it, scope: total becomes total: true, and filteredOutValue: 'null' becomes allowNullForSumFilters: true. Only absolute keeps its name. options is spread last, after every one of them, so a key inside it overrides whatever the aggregate derived.

A list aggregation gets a delimiter whether or not the document holds one: LISTAGG, LISTAGG_DISTINCT, VALUE_LIST and VALUE_LIST_DISTINCT fall back to a comma and a space.

Every one of the option keys above except distinct makes a measure too complex for Apache Ossie export. A Databricks metric-view export is blocked by the same set apart from filter and cacheResult, so a measure whose only option is one of those two exports to Databricks and not to Ossie.

Filters, table limits, and row-level security

Section titled “Filters, table limits, and row-level security”

A filter is embedded where it applies, unless it is stored under filters as a named entity for questions to reuse. It stores a Boolean formula over sibling condition blocks such as {f1} AND ({f2} OR {f3}). Each condition owns an operator and ordered expression arguments.

Owner Effect
View filter Restricts rows before queries use the view. filterMode controls whether the filter is active and strict.
Aggregate operand filter Restricts rows used by that aggregate.
Business-question filters Applies before aggregation. Subjects may be fields or dimensions.
Business-question resultFilters Applies after aggregation, before or after advanced calculations depending on its subject (details); with keyed measures it addresses completed selection keys.
Stored regular filter Reusable conditions, referenced from a compatible regular filter slot; the consuming slot determines when they apply.

Table limits and row-level security are authoring views over a view’s existing filter and filterMode; they do not create another collection. A view-filter comparison against the reserved user-context parameters $userEmail or $userGroupNames is resolved per requesting user. Other view-filter comparisons are ordinary static pre-filters.

When opening legacy layers or drafts saved by an older importer, view and aggregate filters recognize untyped strings as dates only when the comparison expects a date and the value is a real calendar date in exact YYYY-MM-DD form, such as 2026-08-14. The text stays unchanged; the literal gains dataType: date. This does not infer timestamps or numeric date parts, change explicit types, or repair invalid dates. Values outside this rule keep their existing validation diagnostics so you can correct them before publishing. New document authoring still requires explicit date types.

filterMode, and where the group limit lives

Section titled “filterMode, and where the group limit lives”

filterMode is an object of exactly two required booleans, active and strict. The editor always writes both: a filter with no stored mode is treated as { active: false, strict: false }.

Apply as global data reduction writes active. Strict writes strict, and its checkbox is rendered only while active is true. Ticking Apply as global data reduction sets both to true, and clearing it sets both to false; a document written another way can still carry strict: true with active: false and show no control for it. What strict changes is decided by the query engine; nothing on this side defines it. The engine’s published contract declares both booleans with a default of true, while this side treats an absent mode as { active: false, strict: false }, so the two disagree about an unwritten value. Write both rather than relying on either default.

Only a physical-table view offers the controls, and the engine agrees: its own filter-group-config rule refuses an active mode on a statement view, and refuses one with no conditions.

Removing the last condition keeps the mode. Dropping a view filter’s conditions removes filter and leaves filterMode in place, so a view can carry a mode with nothing to apply. Only the section’s Clear removes both.

Limit to groups is not a property of its own. The list is stored as the view filter’s userGroupNames SQL-parameter default — one comma-separated string — which is why a group name cannot contain a comma, and why the editor refuses one with “Group names cannot contain a comma.” On compile it is split on commas, trimmed, emptied entries dropped, and sent to the engine beside the mode. The limit is sent whether or not the rule is a global data reduction; with no limit at all, the view’s filterMode is sent verbatim, or nothing is sent when the view has no mode.

Both directions join the names with a comma and a space: the editor writes A, B, and reading an engine model back writes the groups it carries to the same parameter default in that form. Compiling re-splits and trims, so A,B and A, B are the same limit.

Two user-context parameter names are reserved, userEmail and userGroupNames, and the literals $userEmail and $userGroupNames are what resolve per requesting user. $userGroupNames holds several values, so a condition comparing against it takes only inList or notInList; pointing an existing condition at it rewrites the operator to one of those.

MCP authors the mode directly: astrato_semantic_layer_apply_view_change takes filterMode as a strict object of those two booleans, and null clears it.

For the task rather than the shape, see Restrict rows with a security rule.

Semantic-layer access grants protect the whole semantic-layer resource and are not V3 entities. See Manage resource access for granting permissions to people, groups, workspace roles or everyone in your workspace. With explicit resource access enabled, creating a layer does not provide irrevocable access: the creator’s grants can be changed or removed. Workspace owners and administrators retain full access. Row-level security controls which source rows a permitted query can return.

Keeping access grants outside the V3 document prevents copying or exporting semantic definitions from accidentally copying resource permissions.

A business question combines governed selections with the prose needed to understand the answer. Its dimension selections may reference fields directly or reference named dimensions; its measure selections reference named measures. Selections are ordered lists, and list order is the presentation order. Give every entry a key when you need local aliases, inline periodAxis dimensions, or local calculations; keys then identify the question’s output columns, and advanced calculations refer to the dimension keys. Filters, result filters, prioritized sorting, Top N, chart recommendations, categories, and follow-up questions refine how consumers use it.

Questions are stored and versioned with the semantic layer but are not emitted to the query engine’s legacy composite. They are still validated: a missing selected entity or a question with no measure blocks publication because an agent could not execute it. Renderer recommendations are advisory; omitting output configuration means table output. See Business questions.

locale is optional, but it is all-or-nothing: a present locale must carry number, formats and calendar beside its timezone. Omit one and compilation stops with $.locale.number: expected an object, naming whichever sibling is missing.

Key Shape
locale.number decimalSep and thousandSep, both strings
locale.formats date, datetime, money, number, numberInt and time, all Excel format patterns
locale.calendar dayNames and dayNamesAbbr (7 each), monthNames and monthNamesAbbr (12 each)
locale.timezone An IANA name, or an empty string for UTC

A missing key inside one of those objects is reported against locale, not against the key. A formats block without date fails with $.locale: locale property `date` must be a string, so searching the error for $.locale.formats.date finds nothing. Only a wholly absent sibling object is reported at its own path.

Calendar lengths are enforced twice over, by the published v3 schema and again by validation, which reports locale.calendar.dayNames must contain exactly 7 entries, got 3. An empty or whitespace-only entry is its own error: locale.calendar.monthNames[4] must be a non-empty name.

A pattern is an Excel format pattern, not a formula. The editor refuses eight ways: a leading = or any brace, a control character, an empty box, more than 128 characters, more than four semicolon-separated sections, unbalanced brackets, unbalanced quotes, and a pattern carrying no placeholder at all. The placeholder test looks for 0 # ? @ y m d h s in either case — YYYY-MM-DD passes — and ignores anything inside double quotes or square brackets, so a d in a quoted literal does not count as one.

When the layer defines no pattern, these are used:

Format Default
date yyyy-mm-dd
datetime yyyy-mm-dd hh:mm:ss
time hh:mm:ss
money $#,###.00
number #,##0.00
numberInt #,##0

A stored pattern that fails validation is read back as the default, not used. The invalid text stays in the document — the Dev tab and the compare panel both show it, under Locale › Formats › Date — but nothing formats with it. Five legacy sample values are discarded the same way, in favour of the default: 2021-06-21, 2021-06-21 00:00:00, $2,500.00, 2,500 and 00:00:00.

An empty string means UTC. A named zone must be an exact IANA name, so US/pacific is refused with locale.timezone must be a named IANA timezone, such as Pacific/Auckland, or empty for UTC. That is both a compile error and a validation issue, so it also appears in Issues and blocks publishing. In the editor the control is a searchable picker rather than a text box, so an invalid name usually arrives from a YAML import or the Dev tab.

Settings → Format holds Decimal separator, Thousand separator, Date, Date time, Time, Number, Integer and Money; Locale holds Timezone. There is no control for the calendar names: the editor supplies English Gregorian defaults — Sunday to Saturday, Sun to Sat, January to December, Jan to Dec — and only the Dev tab or a YAML import can change them.

The Format section of Settings with the Decimal separator and Thousand separator boxes above the six format patterns

The two separators commit on every keystroke. The six pattern boxes beside them commit when the box loses focus, and only if the pattern passes the check, so a rejected pattern stays on screen with its reason and never enters the document.

Opening Settings and touching one field writes the whole locale. Every patch is merged over a complete default first, so the editor cannot produce a partial one. The side effect is worth knowing: a layer with no locale at all compiles at the engine’s Europe/London default, while Settings → Locale → Timezone shows UTC, because the panel is displaying a default the document does not contain. Edit any Format field and that UTC is written in, moving the layer’s timezone without your having touched it.

Whatever locale holds reaches the query engine unchanged, so separators, patterns and calendar names are live model settings rather than editor decoration.

The following are document settings or derived state, not independently addressable semantic entities:

  • locale, queryFeatures, authoring, metadata and opaque engine compatibility properties apply to the document;
  • layout stores editor positions and display choices;
  • SQL and filter parameters belong to their owning view, measure, or filter;
  • revisions, publication state, validation issues, source-catalog data, and query capabilities are computed or stored outside the V3 document.

The Dev tab exposes lossless V3 JSON and YAML. Apache Ossie export is a read-only projection of the current valid draft, not another authoring model.

Large YAML imports retain change history for every changed entity. Saving the imported draft is atomic: if saving fails, the previous saved draft remains intact. Creating a version also retains the complete change history for the revisions it covers.

authoring holds two properties. enableInnerJoinForTables is a boolean written by Settings → General → Enable inner join for tables, off by default; it decides whether table panels show the Join type section, and turning it off changes no table’s join. groupedDimensionOptions takes only dimensions and dimensionsOnly. Those are the two states of the Settings checkboxes: Show dimensions as options writes dimensions, Show only dimensions switches it to dimensionsOnly, and clearing the first drops both. It is a live setting — the custom-group Base field picker reads it to decide whether to list dimensions and whether to hide table fields.

The Custom groups section of Settings with its Show dimensions as options and Show only dimensions checkboxes

queryFeatures holds exactly three properties:

  • autoAssociativeFilters — Settings → General → Enable auto associative filters, a boolean that defaults to on. Anything other than an explicit false is treated as enabled, and only an explicit false reaches the engine, as disableAutoAssociativeFilters. See Automatic associative filters for what it does.
  • tableAliasInSqlInsights — Use table alias in SQL query insights in the same section, a boolean that is off unless explicitly true.
  • options — an opaque object passed to the engine verbatim, an escape hatch for engine properties rather than an Astrato setting. It is spread beneath the derived associative-filter flag, so disableAutoAssociativeFilters is the one key inside it that the checkbox overrides.

Importing from the earlier engine format rebuilds autoAssociativeFilters and options and not tableAliasInSqlInsights, while the aliases themselves are carried over — so a layer that came back that way keeps its sqlAlias values and loses the setting that generated them.

metadata holds one property, importSources, keyed by DATABASE.SCHEMA.NAME. Each entry requires format — snowflake-semantic-view or databricks-metric-view — plus datasourceId, database, schema and name. It is the only top-level collection the schema marks editor-only and never emits to the engine, and it is read widely: the imported-view icon and tooltip on a table, the import callout on an element, the upstream-schema status, and the issue text when a source has drifted all come from it. It is also the one setting collection version compare does not read, so a changed import source produces no comparison row.

Table aliases are a model change, not a display preference

Section titled “Table aliases are a model change, not a display preference”

Use table alias in SQL query insights, in Settings → General, presents itself as a readability setting — its own hint says aliasing “improves the readability of the queries produced by Astrato, and simplifies debugging and sharing the queries”. It does more than that. Turning it on gives every view a unique sqlAlias, those aliases are serialized into the published engine model, and the next draft save persists them. A reader who ticks it expecting a debugging convenience has edited the model.

While it is on, each table’s panel gains a Table alias box with the placeholder “Generated from the table name”. A typed alias is 3 to 8 characters of lower-case letters, digits and underscores, starting with three letters and not ending in an underscore. Anything else is refused with “Use 3 to 8 characters: letters, digits and underscores, starting with three letters.”, which does not mention the casing, so Orders is rejected without saying why; a clash reads “Already used by table.” A refused alias is never stored: the box keeps the text while the table keeps its previous alias.

Clearing the box hands the alias back to be generated again. Generation keeps an alias that already meets the rule, so your own naming survives; where two tables hold the same one, the first keeps it and the second is generated afresh.

New and updated joins store these canonical textual values:

Stored value Editor symbol Accepted V3 compatibility aliases
equals = equal, =, ==
notEquals ≠ notEqual, !=, <>, ≠
greaterThan > >
greaterThanOrEqual ≥ greaterThanOrEqualTo, >=, ≥
lessThan < <
lessThanOrEqual ≤ lessThanOrEqualTo, <=, ≤

Loading normalizes a compatibility alias to its canonical value. Applying or exporting the document writes the canonical textual operator. Unsupported values are rejected with the affected condition path.

Names are entity identity in V3. Reference-aware rename operations can update supported dependent references atomically. Field data-type changes list definitions that read the field so you can review their compatibility before applying the change.

The editor asks for confirmation before removing a view, field, measure, dimension, join, or function. This includes entities with no known dependencies inside the semantic-layer document because a connected workbook can still use them. When dependencies are known, the confirmation lists the affected entities and lets you either remove dependent definitions or preserve them for manual repair. Preserved broken references remain visible as draft issues and block publication until repaired.

Removal confirmations block interaction with the editor until you confirm or cancel, so changing the current selection cannot retarget an open destructive action.

Measure selectors and explicit nested aggregation

Section titled “Measure selectors and explicit nested aggregation”

Use periodAxis: { reference: { dimension: Order Timeline }, period: yearToDate, level: month } for measure-local overrides. Use nestedCalculation: { aggregate: SUM, dimensions: [{ reference: { dimension: Order Timeline } }] } for an explicit reduction. An optional inner nestedCalculation.periodAxis preserves its own settings separately from the outer binding.

See Measure overrides and reduction for full examples and editor instructions.

A measure operand can contain a complete calculation definition. Use this to calculate a result per City, reduce it with SUM or AVG, and compare the reduced results without creating helper measures. Agent measure authoring writes this shape. In the measure editor, a measure operand’s Nested calculation icon (Σ) writes its one-measure form, shown as a measure row with its grain. A measure that already holds any other embedded calculation shows it in a calculation form, so it stays editable and saves intact.

resultType: float
expression: '{m1}'
m1:
calculation:
resultType: float
expression: 'if({m1m1} > 20000, {m1m1}, 0)'
m1m1:
aggregate: SUM
arguments: [{ reference: { view: Sales, field: Amount } }]
nestedCalculation:
aggregate: AVG
dimensions: [{ reference: { dimension: City } }]

Here City is an existing stored dimension. The calculation first sums Amount per City, evaluates the IF for each City, then averages those results. At Country query grain, each Country gets its own average. Change the outer aggregate to SUM to sum those results.

New nested operands receive readable names such as m1m1. Existing m1 names remain valid and are preserved when editing. Names do not navigate into other calculations. Each calculation owns its parameters. Reductions support one ordinary stored dimension, or the existing Time Axis settings, and require Business Questions to be enabled.

Within one IF, local aggregates cannot be mixed with embedded calculations or stored-measure references. Wrap each local aggregate in a calculation, or save it as a measure and reference it. To nest reductions, put the inner reduction inside a calculation operand. Import rejects the engine’s unsupported direct reduction-within-reduction shape.

This extends fileVersion: 3; older readers may reject it.

A layer that contains data actions does not support embedded calculations or qualified operand names. Validation reports this combination as an error.