MCP tool reference

Tools

Tool	Scopes	What it does
astrato_management_directory_list_users	admin:read	List the tenant’s users for an administrator, each row carrying why it cannot be changed where that applies.
astrato_management_license_list_teams	admin:read	List the tenant’s licence teams, whose ids a status or team change has to be aimed at.
astrato_management_directory_update_user	admin:write	Change one user’s role, sign-in status or licence team, reporting which of those writes landed.
astrato_workspace_list_collections	workspace:read	List collections visible to the current user. Collections are workspace lenses over dashboards.
astrato_workspace_list_canvas_dashboards	workspace:read	List visible Canvas dashboards in bounded upstream pages, optionally through one collection lens.
astrato_workspace_update_collection	workspace:write	Update one collection’s name and description.
astrato_workspace_delete_collection	workspace:write	Delete one collection after explicit user confirmation.
astrato_dashboard_canvas_update	workspace:write	Update one Canvas dashboard’s name and description.
astrato_dashboard_canvas_prepare_deletion	workspace:write	Return the users currently affected by removing one Canvas dashboard and a five-minute, one-time preparation token. Show this impact before asking for confirmation.
astrato_dashboard_canvas_delete	workspace:write	Consume the matching preparation token, recheck the affected users, and move the Canvas dashboard to Removed when the impact is unchanged.
astrato_workspace_set_canvas_dashboard_favourite	workspace:write	Add or remove one Canvas dashboard from the current user’s Starred view.
astrato_workspace_set_canvas_dashboard_collection	workspace:write	Add or remove one Canvas dashboard from one collection.
astrato_data_create_connection	workspace:write	Create from non-secret metadata, returning a short-lived browser action when credentials are required.
astrato_data_get_secure_action_status	workspace:write	Read pending, completed or failed state and a credential-free receipt for the initiating user.
astrato_data_prepare_import	workspace:write	Check that a data connection allows writes and return a 15-minute upload URL and import id for one CSV file, up to 10 MB and 100,000 rows.
astrato_data_import_csv	workspace:write; sl:write to add to a layer	Create a table from an uploaded CSV by import id, or from up to 256 KB of inline CSV text, with the delimiter and column types inferred. Refused for an existing table name.
astrato_data_list_connections	sl:read	List the tenant data connections a semantic layer can bind to, with validity and the revision later calls require.
astrato_data_describe_connection_drivers	sl:read	Return the driver descriptors that define the flow: authentication methods, settings fields, catalog levels and their vendor labels.
astrato_data_prepare_connection	workspace:write	Prepare non-secret metadata and return a preparation ID and revision.
astrato_data_browse_connection_catalog	sl:read	List one catalog level – databases, schemas, tables with type (and row count where available), or a table’s columns – for a preparation or a saved connection, paged by offset and limit.
astrato_data_apply_connection	workspace:write	Open a bound secure form for create/update, or commit rename, source selection and deletion; retest reports stored validity.
astrato_data_list_dynamic_connection_settings	workspace:write	Read safe per-user settings, validity and the mapping revision of a dynamic connection.
astrato_data_apply_dynamic_connection_settings	workspace:write	Open a bound secure form to add or update per-user settings, or delete selected mappings directly.
astrato_get_context	sl:read	Server, permission, and default-layer context. Call this first for structural workflows.
astrato_semantic_layer_list	sl:read	List semantic layers with their semanticLayerId in pages of up to 50, most recently updated first. Pass name to find layers whose name contains every given word (best matches first), datasourceId for one datasource, or semanticLayerId alone to name one layer. Follow pagination.nextOffset while hasMore is true. Each row carries lastCheck, the layer’s last kept check.
astrato_data_list_sources	sl:read	List the datasources a new semantic layer can bind to, without returning connection settings.
astrato_semantic_layer_create	sl:write	Create an empty, unpublished semantic layer on one datasource and return its actual name and semanticLayerId.
astrato_semantic_layer_update	sl:write	Rename a semantic layer or change its description, in Astrato and in its draft in one call, and return the name Astrato keeps. Publishes nothing.
astrato_semantic_layer_set_visibility	sl:write	Turn “Visible to everyone” on or off for one layer, as the editor’s Members panel does; named user, group and role grants stay. Astrato checks the caller may manage access. Publishes nothing.
astrato_semantic_layer_get_summary	sl:read	The layer’s name (summary.name), compact counts, and exact revision and publication state. Set includeSnapshot: true only to attach the complete V3 JSON snapshot for a bulk read. A layer published outside this editor is judged by the model the engine serves (publicationSource: engine, publishedRevision: 0); never_published means the engine holds no model. Also returns lastCheck.
astrato_semantic_layer_get_details	sl:read	One page of views, fields, joins, or items (cursor + limit, max 50).
astrato_semantic_layer_search	sl:read	Search views, fields, joins, items, and functions.
astrato_semantic_layer_search_source_catalog	sl:read	Search the authorized physical-source catalog and return exact schema, table, and column identifiers.
astrato_semantic_layer_refresh_source_catalog	sl:read	Refresh loaded source metadata or one schema/table branch without discovering unrelated branches.
astrato_semantic_layer_validate	sl:read	Run shared semantic validation, including datasource aggregation support when live capability discovery succeeds.
astrato_semantic_layer_search_fields	sl:read	Ranked fuzzy field matches by business name. The prepare tools use this matcher internally, so skip it when a prepare call already resolves the request.
astrato_semantic_layer_find_unused	sl:read	Measures, dimensions and fields that no workbook or published app uses, plus items workbooks and apps name that the layer no longer has. Owners and administrators only; the first call on a layer reads every workbook on it.
astrato_semantic_layer_plan_authoring_batch	sl:read	Resolve several measure, dimension and business-question intents together, reuse exact existing use cases, and return one consolidated ambiguity list.
astrato_semantic_layer_prepare_measure_change	sl:read	Resolve one measure change; optionally compact repeated metadata or return current-draft engine suggestions and statement-only compiled SQL.
astrato_semantic_layer_prepare_dimension_change	sl:read	Resolve one dimension change; optionally return current-draft engine suggestions.
astrato_semantic_layer_prepare_view_change	sl:read	Resolve existing views and physical-source concepts for typed view and field authoring.
astrato_semantic_layer_export_ossie	sl:read	Export the exact current validated draft as Apache Ossie YAML without publishing. Returns portability diagnostics and a resource link.
astrato_semantic_layer_export_snowflake_semantic_view	sl:read	Generate CREATE SEMANTIC VIEW SQL from the exact current draft of a Snowflake-backed layer. Nothing runs in Snowflake. Every item Snowflake cannot express is listed under pending. Only a call with finalize: true returns the script, as statement and a .sql resource link.
astrato_semantic_layer_list_snowflake_views	sl:read	Discover Snowflake semantic views on a datasource.
astrato_semantic_layer_preview_snowflake_view_import	sl:read	Convert a Snowflake view without touching the draft.
astrato_semantic_layer_get_edit_session_status	sl:write	Report whether a session is still based on the current draft revision.
astrato_semantic_layer_preview_edit_session	sl:write	Preview pending changes and validation before committing.
astrato_semantic_layer_check_source_schema	sl:write	Check the database for schema drift; never publishes. fresh: false reads the stored result and lastCheck without checking.
astrato_semantic_layer_apply_source_schema_fix	sl:write	Apply one revision-bound typed fix returned by the latest source check; never publishes.
astrato_semantic_layer_begin_edit_session	sl:write	Open an edit session pinned to the current draft revision.
astrato_semantic_layer_apply_edit	sl:write	Apply one structured edit. Changes remain in the session until commit.
astrato_semantic_layer_apply_measure_change	sl:write	Create, replace, patch, rename, or delete one measure atomically: validate and commit in one call.
astrato_semantic_layer_apply_dimension_change	sl:write	Create, replace, rename, or delete one field, bucket, drilldown, or mapping dimension atomically. A mapping stores ordered rules — a filter plus the value its rows return — and its SQL is generated only for the engine.
astrato_semantic_layer_apply_view_change	sl:write	Atomically add, copy, edit, rename, or delete views and their fields without publishing.
astrato_semantic_layer_commit_authoring_batch	sl:write	Validate several planned measure, dimension and business-question intents and commit them in at most one revision, with an item receipt. A question may follow up another the same batch creates.
astrato_semantic_layer_rollback_edit_session	sl:write	Discard the session and its pending changes.
astrato_semantic_layer_commit_edit_session	sl:write	Commit the session as a new draft revision. Auto-rebases non-overlapping changes.
astrato_semantic_layer_create_version	sl:version	Create a named version of the current draft head. It has no expected-revision guard.
astrato_semantic_layer_import_snowflake_view	sl:write, sl:version	Apply a previewed Snowflake import atomically.
astrato_semantic_layer_unlink_import_source	sl:write	Detach a draft from a Snowflake semantic view or Databricks metric view it was imported from. Every imported table, field, join, dimension and measure stays; only the record of its source is dropped. Takes source (DATABASE.SCHEMA.NAME, optional when one view is linked). Publishes nothing.
astrato_semantic_layer_publish	sl:write	Publish one confirmed draft revision to the engine. Requires expectedRevision. Then rates the joins it added or changed and returns them under joinQuality; this never blocks or fails the publish.
astrato_semantic_layer_list_questions	sl:read	List stored business questions. See the Business questions guide.
astrato_semantic_layer_get_question	sl:read	Read one complete canonical stored question.
astrato_semantic_layer_suggest_joins	sl:read	List the join suggestions the editor shows, best first, each with its confidence and the exact join to create.
astrato_semantic_layer_check_join_quality	sl:read	Rate each draft join with the engine’s join-quality check: rating, findings with a recommended fix, and counts, errors and warnings first. Queries your data source; follow nextOffset. A join it can rate only after publishing is awaitingPublish. See join quality.
astrato_semantic_layer_suggest_questions	sl:read	Generate unsaved proposals and explicit rejections for unsupported query shapes. Supported period-over-period suggestions are stored with a Time Axis, and the rest are rejected with the reason; a rejection waiting only on a measure names it in needsMeasure.
astrato_semantic_layer_prepare_question_change	sl:read	Read one current target and the reusable dimensions and measures available for a revision-bound change.
astrato_semantic_layer_apply_question_change	sl:write	Atomically create, replace, rename, or delete one stored question without publishing.
astrato_semantic_layer_create_next_questions	sl:write	Create the next business questions for a stored question, linked as its follow-ups: the drivers of its KPI, or related questions the engine suggests asking next. See Next business questions.
astrato_semantic_layer_list_data_actions	sl:read	List the data actions a layer registers: writable tables and stored procedures with their targets and signature metadata, and the layer’s writeback mode. Appears only where the data actions feature is enabled.
astrato_semantic_layer_get_data_action	sl:read	Read one data action: the view, operations and fields a table registers, or the procedure signature the connection reported, and what the layer no longer holds.
astrato_semantic_layer_prepare_data_action_change	sl:read	Read one current data action, the layer’s views, fields, dimensions, measures and parameters, and, for a stored procedure, the connection’s procedure catalog. Writes nothing.
astrato_semantic_layer_apply_data_action_change	sl:write	Atomically create, replace, update, rename, or delete one data action. A procedure’s signature is read from the connection, never typed. Registers a write and runs none.
astrato_semantic_layer_run_data_action	data:query and sl:write	Run one published data action, a write to the data source, with named parameter values. Without confirm it returns a preview and runs nothing. The engine applies the caller’s own data permissions. Appears only where the data actions feature is enabled.
astrato_semantic_layer_set_writeback_mode	sl:write	Store the draft workflow policy explicitly; optionally reject a stale draft revision. Publishes nothing.
astrato_semantic_layer_execute_question	data:query	Compile and execute a stored question against the published semantic layer, a page at a time via limit and offset.
astrato_semantic_layer_list_datasets	sl:read	List datasets: named collections of existing dimensions and measures, with categories and member counts.
astrato_semantic_layer_get_dataset	sl:read	Read one dataset, its members in display order, and any that are no longer in the layer.
astrato_semantic_layer_prepare_dataset_change	sl:read	Read one current dataset and the dimensions and measures available to it. Writes nothing.
astrato_semantic_layer_apply_dataset_change	sl:write	Atomically create, replace, update members of, rename, or delete one dataset. Filters set in the editor are kept; this tool cannot author them.
astrato_semantic_layer_list_set_filters	sl:read	List stored set and regular filters with their type, a set filter’s target, and the questions that use them.
astrato_semantic_layer_get_set_filter	sl:read	Read one stored filter: a set filter’s target and branches or a regular filter’s conditions, and the questions that use it.
astrato_semantic_layer_prepare_set_filter_change	sl:read	Read one current stored filter and what is available to it. Writes nothing.
astrato_semantic_layer_apply_set_filter_change	sl:write	Atomically create, replace, update, rename, or delete one set or regular filter. Renaming updates the questions that use it; deleting copies it into them. A set that tests a measure the published layer cannot break down by its target is refused and nothing is written, since the set would test that measure as 0 or empty; a measure the published layer could not analyse does not block and is listed under measureBreakdownUnassessed.
astrato_data_prepare_query	data:query	List what the published layer can be queried for, by tier: stored dimensions and calculations by default, raw view fields with scope: "all". Reports how many raw fields a semantic page withheld, and the aggregation names at least one of them accepts — check the scope: "all" block for the chosen field’s data type before selecting one.
astrato_data_execute_query	data:query	Run a caller-defined query against the published layer and return columns and rows in engine order. Takes values for the parameters a selected calculation declares.

Both query tools require data:query. It is one of the default OAuth scopes the MCP resource advertises, so a client that connects with the advertised scopes, or names none, can query data from its first authorization; a grant that leaves it out cannot. PAT clients receive this capability when the server authenticates the PAT, so no OAuth login or additional scope configuration is needed. Internal Nash also receives it explicitly. Every query still checks access to the semantic layer.

For a connection made before data:query was a default, or one that left it out, adding it requires a new authorization and consent; refreshing an existing token preserves its original scopes. A dynamically registered client whose original registration omitted data:query must register again before requesting it. In clients that manage registration automatically, remove and reconnect the Nash MCP connection.

astrato_data_execute_query accepts a canonical Business Question in query, with at most twenty dimensions and measures and at least one of either. measures may be empty or omitted when the question lists dimension values. It does not accept the old selections, flat filters or orders request. Use BQ filters, resultFilters, orderBy and defaults.topN; keep parameters, limit, offset and queryTimeout outside query. See Business questions for examples.

Since contract 5.0.0, a question’s dimensions and measures are ordered lists, and a saved question keeps the order it was sent in. That order is the default column order, a moving calculation moves along the first dimension, and a row comparison partitions by the last. Each entry may carry a key, which orderBy, output, resultFilters, period comparisons and advanced calculations use to refer to it; a list keys every entry or none, and only a keyed entry may carry a period axis, a comparison, a formula or an advanced calculation. A replace that only reorders selections is a change, and is saved.

Earlier contracts stored selections as name-keyed maps, which came back shortest key first. A map is still accepted on input and read as the keyed list it names, in the order it is written. Every tool that returns a definition returns lists. Use astrato_data_prepare_query with scope: "questions" to discover stored BQ definitions with data:query access alone. Oversized definitions return an entry with id and definitionOmitted: "size"; execute that ID with astrato_semantic_layer_execute_question without requesting structural access. A question that groups by a drill-down dimension also returns drillLevels: for each such dimension selection, the levels it can group by. Execute it with parameters.drillLevels set to one of them — for example { "Breakdown": { "dimension": "Channel" } } — to answer “sales by channel” from a general sales question. Without it the first level is used. Field catalogue entries carry canonical reference objects. Result pages are bounded by serialized size as well as row count. When even the smallest complete one-row result cannot fit, the tool refuses the query and directs you to increase responseBudgetBytes within the cap or select fewer columns. A successful response includes statement when the semantic engine reports the SQL and it fits. omittedMetadata.statement is true only when a reported statement is removed to fit the response budget; it remains false when the engine supplies no statement.

To see the SQL before anything runs, call astrato_data_execute_query or astrato_semantic_layer_execute_question with the same arguments plus dryRun: true. The query is checked and compiled exactly as it would be for execution, but nothing reaches your warehouse. The result has dryRun: true, the SQL in statement, the result columns and publishedRevision. In the parsed tool result these are under data for astrato_data_execute_query, and under data.data for astrato_semantic_layer_execute_question, which keeps the question’s identity in data. A dry run needs the same data:query scope as execution. When an agent shows you SQL, it should be one of these statements, never one it wrote itself.

To see the SQL of a query while it runs, send a progress token with the execution. Once the query is compiled, and before your warehouse is called, the tool sends a progress notification whose message is SQL to run: followed by a line break and the statement. It is compiled from the same published revision the execution then uses. A query whose SQL cannot be compiled still runs, without that notification.

{
  "semanticLayerId": "7c0d6c5e-5d0b-4b63-9a55-2f2b1c1d0e42",
  "id": "Average Selling Price by Product",
  "limit": 100,
  "dryRun": true
}

When a datasource advertises LISTAGG or VALUE_LIST, astrato_data_prepare_query offers it for compatible raw fields. Use it in a canonical aggregate operand in query.local.measures; astrato_data_execute_query supplies a comma followed by a space as the list delimiter. Send distinct: true only when the prepared capability advertises it.

astrato_data_prepare_query offers an item only where the draft and the engine’s published model agree on it: the draft says what exists, the engine says what it can answer. An item added since the last publish, or whose query-relevant definition has changed since, is therefore listed under unavailable with a reason rather than offered, and one deleted in the draft is not listed at all — so a measure whose formula you have just changed stops being queryable until you publish it. A metadata-only edit — label, description, synonyms, number format — does not change what the engine computes and leaves the item queryable. The published side is read from the engine itself, so a layer published in Astrato, copied by Nash, or published from another editor instance is queryable here exactly as Data Explorer shows it, whether or not this editor ever published it.

Pass the current BQ selection as query to astrato_data_prepare_query, with any execution parameters, to obtain compiler context before execution. Omit query or pass {} for starting view states; that page lists stored items without candidate analysis, so it holds up to limit entries. Pass analyzeCandidates: true to analyze each stored item as if selected alone. Once the selection holds something, stored entries carry candidate analysis for the items that fit the page; raw fields carry the current view state and require an explicitly authored aggregate. Prepare again as the selection grows. Cursor continuations require the same selection, parameters, analyzeCandidates setting, and published catalog content. If any of these changes, prepare again without the cursor. Preparation also accepts filters, parameter overrides, and local definitions before any output is selected; current and candidate analysis retain that context. Execution still requires a selection.

Example: sales by tag

For a layer with a governed Sales measure and a Tag dimension, follow this sequence. Use the exact references returned by your layer’s catalog in place of these example names.

1. Call astrato_data_prepare_query with semanticLayerId, query: {} and analyzeCandidates: true. Review the starting context and the candidate analysis for Sales.

2. Select the measure and prepare again with query: { "measures": [{ "key": "sales", "reference": { "measure": "Sales" } }] }. Choose a breakdown using the compiler context returned for this measure.

3. Add Tag and call astrato_data_prepare_query with the complete query:

   {
     "measures": [{ "key": "sales", "reference": { "measure": "Sales" } }],
     "dimensions": [{ "key": "tag", "reference": { "dimension": "Tag" } }]
   }

4. Review the updated diagnostics, then pass that same query and semanticLayerId to astrato_data_execute_query. Keep any filters, parameter overrides and local definitions identical between preparation and execution. A queryAnalysisRejected refusal must be resolved before execution; unavailable analysis does not certify the breakdown.

Many-to-many groups can overlap: one sale may belong to several tags. Do not sum tag rows into an overall total without checking the measure’s meaning. Fanout and relation-dimensionality reduction are separate authored measure settings; preparation never enables either automatically.

papillon lists eligible leading views and a unique leading grain when one exists. These candidates are distinct from the committed roots in projection.grains. Projection reasons explain guarded sources; their absence does not certify complete formula attribution. A NULL dimension row alone does not identify untagged data.

Projected sources with postFilterMeasureIndex belong to the resolved hidden aggregate in projection.postFilterMeasures, rather than to a selected item in effectiveItems.

Execution returns analysis for its exact query alongside rows. Analysis can be unavailable or omitted to fit the response budget; check the reported reason or omittedMetadata.queryAnalysis. queryAnalysisRejected reports an execution policy refusal while preserving available typed compiler context. It is distinct from missing or omitted analysis. Besides associative filters that cannot be applied, it refuses filters that cannot reach a measure’s rows.

When the analysis carries the warning nrtd_measure_cannot_breakdown, for example [Order Value] cannot be broken down by [Ship Mode], astrato_data_execute_query and astrato_semantic_layer_execute_question refuse the query, with or without dryRun, and run nothing. Run anyway, that measure would read 0 or empty under every value of the dimension, with its whole value in a row where the dimension is empty. The error quotes the compiler’s verdict and the joins it suggests reviewing. It always carries queryAnalysisRejected; the full queryAnalysis is included only when it fits the response budget, and otherwise queryAnalysisUnavailable says it was omitted. astrato_data_prepare_query reports the same warning in queryAnalysis.warnings before you execute. To answer, do one of the following:

• Send the query without that dimension to get the measure’s total, or without that measure to break down the other measures.
• Group the measure by a field of its own view. A COUNT with distinct: true of a key can be broken down.
• If a join is missing or its cardinality is wrong, fix it in the layer and publish. astrato_semantic_layer_check_join_quality checks joins against the data.

Business-question execution outside MCP is unchanged and still returns those rows.

A resultNotices entry flags a measure that is zero or empty in every returned row. That can be the answer, but an empty or unloaded source, a filter on values the data does not hold, or a measure filter on a field the measure’s view does not reach returns the same, so check it, for example against the same measure without its filter, before reporting it. The entry is not added for a measure that the query’s own resultFilters require to equal 0 or be empty, as long as the filter combines its conditions with AND, or for a 0 from an unfiltered MIN, MAX or AVG of a single field, which SQL returns as empty rather than 0 over no rows. A MIN, MAX or AVG of a conditional expression such as if(…, 1, 0) is still flagged, because it reads 0 when its condition never matches. When totalRecords exceeds the rows on the page, the entry says that it judged one page.

When a query with no filters returns no rows, or only zero or empty measures, the entry also says which view may be empty and names up to three others that could hold the same records: views that share a word in their name, or that have every field the query read. Query those before reporting that there is no data.

astrato_semantic_layer_check_source_schema can create a draft revision when the database confirms that a referenced object is missing or has been restored. Datatype changes and likely renames based on casing or separators remain suggestions until the fix is confirmed. A fresh check is kept as the layer’s last check, which the semantic layer list shows beside the layer’s name; fresh: false reads only and keeps nothing. See Semantic layer issues and Find a semantic layer.

Contract 8.31.0 returns that last check as lastCheck on each row of astrato_semantic_layer_list, on astrato_semantic_layer_get_summary, and on astrato_semantic_layer_check_source_schema with fresh: false, so an agent can tell which layers need attention, and when each was last checked, without running a check:

{
  "checkedAt": "2026-10-28T07:00:00.000Z",
  "checkedBy": { "userId": "…", "name": "Sam Lee" },
  "current": true,
  "tone": "error",
  "label": "1 missing, 2 errors",
  "errorCount": 2,
  "warningCount": 0
}

tone is ok, warning or error, and label is the mark the list shows, such as Healthy. errorCount and warningCount count the model’s own issues; missing tables and fields show only in tone and label. checkedBy is null where Astrato cannot name who ran the check. current is false once the draft has changed since the check, so its result no longer applies. lastCheck is null for a layer never checked, and is left out only where the kept check could not be read. It says that something needs attention, not what: run a fresh check, or open the layer’s Issues panel, for the findings. Anyone who can read a layer can read its lastCheck.

Source discovery, view preparation, and view application reuse a progressive informationSchemaUri. Pass the returned URI through the same workflow so already loaded catalog branches are not fetched again. This client-scoped temporary resource expires after ten minutes without use. Use astrato_semantic_layer_refresh_source_catalog only when current source metadata is required.

A connection’s table listing can leave out tables that exist. From contract 6.51.0, naming a schema and an exact table still works when the listing omits it: in astrato_semantic_layer_search_source_catalog, a prepare_view_change source query, an apply_view_change create or re-point, or astrato_semantic_layer_refresh_source_catalog, the server reads that one table’s columns directly. If they can be read, the call goes ahead and the table carries listed: false and no objectType; a view created on it stores no objectType, and its apply receipt carries sourceListed: false. If the database says the table does not exist, the call is refused as not found; if the read fails for another reason, such as access or a rate limit, it is refused as unverified with that reason. A name the listing holds in another casing is refused with the listed spelling and is not read, so send identifiers exactly. A named-table search returns resolvedTable with listed.

Responses that return informationSchemaUri add listingGaps when tables the layer reads are missing from a listing loaded in this context, with foundByName for those already read directly. This is information, not an error: absent from the listing does not mean absent from the database, and astrato_semantic_layer_check_source_schema is what says whether a table is missing. A refresh keeps a loaded table the new listing leaves out while it can still be read, and drops it once the database says it is gone; later calls with the same informationSchemaUri do not bring it back. A read that cannot confirm either way fails the refresh and keeps the table. Among search results with equal scores, an exact name comes first.

Use the returned column source exactly, including its case and spaces. Column datatypes use Astrato’s canonical names; unsupported source types are reported as unhandled. Missing display names fall back to the source identifier. A malformed column response reports an error rather than indicating that the table has no columns.

astrato_semantic_layer_prepare_view_change also returns the datasource’s nativeDataTypeOptions. A physical field may use nativeDataType only with the semantic dataType and sourceType declared by one of those options. Do not invent native types or apply them to inline or expression fields. The server rejects unsupported combinations for the current datasource; changing the semantic datatype clears an existing native override.

Most tools accept an optional semanticLayerId. When it is omitted, the server uses its configured default layer. The hosted server has no default layer, so pass semanticLayerId there; to find a layer by name, call astrato_semantic_layer_list with name.

A name search matches names that contain every word given, in any order, ignoring case; a word may be the start of a longer word. It reads up to 1,000 of the most recently updated layers. When the tenant has more, nameSearch.complete is false; use more specific words or pass datasourceId.

For a Custom SQL view, provide the statement and any parameter definitions but not result fields. The create-sql and update-sql inputs reject a fields property, so clients must omit it. Every SQL parameter needs a non-null, non-blank default; date defaults use the unambiguous YYYY-MM-DD format. The server validates the statement with the current parameter defaults and derives authoritative field names and datatypes from the datasource. Updating a Custom SQL statement repeats that introspection before committing; if a removed result field is referenced by a join, dimension, measure or filter, the update is rejected instead of leaving a broken model.

An authoring change is refused when it makes the item it changes invalid. A drill-through level, for example, must be a field or an ordinary field dimension, and a bucket or custom-group level is refused with every offending level listed. A change that breaks a different item is saved, because a draft may be repaired over several edits. Deleting a dimension that a stored question selects is one example. The response then carries publishBlockers, listing each broken item and why, and publishBlockersHint; a preview reports them the same way before anything is committed. Publishing refuses the layer until every blocker is fixed: change or remove the broken item, or restore what it depends on, such as recreating the deleted dimension.

Custom-group dimensions

When you author a custom-group (mapping) dimension, each rule is checked for missing references, invalid filter values, formula conditions and parameter defaults. Diagnostics identify the dimension and the affected rule, such as groups[0].filter.f1.arguments[1]. Fix the reported reference or value before retrying the change. Rules that cannot currently be converted for publication are also reported as errors.

Set each rule’s output and the optional default as a value with a compatible dataType. In the dimension’s property panel, Returns updates all output types. Incompatible values stay visible for repair. Choose Group name, Null, or (for everything else) Exclude from the dimension, which stores no default. The rest of the section stays disabled until a Base field is chosen. Clearing text stores an empty string; it does not remove the default. Boolean values use True/False. Dates use YYYY-MM-DD, times use HH:mm:ss (optional fractional seconds), and timestamps combine the date and time. Zoned temporal types require Z or an offset such as +12:00.

Publishing keeps the authored rules in your semantic layer and version history. Importing engine YAML containing generated SQL yields a custom SQL field and an ordinary field dimension; it does not recover the original rules. Unchanged published groups remain queryable; changing a rule or fallback requires publication before querying the new definition.

In the editor, open Issues to navigate to the affected dimension. Renaming a field or table updates both the group’s base binding and its rule references. Version compare shows the ordered rules, filters, parameter defaults and typed outputs, including the value for everything else.