Skip to content

Written for: For developers

MCP tool reference

119 min read · Updated 17 Nov 2026

Every generally available tool an external MCP client can call, with the scopes it needs and the arguments it takes. Tools says what each semantic layer, workspace and data tool does. Arguments by tool gives every tool’s arguments with their types, allowed values, limits, defaults and nested fields, including the Data App, access and App Builder tools that are described on their own pages.

Arguments by tool is read from each tool’s input schema. Your client reads the same schema from the server it is connected to with the MCP tools/list request, and that copy is the one the server enforces:

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }
  • Each entry in the result has the tool’s name, description, annotations and inputSchema, a JSON Schema whose required array names the arguments you must send. Most clients show this as the connection’s tool list.
  • A large schema shares its repeated parts under $defs. Follow each $ref to read them.
  • tools/list lists every tool the environment registers, whatever your scopes, so a data-only client holding data:query can read it although it cannot call astrato_get_context. A listed tool can still refuse a call for a missing scope; see MCP scopes and permissions.
  • A tool a feature flag disables is not listed, and an argument a feature gate controls is left out of the schema. The six data action tools (Private Preview) are listed only where the data actions feature is enabled for your workspace; ask your Astrato contact to enable it. A connector that was connected before it was enabled lists them only after you reconnect it.
  • Clients may cache the list. After a contract change, reconnect or refresh tool discovery.
  • MCP URL: https://app.astrato.io/mcp
  • Transport: remote Streamable HTTP
  • Authentication: OAuth for interactive clients, or an Astrato Personal Access Token (PAT)

Examples use https://app.astrato.io. If your organisation provides a private or custom deployment origin, replace the Astrato origin in the URLs. Client settings are in Configure an MCP client.

The tools use one product-shaped namespace:

  • astrato_data_* manages connections, sources, and governed data queries.
  • astrato_workspace_* discovers and organizes visible Astrato resources.
  • astrato_semantic_layer_* discovers and authors semantic models and their business questions.
  • astrato_dashboard_canvas_* manages Canvas dashboard lifecycle operations.
  • astrato_dashboard_freeform_* creates unpublished Data Apps and manages their metadata, hosting and lifecycle. Publish content through the CLI.
  • astrato_management_access_* manages direct grants over typed Astrato resources.
  • astrato_management_directory_* and astrato_management_license_* read the tenant’s users and licence teams, and change a user’s role, sign-in status and licence team.
  • astrato_app_builder_* edits and runs an app’s Builder document.
  • astrato_reporting_* discovers notification integrations and sends through them.
  • astrato_get_context reports the live tool contract, capabilities, permissions, authenticated Astrato identity, and routing context.

OAuth scopes control authority independently of these product capabilities.

The identity context includes the current user’s name, email, and tenant role from verified Astrato identity data. These values explain the session but never grant access; every operation is authorized again by its scope and owning Astrato service. Group memberships are not injected.

The gateway may expose fewer tools when a product capability is disabled for your environment. Always use live tool discovery rather than assuming that every documented tool is available.

astrato_get_context returns a capabilities array alongside the flat tools list. Each element carries exactly id, title, description and tools — the last being that capability’s tools that are registered on this connection.

There are fourteen identifiers, and the capabilities array keeps the order below. The flat tools list is in registration order, which is not alphabetical and does not follow the order below, so do not key on its order. The title is a product word that cannot be derived from the id, so copy it exactly rather than generating it:

id title Holds
core Nash context astrato_get_context alone, which needs sl:read
workspace Workspace The astrato_workspace_* tools
data Data The astrato_data_* tools
semantic-layer Semantic layer The astrato_semantic_layer_* tools
dashboard-canvas Workbooks Canvas update, prepare-deletion and delete
dashboard-freeform Data apps The freeform tools and all seven astrato_app_builder_*
management-access Access management The astrato_management_access_* tools
management-directory Directory …directory_list_users and …directory_update_user
management-licensing Licensing astrato_management_license_list_teams
reporting Reporting Two delivery tools externally, or none
management-reporting Reporting administration In-product Nash only
management-integrations Integration access management In-product Nash only
support AI Support In-product Nash only
admin-helper Admin helper In-product Nash only, read-only, needs admin:read

A capability id is not a tool-name prefix. astrato_workspace_set_canvas_dashboard_favourite and astrato_workspace_set_canvas_dashboard_collection sit under workspace rather than dashboard-canvas, and the seven astrato_app_builder_* tools sit under dashboard-freeform with no Builder capability of their own. A client that groups tools by string prefix will disagree with the server’s own grouping.

A capability with no registered tool is omitted entirely, not returned with an empty tools list. Read a missing id as “nothing from it is registered here”, never as “this capability does not exist”. A tool its feature flag disables is never registered, so a flag can take a whole capability with it: global.astrato-apps removes dashboard-freeform and management-access, global.nash.recurring removes reporting, management-reporting and management-integrations, and global.nash.support removes support. global.nash.app-builder is narrower — it removes the seven astrato_app_builder_* tools and leaves dashboard-freeform with its six freeform tools.

Four ids never appear for an external client at all. support is registered only for in-product Nash, although both its tools need no more than sl:read, so holding a scope is no promise of the capability. admin-helper is likewise registered only for in-product Nash, whatever scopes a client holds. The management-reporting and management-integrations tools are reserved for in-product Nash as well, and their scopes are not among the fourteen an external client can be granted. Externally, reporting holds astrato_reporting_list_integrations and astrato_reporting_send_slack_text or nothing: each is registered only where the workspace’s own integration access carries its scopes as well as your session. See Recurring Nash tasks.

Nash is the agent identity. Capabilities are the Astrato product operations Nash can use, while skills are optional workflow guidance for combining those operations; neither a capability nor a skill is a separate Nash agent.

The astrato_management_* area covers access control, the Astrato user directory and licensing, each with its own capability id; integration access and reporting administration sit there too, for in-product Nash only. Tenant settings, the group directory, identity policy, embedding, AI governance, tenant assets and exports join it only when executable, server-authorized tools exist. Reporting remains a separate capability because schedules and subscriptions are not uniformly administrator-only. Unimplemented roadmap capabilities are never advertised by MCP discovery.

These tools cover the usual path from a new semantic layer to a published Data App, once the layer has a source table: a new layer is empty, so add its tables and fields with astrato_semantic_layer_prepare_view_change and astrato_semantic_layer_apply_view_change before measures. Tools lists the semantic layer, workspace and data tools.

  • astrato_semantic_layer_create creates an empty, unpublished semantic layer on a datasource.
  • astrato_semantic_layer_apply_measure_change adds or changes a measure in the layer’s draft.
  • astrato_semantic_layer_preview_publish shows everything publishing would send, including other people’s changes. Show it to the user and publish only once they approve it.
  • astrato_semantic_layer_publish publishes the layer, so queries and Data Apps can use it. Pass the expectedRevision of the preview the user approved.
  • astrato_dashboard_freeform_create reserves an unpublished Data App. Publish its content with the CLI.

Reporting: when Astrato’s sender is available, astrato_reporting_list_integrations discovers permitted connections and destinations and astrato_reporting_send_slack_text sends text. For a webhook, use the returned destination ID webhook; never supply its URL as a tool argument. Discovery needs integrations:read, sending needs integrations:read and messages:send, and company user, group and destination permissions still apply.

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. A collection is a workspace lens over the workbooks and Data Apps it holds; membership never grants access.
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_pinboard_list workspace:read List the pinboards the caller can open.
astrato_pinboard_get workspace:read Read a board document and its revision.
astrato_pinboard_create workspace:write Create an empty personal or collection board.
astrato_pinboard_add_pin workspace:write Pin a stored business question to the end of a board.
astrato_pinboard_remove_pin workspace:write Remove a pin from a board and its layouts after explicit user confirmation.
astrato_pinboard_replace_document workspace:write Replace a whole board document. Use it to rename a board, reorder or resize pins, or change display settings.
astrato_pinboard_delete workspace:write Delete a board after explicit user confirmation.
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 stored document for a bulk read (current layers are V3; read fileVersion). 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_export_databricks_metric_view sl:read Feature-gated. Generate a CREATE VIEW … WITH METRICS LANGUAGE YAML statement from the exact current draft of a Databricks-backed layer. Nothing runs in Databricks. The table that reaches the most others through many-to-one joins becomes the source and the rest are joined under it; everything a metric view cannot carry is left out, listed under omitted with its reason and commented in the statement. Every call attaches the .sql file, which is the deliverable.
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_list_databricks_metric_views sl:read Feature-gated. Discover the metric views in the catalog of a Databricks datasource; a metric view is the Databricks counterpart of a Snowflake semantic view. Metadata discovery only: it imports nothing and changes no draft. Appears only where the Databricks metric views feature is enabled, and refuses a datasource that is not Databricks.
astrato_semantic_layer_preview_databricks_metric_view_import sl:read Feature-gated. Convert a Databricks metric view without touching the draft: its source table and joins become views and joins, its dimensions and measures become dimensions and measures. Returns counts, diagnostics, sourceHash, the layout profile and the revision that astrato_semantic_layer_import_databricks_metric_view requires. It refuses a draft on another datasource. Show the counts and diagnostics before importing.
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 dimension of any kind — field, bucket, drillthrough, mapping, periodAxis or sets — 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_import_databricks_metric_view sl:write, sl:version Feature-gated. Apply a previously previewed Databricks metric view to the draft. Import, table layout, draft revision and named version are one atomic operation. It refuses a draft whose revision or sourceHash has moved since the preview, a draft on another datasource, and diagnostics that were not accepted. It overwrites a non-empty draft only with replaceExisting: true, recording a manual version of the current revision first unless one already exists. It does not publish.
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_preview_publish sl:read Show what publishing would send, without publishing: a count of every change since the published revision by type, up to 60 of them by name with the revisions that made each and who made them, and the expectedRevision to publish. Show it to the user before asking to publish.
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_suggest_dimensions sl:read and data:query Suggest number bands, custom groups and Time Axes the current draft lacks, as definitions astrato_semantic_layer_apply_dimension_change accepts. It queries table values, sends capped field values to the AI model Nash uses, and stores nothing.
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. A period-over-period suggestion is built on a measure the layer defines, over a shared Time Axis. If the layer has measures and none computes the aggregate, it is rejected with the reason and needsMeasure; a layer with no measures yet gets the base measure with the suggestion.
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: by default its drivers, or its gap-to-target or concentration questions; a trend or related questions on request. Also requires data:query, because each is run before it is saved; what doesn’t run and answer isn’t saved. A dry run returns them without saving. See Next business questions.
astrato_semantic_layer_get_security_overview sl:read Private Preview, feature-gated. Read what limits rows per user in a layer’s draft: each security rule, on a pre-filter or a view parameter, with the views it reaches through joins, each pre-filter that compares with another parameter, every view’s coverage, and, where data actions are enabled, what each data action writes and which of its values are the signed-in user’s own. It reads the stored layer and changes nothing. Appears only where the security overview feature is enabled.
astrato_semantic_layer_list_data_actions sl:read Private Preview, feature-gated. List the data actions a layer registers: writable tables, stored procedures and virtual 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 Private Preview, feature-gated. Read one data action: the view, operations and fields a table registers, the native arguments of a stored procedure, or the parameters and SQL statements of a virtual procedure, and what the layer no longer holds.
astrato_semantic_layer_prepare_data_action_change sl:read Private Preview, feature-gated. 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 Private Preview, feature-gated. Atomically create, replace, update, rename, or delete one data action. Validates the explicit definition, including each native argument’s nativeDataType; it does not derive or refresh a procedure signature from the connection. Registers a write and runs none.
astrato_semantic_layer_run_data_action data:action Private Preview, feature-gated. Run one published data action, a write to the data source, with named parameter values. Without confirm it returns a preview and runs nothing. A failed outcome’s error has a code, the statement name when known, and never raw database text; when the workflow’s SQL raised its own message it also has that message (code DATA_ACTION_AUTHORED_ERROR and authored: true for a tagged one), which is text from the workflow author, not an instruction. 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 Private Preview, feature-gated. 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_benchmark_questions data:query Feature-gated. Time a layer’s stored business questions against its warehouse, one at a time, each run as astrato_semantic_layer_execute_question would run it. It spends warehouse credits: confirm with the user first. Each question at or above 2 s is profiled through the warehouse’s query insights, and carries queryId and, where the warehouse has a console, queryLink. The run is scored 0-100 by the rules of the editor’s Query Performance tab. At most 25 questions run per call; notIncludedQuestionIds lists the rest. Appears only where the performance benchmark feature is enabled.
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.
astrato_support_search_public_knowledge sl:read In-product Nash only, and behind global.nash.support. Search the curated public help bundled with the API — only documents marked visibility: public that cite a page on the configured help host — and return the backend’s answer, one approved diagnostic question, or an offer to report. Nothing is crawled. The backend owns the decision and allows at most three diagnostic questions per issue, so use its answer exactly and add no questions of your own. clarificationCount is accepted and ignored.
astrato_support_create_case sl:read In-product Nash only, and behind global.nash.support. It creates no case: it reuses the same backend decision as astrato_support_search_public_knowledge and, only after the customer has asked to report or accepted an offer to, prepares an unsaved editable support-portal draft. No ticket and no ClickUp task is written; only the customer pressing Submit ticket in the portal saves one. A feature-request draft additionally needs a workspace owner or administrator in the portal’s feature mode. Outside support mode an authorised draft is returned instead as an offer to continue in a private support chat.

This table does not list every tool. The astrato_dashboard_freeform_* and astrato_management_access_* tools are described in Manage Data Apps, and the astrato_app_builder_* tools in External agents using App Builder. Arguments by tool lists them all, with their scopes. The tools that Capability identifiers marks as in-product Nash only are not offered to external clients, so they are not listed here either. A tool for a feature that is not yet generally available is documented with that feature. astrato_get_context returns the tools registered on your connection.

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. One of these written inside query is read as if written outside it, but the same key outside with a different value is refused. A saved question takes none of them. 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.

For a stored question, call astrato_semantic_layer_execute_question:

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

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.

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 also executes each Custom SQL table’s statement once with its parameter defaults, which can cost warehouse time, and reports columns it no longer returns, type changes and new columns. A column-added finding’s fix adds that one column as a field. Otherwise it stays out, because a new column could be sensitive, with two exceptions: an update-sql statement change adds the columns it introduces, and on a table with no column fields it adds every column the statement returns. A statement that fails is a sql-check-failed finding on that table and does not stop the rest of the check. 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 update that leaves the statement and parameters unchanged keeps the fields as they are. A changed statement adds a field for each column it returns that the old statement did not. A column the old statement already returned, such as one that reached a SELECT * from the warehouse, stays out until astrato_semantic_layer_check_source_schema offers it and its fix is applied. If the old statement cannot be run, no new column is added.

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.

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. Select 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.

Each tool below lists every argument of its input schema, in schema order, as of tool contract 8.58.0. An entry gives the argument’s type, whether you must send it, the allowed values, limits and default where the schema sets them, and the schema’s own description. MCP contract changes lists what changed since.

  • A nested field is indented under the object that holds it. Under an array of objects, the indented fields are those of each item.
  • An object that takes one of several shapes names the field that chooses the shape, such as operation. A field that only some shapes have says which, and “required when” names the shapes that must send it.
  • Where an object has too many nested fields to list here, its entry names them. Read their types from the input schema.
  • An argument a feature controls says so. Where that feature is off, the schema leaves it out.

semanticLayerId is optional on most semantic layer tools because a server can have a default layer. The hosted server has none, so pass it there.

Workspace, Canvas dashboards and administration

Section titled “Workspace, Canvas dashboards and administration”

Takes no arguments.

  • offset (integer; optional; at least 0). Zero-based workbook offset. Start at 0.
  • limit (integer; optional; 1 to 100). Maximum workbooks to return, up to 100.
  • search (string; optional). Case-insensitive substring of the name or description. It is a literal match, not a fuzzy one: “Pac Man” does not find “Pacman”, and a phrase of your own words (“pivot export bug”) finds nothing. Search one distinctive word.
  • sort (string; optional; one of name, -name, updated, -updated, created, -created). Sort order. Only these values exist; anything else is refused. Default -updated.
  • collectionId (UUID string; optional). Only return workbooks visible through this collection. Omit for the complete visible catalog.
  • group (string; optional; one of all, drafts, published, starred, removed). Catalog group. Drafts means every dashboard holding a draft — including published ones with unpublished changes — not only unpublished ones. Removed means the soft-deleted dashboards, which is the only way to answer what the user deleted.
  • datasourceType (string; optional). Only return workbooks using this exact Astrato datasource type, such as snowflake.
  • starred (boolean; optional). Only return workbooks the current user has starred.
  • updatedFrom (string; optional). Only dashboards last touched on or after this date (YYYY-MM-DD) or ISO timestamp. Use it for “last month”, “this week”, “since Monday” instead of reading the whole catalog.
  • updatedTo (string; optional). Only dashboards last touched on or before this date (YYYY-MM-DD) or ISO timestamp. With updatedTo alone, use it for “not touched since”.
  • owner (string; optional). Only dashboards whose owner’s name contains this text, case-insensitively. The name search does not cover owners, so this is the way to find one person’s workbooks.
  • createdFrom (string; optional). Only dashboards created on or after this date or ISO timestamp.
  • createdTo (string; optional). Only dashboards created on or before this date or ISO timestamp.
  • inCollection (boolean; optional). True for dashboards in at least one collection; false for the ones in none.
  • hasVersionType (string; optional; one of draft, shared_draft, published, depublished, readonly). Only dashboards holding a version of this type. A shared version is shared_draft; the live one is published; depublished was live once; readonly is a snapshot.
  • usesSemanticLayerId (UUID string; optional). Only dashboards with a version built on this semantic layer.
  • id (UUID string; required). Exact collection id returned by astrato_workspace_list_collections.
  • name (string; required; at least 1 character). New display name.
  • description (string; required). New description. Use an empty string to clear it.
  • id (UUID string; required). Exact collection id returned by astrato_workspace_list_collections.

astrato_workspace_set_canvas_dashboard_favourite

Section titled “astrato_workspace_set_canvas_dashboard_favourite”
  • canvasDashboardId (UUID string; required). Exact workbook id returned by astrato_workspace_list_canvas_dashboards.
  • favourite (boolean; required). True to star the dashboard; false to remove it from Starred.

astrato_workspace_set_canvas_dashboard_collection

Section titled “astrato_workspace_set_canvas_dashboard_collection”
  • canvasDashboardId (UUID string; required). Exact workbook id returned by astrato_workspace_list_canvas_dashboards.
  • collectionId (UUID string; required). Exact collection id returned by astrato_workspace_list_collections.
  • included (boolean; required). True to add the dashboard; false to remove it from the collection.

Takes no arguments. Pinboard tools are available only where the pinboard feature is on. Each entry returns canEdit.

A personal board belongs to its creator alone. Reading a collection board needs access to the collection. Creating or changing one needs workspace:write and edit access to the collection.

  • pinboardId (string; optional). Board id from astrato_pinboard_list. Omit for the caller’s default board.
  • name (string; required). Board name.
  • collectionId (UUID string; optional). Collection to create the board in, which needs edit access. Omit for a personal board.
  • semanticLayerId (string; required). Layer holding the question.
  • businessQuestion (string; required). Stored business question id. It must exist and be readable.
  • pinboardId (string; optional). Omit for the caller’s default board.
  • slug (string; required). Pin slug, a key of the document pins.
  • pinboardId (string; optional). Omit for the caller’s default board.
  • document (object; required). The complete document from astrato_pinboard_get, edited. Pins left out are removed, and a question the board did not already have must exist and be readable.
  • expectedRevision (integer; required). The revision astrato_pinboard_get returned. If the board has changed since, the call is refused with a conflict: read it again and reapply the change.
  • pinboardId (string; optional). Omit for the caller’s default board.
  • pinboardId (string; required). Board id from astrato_pinboard_list.
  • offset (integer; optional; at least 0). Zero-based user offset. Start at 0.
  • limit (integer; optional; 1 to 200). Maximum users to return, up to 200.
  • search (string; optional). Case-insensitive name or email match, applied to the page that was read.

Takes no arguments.

  • userId (UUID string; required). Exact Astrato user id from astrato_management_directory_list_users. Not an email address.
  • role (string; optional; one of administrator, creator, designer, viewer). The user’s new role. The owner’s role cannot be assigned.
  • active (boolean; optional). Whether the user may sign in. Disabling keeps the account and its content.
  • teamId (UUID string; optional). Licence team to move the user into, from astrato_management_license_list_teams.
  • canvasDashboardId (UUID string; required). Exact workbook id returned by astrato_workspace_list_canvas_dashboards.
  • name (string; required; at least 1 character). New display name.
  • description (string; required). New description. Use an empty string to clear it.
  • canvasDashboardId (UUID string; required). Exact workbook id returned by astrato_workspace_list_canvas_dashboards.
  • canvasDashboardId (UUID string; required). Exact workbook id returned by astrato_workspace_list_canvas_dashboards.
  • preparationToken (UUID string; required). Opaque one-time token returned by the immediately preceding preparation call.
  • expectedAffectedUserIds (array of string; required). Exact affected user ids returned by the immediately preceding astrato_dashboard_canvas_prepare_deletion call. Confirm that impact with the user before deleting.
  • name (string; required; 1 to 200 characters). Display name for the new data connection.
  • driverName (string; required; 1 to 80 characters). Astrato datasource driver, such as snowflake, postgres, databricks, or google_bigquery.
  • authentication (string; required; one of none, username-password, username-private-key, token, service-account-json). The server-owned secure input profile. Never put a password, token, private key, service-account JSON, or other credential in settings or chat.
  • username (string; optional; 1 to 256 characters). Optional non-secret login name already supplied by the user. Preserve it here so the secure form asks only for the secret.
  • authType (string; optional; one of password, oauth, jwt, jwt_with_user_settings). Optional Astrato datasource authentication type. Private-key and service-account profiles use jwt by default; supported dynamic connections preserve jwt_with_user_settings and enroll their creating user.
  • authInfo (string; optional; at most 1000 characters). Optional non-secret reference to an Astrato-managed OAuth connection. Never provide an OAuth token.
  • settings (map of string to any; required). Non-secret datasource settings only. Keys that look like passwords, tokens, private keys, credentials, or access keys are rejected.
  • actionId (UUID string; required). Secure action id returned by astrato_data_create_connection.

Takes no arguments.

astrato_data_list_dynamic_connection_settings

Section titled “astrato_data_list_dynamic_connection_settings”
  • connectionId (UUID string; required)

astrato_data_apply_dynamic_connection_settings

Section titled “astrato_data_apply_dynamic_connection_settings”
  • connectionId (UUID string; required)
  • expectedRevision (string; required; 1 to 200 characters)
  • change (object (2 shapes); required; shape chosen by operation: upsert, delete)
    • operation (string; required; one of upsert, delete)
    • users (array of object; required when operation is upsert; 1 to 100 items)
      • userId (UUID string; required)
      • settings (object; required)
        • projectID (string; optional; at most 2000 characters)
        • datasetID (string; optional; at most 2000 characters). Optional BigQuery dataset; if supplied it must match sharedSettings.datasetID from the list. All users share that dataset.
        • host (string; optional; at most 2000 characters)
        • port (string; optional; at most 20 characters)
        • user (string; optional; at most 2000 characters)
    • userIds (array of UUID string; required when operation is delete; 1 to 100 items)
  • driverId (string; optional; at least 1 character). Limit the result to one driver.
  • driverId (string; required; at least 1 character). Driver id from astrato_data_describe_connection_drivers, e.g. “postgres”, “snowflake”, “demo”.
  • authMethod (string; optional; at least 1 character). One of the driver descriptor authMethods. Optional when the driver accepts only one.
  • settings (map of string to any; optional; default {}). Non-secret settings only. Credentials are rejected. Apply returns an encrypted browser form to validate and save.
  • context (map of string to any; optional). Selectors that change what the catalog returns, e.g. Snowflake role and warehouse.
  • connectionId (UUID string; optional). Set when re-preparing an existing connection.
  • baselineRevision (integer; optional; at least 0). Required when connectionId is set: the revision field from astrato_data_list_connections or a prior read of this connection. Refused if the connection has changed since, so a stale edit cannot overwrite a concurrent one.
  • exitNode (object; optional). Listed only where Deployment Region authoring is enabled. Route this connection through a tenant egress profile. Only some drivers accept one; a prepare result lists the profiles available.
    • enabled (boolean; required)
    • profile (string; optional; at least 1 character). A profile name from a previous prepare result. Omit for the tenant default.
  • connectionId (UUID string; optional). A saved connection to browse.
  • preparationId (UUID string; optional). A preparation from astrato_data_prepare_connection.
  • level (string; required; one of database, schema, table, column). Which hierarchy level to list. The descriptor names what the driver calls it; column is below table.
  • database (string; optional; at least 1 character)
  • schema (string; optional; at least 1 character). Required when listing tables or columns.
  • table (string; optional; at least 1 character). Required when listing columns.
  • offset (integer; optional; at least 0). Zero-based item offset. Start at 0.
  • limit (integer; optional; 1 to 500). Maximum items to return, up to 500.
  • expectedRevision (integer; required; at least 0)
  • change (object (7 shapes); required; shape chosen by operation: create, update, configure, rename, select-source, retest, delete)
    • operation (string; required; one of create, update, configure, rename, select-source, retest, delete)
    • preparationId (UUID string; required when operation is create or update)
    • name (string; optional; 1 to 200 characters). Only when operation is create or configure.
    • source (object; required when operation is select-source). Only when operation is create or select-source.
      • database (string; optional; at least 1 character)
      • schema (string; optional; at least 1 character)
    • context (map of string to string; optional). Only when operation is create or update.
    • connectionId (UUID string; required when operation is update, configure, rename, select-source, retest or delete)
    • context (object; optional). Only when operation is configure.
      • role (string; optional; at most 1000 characters)
      • warehouse (string; optional; at most 1000 characters)
    • source (object; optional). Only when operation is configure.
      • database (string; optional; 1 to 1000 characters)
      • schema (string; optional; at most 1000 characters)
    • exitNode (object; optional). Only when operation is configure.
      • enabled (boolean; required)
      • profile (string; optional; 1 to 1000 characters)
    • newName (string; required when operation is rename; 1 to 200 characters)
  • datasourceId (UUID string; optional). The data connection to import into, from astrato_data_list_connections. It must allow writes.
  • semanticLayerId (UUID string; optional). Import into this semantic layer’s own data connection instead of naming one. In a layer conversation, pass the current layer: no connection lookup is needed.
  • sha256 (string; optional; matches ^[0-9a-fA-F]{64}$). Recommended when the file is on disk: its SHA-256 in hex. The upload URL then accepts only that file, so nobody else who sees the URL can upload a different one first.
  • datasourceId (UUID string; optional). The data connection to import into, from astrato_data_list_connections. It must allow writes.
  • semanticLayerId (UUID string; optional). Import into this semantic layer’s own data connection instead of naming one. In a layer conversation, pass the current layer: no connection lookup is needed.
  • importId (string; optional; 1 to 100 characters). The importId from astrato_data_prepare_import, after the file was uploaded to its upload.url, or the importId of a file attached in the Nash panel.
  • content (string; optional; 1 to 262,144 characters). The CSV text itself, only for a small file (up to 256 KB) with no way to upload it. Anything larger goes through astrato_data_prepare_import.
  • fileName (string; optional; 1 to 255 characters). The original file name, used for the default table name. An upload through astrato_data_prepare_import does not keep it, so pass it to name the table after the file; without it or tableName the table is called upload. A file attached in the Nash panel keeps its name, so this is not needed for one.
  • tableName (string; optional; 1 to 255 characters). Name for the new table. Defaults to fileName without .csv, or upload when neither is given. An existing name is refused.
  • hasHeaders (boolean; optional). Whether the first row names the columns. Defaults to true.
  • addToLayer (boolean; optional). With semanticLayerId: also add the new table to that layer as a view over all its columns, as the editor upload does. Defaults to true; set false to only create the table.
  • columnTypes (map of string to string; optional). Optional overrides of the inferred column types, keyed by column name: boolean, date, float, int, string, time or timestamp.
  • detail (full or identity; optional). Omit it or use full for the complete Nash context. Use identity for a compact session guard containing the tool contract version, authenticated identity, connection mode and authorization summary. This is useful for clients with small inline tool-result limits. It deduplicates scopes and retains missing-scope tool and reconnect guidance. An optional identity value that cannot fit safely is null and named in identity.omittedFields; use full when that display value is needed.

Takes no arguments.

  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • draft (object; optional). Listed only where Deployment Region authoring is enabled. Opt in to an exact saved draft using revision and headToken from the layer read/save. Omit for published behavior. Prepare returns draft only when supported by this connection; draftUnavailable means the returned catalogue is published, so omit draft when executing it. Repeat the returned draft unchanged for preparation, dryRun, execution and pagination. A changed draft or lost execution capability requires preparing again; draft execution never falls back silently.
    • revision (integer; required; at least 0)
    • headToken (string; required; 1 to 1024 characters)
  • debug (boolean; optional). Capture a complete query replay bundle as a caller-scoped MCP resource. Includes the selected published or saved-draft semantic layer, compiler model, translated queries and full analysis; excludes request credentials and result rows. Read debugReplay.resourceUri with resources/read. Capture size or storage failures are explicit.
  • parameters (object; optional). Execution-only overrides. all is keyed by parameter name and reaches every selection and filter group that declares it; measures is keyed by the BQ measure selection key, then the declared parameter name; filters and resultFilters by parameter name; associativeFilters by branch name then parameter name; drillLevels by dimension selection key. Omitted values retain declared defaults. Never copy these values into a saved definition.
    • all (map of string to string or number or boolean; optional). Values by parameter name for every measure selection, filters and resultFilters group that declares the name; groups that do not declare it are left alone. The simplest way to set a window shared by several measures, and the only way to set a view parameter, including on a view reached through a join; a value bound to the user wins over it. A value under measures, filters or resultFilters for one selection or group wins over this one.
    • measures (map of string to map of string to string or number or boolean; optional)
    • filters (map of string to string or number or boolean; optional)
    • resultFilters (map of string to string or number or boolean; optional)
    • associativeFilters (map of string to map of string to string or number or boolean; optional)
    • drillLevels (map of string to object; optional). The level a drill-through dimension selection groups by, keyed by its selection key (the string index for an array of selections). The value is one of that selection’s drillLevels references, or the field it groups by. Omitted, the first level is used. Choose the level the user asked to break the answer down by: “sales by channel” on a question grouped by a drill-through with a Channel level executes that question with Channel.
  • search (string; optional; 1 to 200 characters). Ranked field match, the same matcher astrato_semantic_layer_search_fields uses; among equal scores an item named exactly as the search comes first. At most 200 characters. Omit to list from the start, which is what a layer small enough for one page wants.
  • limit (integer; optional; 1 to 300). Maximum entries per page. Default 300.
  • cursor (string; optional). Continuation from a previous nextCursor. Bound to the layer, both revisions, scope, search, query context and parameters. Repeat those inputs unchanged when continuing.
  • scope (string; optional; one of semantic, all, questions). Which tier to list. “semantic” (default) lists the stored dimensions and calculations — the governed layer, and where to answer from first. “all” adds the raw view fields behind them; use it only when no stored question or item expresses what the question needs. A semantic page reports how many raw fields it withheld, and under withheld.aggregations the aggregations those fields accept — a stored item reports none of its own, so that list is the only statement such a page makes of what the layer can aggregate by. It is pooled across the data types of the withheld fields, establishing that an aggregation exists here rather than that it applies to any particular field. A question about spread, variance or a median usually lives in that tier, such a calculation being rarely stored: widen the scope, check the aggregation against the capability block for the chosen field’s data type, then define it in query.local.measures. Conclude that the layer cannot express the concept only once that block rules it out.
  • analyzeCandidates (boolean; optional). Whether stored entries carry candidateAnalysis. Defaults to true once query selects something and false for an empty start, where a plain listing returns up to limit entries quickly. Pass true to analyze candidates from an empty selection, false to skip analysis while building a query.
  • query (object; optional). Current partial or complete BQ selection. limit and scope are arguments beside query, never inside it. Omit or pass {} to start with compiler view states for an empty selection; stored entries then carry candidateAnalysis only when analyzeCandidates is true. Returns compiler projection diagnostics before execution. Catalogue roles and datatype capabilities alone do not certify a breakdown.
    • description (string; optional)
    • question (string; optional)
    • meaning (string; optional)
    • businessValue (string; optional)
    • finding (string; optional). What the data showed when astrato_semantic_layer_create_next_questions created this question as a driver of another question’s change: its one-sentence finding, written then and never refreshed. Only that tool writes it: a create carrying one is refused, and a replace or patch keeps the stored one whether it is resent as read or left out, and is refused when it differs.
    • findingEvidence (object; optional). The evidence the finding was built from, stored beside it and kept the same way: resend as read, or leave it out.
      • method (string; required; one of multiplicative, additive, priceVolumeMix, customerBridge, concentration, gapToTarget)
      • change (number; required)
      • leading (object; optional)
        • label (string; required)
        • change (number; required)
        • before (number; optional)
        • now (number; optional)
      • offsetting (object; optional)
        • parts (array of object; required)
          • label (string; required)
          • change (number; required)
        • change (number; required)
      • concentration (object; optional)
        • dimension (string; required)
        • memberCount (number; required)
        • topShare (number; required)
        • topThreeShare (number; required)
      • gapToTarget (object; optional)
        • dimension (string; required)
        • target (string; required)
        • memberCount (number; required)
        • attainment (number; required)
        • leadingShare (number; required)
        • leadingAttainment (number; required)
    • followUps (array of string; optional). References to other stored business questions, never free text: each entry identifies a name from available.businessQuestions as astrato_semantic_layer_prepare_question_change returned it. Matching normalizes equivalent Unicode spellings and ignores surrounding whitespace and case, then stores the layer’s existing name. A question cannot follow up with itself. Anything that names no other question here is dropped and reported rather than stored, so to follow up with a question that does not exist yet, save that question first and then reference it.
    • categories (array of string; optional)
    • dimensions (array of object or map of string to object; optional). An ordered list: its order is the answer’s column order, a moving calculation moves along the first dimension, and a row comparison partitions by the last. An inline periodAxis uses the same definition as a global axis and needs a key. A name-keyed map is still accepted and read as the keyed list it names, in the order it is written. Dimensions and measures together: at most 20, not counting hidden filter-only calculations. An empty list with one measure asks for a single total across everything.
    • measures (array of object or map of string to object; optional; default []). An ordered list of reusable measure references, or keyed selections: a keyed selection may be a formula over completed sibling results, and may add period bindings, comparisons, explicit reductions and an advancedCalculation over the answer’s rows. A name-keyed map is still accepted, as for dimensions. Omit or leave empty for a question that asks for a list rather than an aggregate — “the customers in California” selects dimensions and nothing else. A question must select something, so at least one dimension is then required. Dimensions and measures together: at most 20.
    • filters (object; optional). Pre-calculation filters. Subjects may reference fields or dimensions, never measures. One object, never an array: an expression naming conditions in braces, and each condition under its name as {operator, arguments: [subject, value…]}, for example {“expression”: “{f1} AND {f2}”, “f1”: {“operator”: “equals”, “arguments”: [{“reference”: {“dimension”: “Region”}}, {“value”: “West”}]}, “f2”: {…}}. Names are generated as f1, f2, …, and any other name is kept unless it is empty, is expression or parameters, or holds braces or a line break. The expression combines them with AND, OR and parentheses (NOT is for associative filters only) and names every condition of the same filter exactly once; a parameter’s name is not a condition. A period — last month, this year so far, the last 30 days — is a generated range: the between operator with a single date argument, {“date”: {“kind”: “predefinedRange”, “period”: “previousMonth”}}. A fixed date is a value that carries the type of the field it is compared with, {“value”: “2026-08-01”, “dataType”: “date”}, two of them for a range; a saved question refuses one without it. A parameter supplies a value inside a condition as {“reference”: {“parameter”: “channel”}} and is declared under parameters. A condition’s operator is one of equals, notEquals, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, between, notBetween, inList, notInList, contains, notContains, like, notLike, set, notSet, hideNotSet, geoIntersects. The lowercase names the query catalogue lists (gte, inlist, notset…) are also accepted, as are the comparison spellings authoring uses (=, >=, greater_than_or_equal). Other snake_case spellings such as is_not_set are refused with the name to use. like/notLike wildcards: * and ?, not %.
    • associativeFilters (object; optional)
    • resultFilters (object; optional). A plain-measure condition (no period comparison) runs before advancedCalculation, so totals and ranks cover only kept rows; one on an advancedCalculation selection runs after. reference.measure: a sibling key, or without keys a reusable measure. Shape, grammar and operators as for filters.
    • output (array of object; optional; at least 1 item). Answer columns, in returned order. Omitted returns all selections. Hidden dimensions still define the grouping grain.
      • reference (object; required)
    • orderBy (array of object; optional). Prioritized orderBy rules. Every target must be selected by this question.
      • reference (object; required)
      • direction (string; optional; one of ascending, descending)
    • preferredCharts (array of object; optional). Advisory renderer suggestions only. They never change query validity.
      • type (string; required; one of line, bar, stacked_bar, area, pie, donut, scatter, table, heatmap, funnel, kpi, combo, waterfall, dot)
      • reason (string; optional)
    • defaults (object; optional)
      • topN (integer; optional; 1 to 1000). Rank and bound the complete answer. With several dimensions and a measure, N counts ranked values, not rows. Without rankedDimension or allMode the last dimension is ranked within each combination of the others (top N per group), and resultNotices says so.
      • ranking (object; optional)
        • reference (object; required)
          • measure (string; required; at least 1 character)
        • direction (string; optional; one of ascending, descending)
      • rankedDimension (object; optional). With several dimensions, rank this selected dimension (named like an orderBy target) by the measure totalled across the others, and keep every row under its top N values: country × category with rankedDimension country keeps the top N countries with all their categories. Absent ranks within all other dimensions.
        • dimension (string; required; at least 1 character)
      • allMode (string; optional; always independent). With several dimensions and no rankedDimension, rank each dimension on its own and keep the rows whose values are in every top N. Absent keeps ranking within all other dimensions.
      • hideZeroValues (boolean; optional). Drop rows where every selected measure is zero or null, for example products with no sales in the filtered period. A row with any non-zero measure stays. No effect on a question without measures. Refused together with topN: send one or the other.
      • showOthers (boolean; optional)
      • othersPosition (string; optional; one of default, first, last). first puts Others before the ranked rows, last after them, default keeps it in the question’s order. Takes effect with an orderBy; without one the answer follows the rank and Others comes last.
      • othersLabel (string; optional)
    • local (object; optional). Transient semantic definitions referenced by name from this BQ. Saving promotes them atomically to the semantic layer; conflicting names are rejected. Saved questions reference the promoted entities and require publication before executing them.
      • dimensions (map of string to object; optional)
      • measures (map of string to object; optional)
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • draft (object; optional). Listed only where Deployment Region authoring is enabled. Opt in to an exact saved draft using revision and headToken from the layer read/save. Omit for published behavior. Prepare returns draft only when supported by this connection; draftUnavailable means the returned catalogue is published, so omit draft when executing it. Repeat the returned draft unchanged for preparation, dryRun, execution and pagination. A changed draft or lost execution capability requires preparing again; draft execution never falls back silently.
    • revision (integer; required; at least 0)
    • headToken (string; required; 1 to 1024 characters)
  • debug (boolean; optional). Capture the exact model and query inputs, resolved parameters and full compiler analysis as a caller-scoped MCP replay resource, also on authorized failures. Includes existing compiled SQL where available; does not compile extra SQL or capture result rows. Read debugReplay.resourceUri with resources/read.
  • parameters (object; optional). Execution-only overrides. all is keyed by parameter name and reaches every selection and filter group that declares it; measures is keyed by the BQ measure selection key, then the declared parameter name; filters and resultFilters by parameter name; associativeFilters by branch name then parameter name; drillLevels by dimension selection key. Omitted values retain declared defaults. Never copy these values into a saved definition.
    • all (map of string to string or number or boolean; optional). Values by parameter name for every measure selection, filters and resultFilters group that declares the name; groups that do not declare it are left alone. The simplest way to set a window shared by several measures, and the only way to set a view parameter, including on a view reached through a join; a value bound to the user wins over it. A value under measures, filters or resultFilters for one selection or group wins over this one.
    • measures (map of string to map of string to string or number or boolean; optional)
    • filters (map of string to string or number or boolean; optional)
    • resultFilters (map of string to string or number or boolean; optional)
    • associativeFilters (map of string to map of string to string or number or boolean; optional)
    • drillLevels (map of string to object; optional). The level a drill-through dimension selection groups by, keyed by its selection key (the string index for an array of selections). The value is one of that selection’s drillLevels references, or the field it groups by. Omitted, the first level is used. Choose the level the user asked to break the answer down by: “sales by channel” on a question grouped by a drill-through with a Channel level executes that question with Channel.
  • limit (integer; optional; 1 to 1000). Rows per page, 1 to 1000; 100 when omitted, or the whole Top N answer when topN is larger, Others included. Continue a longer result from nextOffset.
  • offset (integer; optional; at least 0)
  • queryTimeout (integer; optional; 120 to 600). Engine timeout for each attempt in whole seconds, from 120 to 600. Default 120. Allow the MCP call at least twice this value plus retry delay; one transient failure may run the query again.
  • dryRun (boolean; optional). When true, compile the SQL this exact call would run and return it as statement, with the result columns, without running anything. Use it when the SQL is wanted before or instead of running the query; an execution already returns the SQL it ran.
  • responseBudgetBytes (integer; optional; 4096 to 262,144). Optional Astrato query data budget in serialized UTF-8 bytes; default 49152. Not a token count or MCP capability. Follow nextOffset with the same query, parameters and orderBy. Rows are never cut; if one cannot fit, request a larger budget or select fewer columns. Applies to executed results, not dry-run SQL.
  • query (object; required). The question alone. limit, offset and dryRun are arguments beside query, never inside it.
    • description (string; optional)
    • question (string; optional)
    • meaning (string; optional)
    • businessValue (string; optional)
    • finding (string; optional). What the data showed when astrato_semantic_layer_create_next_questions created this question as a driver of another question’s change: its one-sentence finding, written then and never refreshed. Only that tool writes it: a create carrying one is refused, and a replace or patch keeps the stored one whether it is resent as read or left out, and is refused when it differs.
    • findingEvidence (object; optional). The evidence the finding was built from, stored beside it and kept the same way: resend as read, or leave it out.
      • method (string; required; one of multiplicative, additive, priceVolumeMix, customerBridge, concentration, gapToTarget)
      • change (number; required)
      • leading (object; optional)
        • label (string; required)
        • change (number; required)
        • before (number; optional)
        • now (number; optional)
      • offsetting (object; optional)
        • parts (array of object; required)
          • label (string; required)
          • change (number; required)
        • change (number; required)
      • concentration (object; optional)
        • dimension (string; required)
        • memberCount (number; required)
        • topShare (number; required)
        • topThreeShare (number; required)
      • gapToTarget (object; optional)
        • dimension (string; required)
        • target (string; required)
        • memberCount (number; required)
        • attainment (number; required)
        • leadingShare (number; required)
        • leadingAttainment (number; required)
    • followUps (array of string; optional). References to other stored business questions, never free text: each entry identifies a name from available.businessQuestions as astrato_semantic_layer_prepare_question_change returned it. Matching normalizes equivalent Unicode spellings and ignores surrounding whitespace and case, then stores the layer’s existing name. A question cannot follow up with itself. Anything that names no other question here is dropped and reported rather than stored, so to follow up with a question that does not exist yet, save that question first and then reference it.
    • categories (array of string; optional)
    • dimensions (array of object or map of string to object; required). An ordered list: its order is the answer’s column order, a moving calculation moves along the first dimension, and a row comparison partitions by the last. An inline periodAxis uses the same definition as a global axis and needs a key. A name-keyed map is still accepted and read as the keyed list it names, in the order it is written. Dimensions and measures together: at most 20, not counting hidden filter-only calculations. An empty list with one measure asks for a single total across everything.
    • measures (array of object or map of string to object; optional; default []). An ordered list of reusable measure references, or keyed selections: a keyed selection may be a formula over completed sibling results, and may add period bindings, comparisons, explicit reductions and an advancedCalculation over the answer’s rows. A name-keyed map is still accepted, as for dimensions. Omit or leave empty for a question that asks for a list rather than an aggregate — “the customers in California” selects dimensions and nothing else. A question must select something, so at least one dimension is then required. Dimensions and measures together: at most 20.
    • filters (object; optional). Pre-calculation filters. Subjects may reference fields or dimensions, never measures. One object, never an array: an expression naming conditions in braces, and each condition under its name as {operator, arguments: [subject, value…]}, for example {“expression”: “{f1} AND {f2}”, “f1”: {“operator”: “equals”, “arguments”: [{“reference”: {“dimension”: “Region”}}, {“value”: “West”}]}, “f2”: {…}}. Names are generated as f1, f2, …, and any other name is kept unless it is empty, is expression or parameters, or holds braces or a line break. The expression combines them with AND, OR and parentheses (NOT is for associative filters only) and names every condition of the same filter exactly once; a parameter’s name is not a condition. A period — last month, this year so far, the last 30 days — is a generated range: the between operator with a single date argument, {“date”: {“kind”: “predefinedRange”, “period”: “previousMonth”}}. A fixed date is a value that carries the type of the field it is compared with, {“value”: “2026-08-01”, “dataType”: “date”}, two of them for a range; a saved question refuses one without it. A parameter supplies a value inside a condition as {“reference”: {“parameter”: “channel”}} and is declared under parameters. A condition’s operator is one of equals, notEquals, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, between, notBetween, inList, notInList, contains, notContains, like, notLike, set, notSet, hideNotSet, geoIntersects. The lowercase names the query catalogue lists (gte, inlist, notset…) are also accepted, as are the comparison spellings authoring uses (=, >=, greater_than_or_equal). Other snake_case spellings such as is_not_set are refused with the name to use. like/notLike wildcards: * and ?, not %.
    • associativeFilters (object; optional)
    • resultFilters (object; optional). A plain-measure condition (no period comparison) runs before advancedCalculation, so totals and ranks cover only kept rows; one on an advancedCalculation selection runs after. reference.measure: a sibling key, or without keys a reusable measure. Shape, grammar and operators as for filters.
    • output (array of object; optional; at least 1 item). Answer columns, in returned order. Omitted returns all selections. Hidden dimensions still define the grouping grain.
      • reference (object; required)
    • orderBy (array of object; optional). Prioritized orderBy rules. Every target must be selected by this question.
      • reference (object; required)
      • direction (string; optional; one of ascending, descending)
    • preferredCharts (array of object; optional). Advisory renderer suggestions only. They never change query validity.
      • type (string; required; one of line, bar, stacked_bar, area, pie, donut, scatter, table, heatmap, funnel, kpi, combo, waterfall, dot)
      • reason (string; optional)
    • defaults (object; optional)
      • topN (integer; optional; 1 to 1000). Rank and bound the complete answer. With several dimensions and a measure, N counts ranked values, not rows. Without rankedDimension or allMode the last dimension is ranked within each combination of the others (top N per group), and resultNotices says so.
      • ranking (object; optional)
        • reference (object; required)
          • measure (string; required; at least 1 character)
        • direction (string; optional; one of ascending, descending)
      • rankedDimension (object; optional). With several dimensions, rank this selected dimension (named like an orderBy target) by the measure totalled across the others, and keep every row under its top N values: country × category with rankedDimension country keeps the top N countries with all their categories. Absent ranks within all other dimensions.
        • dimension (string; required; at least 1 character)
      • allMode (string; optional; always independent). With several dimensions and no rankedDimension, rank each dimension on its own and keep the rows whose values are in every top N. Absent keeps ranking within all other dimensions.
      • hideZeroValues (boolean; optional). Drop rows where every selected measure is zero or null, for example products with no sales in the filtered period. A row with any non-zero measure stays. No effect on a question without measures. Refused together with topN: send one or the other.
      • showOthers (boolean; optional)
      • othersPosition (string; optional; one of default, first, last). first puts Others before the ranked rows, last after them, default keeps it in the question’s order. Takes effect with an orderBy; without one the answer follows the rank and Others comes last.
      • othersLabel (string; optional)
    • local (object; optional). Transient semantic definitions referenced by name from this BQ. Saving promotes them atomically to the semantic layer; conflicting names are rejected. Saved questions reference the promoted entities and require publication before executing them.
      • dimensions (map of string to object; optional)
      • measures (map of string to object; optional)
  • message (string; required; 1 to 8000 characters after trimming). The customer’s problem or question in their own words, for this turn. It is the only field the handler passes on; the backend reads the conversation’s own progress.
  • clarificationCount (integer; optional; 0 to 3). Accepted for compatibility and ignored. The backend owns the three-question budget.
  • message (string; required; 1 to 8000 characters after trimming). The customer’s reporting request in their own words. It is the only field the handler passes on, so a classification sent here cannot override what the customer actually asked for.
  • searchResult (object; required). The latest escalate result from astrato_support_search_public_knowledge, copied unchanged. It is validated and rejects any field not listed here; the backend then reuses its own current decision rather than this copy.
    • action (string; required; escalate only)
    • issueType (string; required; one of bug, feature)
    • issueOrigin (string; required; one of astrato_bug, unknown, feature_request)
    • evidence (object; required). One field, error (string; required; one of provided, unavailable, missing). No other field is accepted.
    • summary (string; required; 1 to 500 characters after trimming). The issue summary from that result.
  • userAction (string; optional; one of requested_support, accepted_support_offer). Which of the two the customer did. Asking for help, a rejected question or reaching the question ceiling authorises no draft, whatever is passed here.
  • name (string; optional; 1 to 200 characters). Only layers whose name matches these words, case-insensitively and in any order; a word may be the start of a longer one. Best matches first.
  • datasourceId (UUID string; optional). Only layers bound to this datasource, from astrato_data_list_sources.
  • semanticLayerId (UUID string; optional). Only the layer with this id: one entry with its name and datasource, or none when no layer you can read has it. Send it alone, without name or datasourceId.
  • offset (integer; optional; at least 0). Zero-based catalog offset. Start at 0.
  • limit (integer; optional; 1 to 50). Maximum semantic layers to return, up to 50.
  • name (string; required; at least 1 character). Requested name for the new semantic layer. Astrato appends a copy suffix when another layer already uses it, so the created name is the one the result reports.
  • datasourceId (UUID string; optional). Datasource id from astrato_data_list_sources. A semantic layer binds to exactly one datasource. Required unless copyFromSemanticLayerId is given, which takes its datasource from the layer being copied.
  • copyFromSemanticLayerId (UUID string; optional). Copy this layer instead of creating an empty one. The new layer receives every table, field, join, dimension and measure of that layer as it currently stands, in one revision. If the source changes during creation, the copy fails and cleanup is attempted; retry from the current source. Use this for any duplicate: rebuilding a layer entity by entity takes dozens of calls and produces a different model.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • name (string; optional; at least 1 character). New name for the layer. Omit to keep the current one. Report the name the result returns, which is the one Astrato keeps.
  • description (string; optional; at most 250 characters). New description, up to 250 characters. An empty string clears it; omit to keep the current one.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • visibleToEveryone (boolean; required). true makes the layer visible to everyone in the workspace; false removes workspace-wide visibility.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • mode (string; required; one of dataSource, dataActions). Draft workflow policy: connection permissions or registered workflows only.
  • expectedRevision (integer; optional; at least 0). Current draft revision, when obtained from an authoring context.
Section titled “astrato_semantic_layer_unlink_import_source”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • source (string; optional; at least 1 character). The linked view as DATABASE.SCHEMA.NAME, exactly as the error or the editor lists it. Optional when only one is linked.
  • expectedRevision (integer; optional; at least 0). Current draft revision, when obtained from an authoring context.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.

astrato_semantic_layer_export_snowflake_semantic_view

Section titled “astrato_semantic_layer_export_snowflake_semantic_view”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • database (string; optional; at least 1 character). Snowflake database to create the semantic view in. Defaults to the connection default.
  • schema (string; optional; at least 1 character). Snowflake schema to create the semantic view in. Defaults to the connection default.
  • name (string; optional; at least 1 character). Semantic view name. Defaults to the layer name in upper snake case.
  • completions (object; optional). Expressions and SQL for pending items, keyed by their Astrato name (pending[].key).
    • measures (map of string to object; optional)
    • dimensions (map of string to object; optional)
    • verifiedQueries (map of string to object; optional)
  • finalize (boolean; optional). Attach the .sql file for the user. Set it on the call whose result is final.

astrato_semantic_layer_export_databricks_metric_view

Section titled “astrato_semantic_layer_export_databricks_metric_view”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • catalog (string; optional; at least 1 character). Databricks catalog to create the metric view in. Defaults to the connection catalog.
  • schema (string; optional; at least 1 character). Databricks schema to create the metric view in. Defaults to the connection schema.
  • name (string; optional; at least 1 character). Metric view name. Defaults to the layer name in snake case with a _metric_view suffix.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • expectedRevision (integer; required; at least 0). Exact current revision returned by a fresh summary or validation.

astrato_semantic_layer_list_snowflake_views

Section titled “astrato_semantic_layer_list_snowflake_views”
  • datasourceId (UUID string; required). Snowflake datasource id.

astrato_semantic_layer_preview_snowflake_view_import

Section titled “astrato_semantic_layer_preview_snowflake_view_import”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • datasourceId (UUID string; required). Snowflake datasource id.
  • database (string; required; at least 1 character). Exact Snowflake database name.
  • schema (string; required; at least 1 character). Exact Snowflake schema name.
  • name (string; required; at least 1 character). Exact Snowflake semantic view name.

astrato_semantic_layer_list_databricks_metric_views

Section titled “astrato_semantic_layer_list_databricks_metric_views”
  • datasourceId (UUID string; required). Databricks datasource id.

astrato_semantic_layer_preview_databricks_metric_view_import

Section titled “astrato_semantic_layer_preview_databricks_metric_view_import”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • datasourceId (UUID string; required). Databricks datasource id.
  • database (string; required; at least 1 character). Exact Databricks catalog name.
  • schema (string; required; at least 1 character). Exact Databricks schema name.
  • name (string; required; at least 1 character). Exact Databricks metric view name.

astrato_semantic_layer_import_snowflake_view

Section titled “astrato_semantic_layer_import_snowflake_view”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • datasourceId (UUID string; required). Snowflake datasource id.
  • database (string; required; at least 1 character). Exact Snowflake database name.
  • schema (string; required; at least 1 character). Exact Snowflake schema name.
  • name (string; required; at least 1 character). Exact Snowflake semantic view name.
  • expectedRevision (integer; required; at least 0). Revision returned by preview.
  • expectedSourceHash (string; required; at least 1 character). Snowflake source hash returned by preview.
  • acceptDiagnostics (boolean; required). Confirm that preview diagnostics are accepted.
  • replaceExisting (boolean; optional). Explicitly replace a non-empty draft. Omit or false for the safe empty-layer default.

astrato_semantic_layer_import_databricks_metric_view

Section titled “astrato_semantic_layer_import_databricks_metric_view”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • datasourceId (UUID string; required). Databricks datasource id.
  • database (string; required; at least 1 character). Exact Databricks catalog name.
  • schema (string; required; at least 1 character). Exact Databricks schema name.
  • name (string; required; at least 1 character). Exact Databricks metric view name.
  • expectedRevision (integer; required; at least 0). Revision returned by preview.
  • expectedSourceHash (string; required; at least 1 character). Databricks source hash returned by preview.
  • acceptDiagnostics (boolean; required). Confirm that preview diagnostics are accepted.
  • replaceExisting (boolean; optional). Explicitly replace a non-empty draft. Omit or false for the safe empty-layer default.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • includeSnapshot (boolean; optional). When true, attach the complete semantic layer document as stored, as JSON. Current layers are V3 (fileVersion: 3), but read fileVersion before parsing; the file name still reads v2 whatever it holds. It comes as a standard resource_link, plus a second resource_link (parametersResourceUri) mapping each measure name to its effective parameters, including those a derived or conditional measure inherits from its operands (declaredBy), as astrato_data_prepare_query reports them; a measure it omits has no effective parameters. Use only for deterministic bulk reads; omit for ordinary summaries and bounded detail reads.
  • snapshotOf (string; optional; one of draft, published). Which document includeSnapshot attaches. draft (default) is the current draft; published is the latest published revision, which is what queries run on, or for a layer published outside this editor (publicationSource engine) the model the engine serves. Refused when the engine holds no published model.
  • includeDetails (boolean; optional). When true, include every view and field with data types, joins, and reusable items for a complete user-facing description.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • section (string; required; one of views, fields, joins, items). Detail collection to read. Follow nextCursor until it is absent.
  • cursor (string; optional). Opaque nextCursor returned by the previous page.
  • limit (integer; optional; 1 to 50). Maximum entries in this page. Defaults to 25.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • text (string; optional; at most 200 characters). Search text, at most 200 characters. Empty string returns top entities.
  • query (string; optional; at most 200 characters). Alias for text.
  • limit (integer; optional; 1 to 50). Maximum number of matches to return.

astrato_semantic_layer_search_source_catalog

Section titled “astrato_semantic_layer_search_source_catalog”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • informationSchemaUri (string; optional; at least 1 character). Resource URI returned by an earlier source-catalog call. Reuse it so searches and authoring expand one progressive information schema.
  • query (string; required; at least 1 character). Business or physical source terms, for example “bike sales”.
  • database (string; optional; at least 1 character)
  • schema (string; optional; at least 1 character)
  • table (string; optional; at least 1 character). Exact table, with schema: its physical name (the table a source search returns) or, for a listed table, the listing’s display name. The physical name is matched first, then the display name, so send the physical name when the two could differ. A table the connection’s listing omits is still resolved by its exact physical name when its columns can be read; never guess casing.
  • includeColumns (boolean; optional)
  • schemaOffset (integer; optional; at least 0)
  • limit (integer; optional; 1 to 50)

astrato_semantic_layer_prepare_view_change

Section titled “astrato_semantic_layer_prepare_view_change”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • informationSchemaUri (string; optional; at least 1 character). Resource URI returned by an earlier source-catalog call. Reuse it so searches and authoring expand one progressive information schema.
  • request (string; required; at least 1 character). The user request in their own business language.
  • targetView (string; optional; at least 1 character)
  • sourceQueries (array of object; optional; at most 12 items; default []). Every physical source concept needed by this change. One call resolves all concepts.
    • id (string; required; matches ^[A-Za-z][A-Za-z0-9_]*$)
    • text (string; required; at least 1 character)
    • database (string; optional; at least 1 character)
    • schema (string; optional; at least 1 character)
    • table (string; optional; at least 1 character). Exact table, with schema: its physical name (the table a source search returns) or, for a listed table, the listing’s display name. The physical name is matched first, then the display name, so send the physical name when the two could differ. A table the connection’s listing omits is still resolved by its exact physical name when its columns can be read; never guess casing.
    • includeColumns (boolean; optional)
    • schemaOffset (integer; optional; at least 0)

astrato_semantic_layer_refresh_source_catalog

Section titled “astrato_semantic_layer_refresh_source_catalog”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • informationSchemaUri (string; required; at least 1 character). The information-schema resource URI to refresh.
  • database (string; optional; at least 1 character)
  • schema (string; optional; at least 1 character)
  • table (string; optional; at least 1 character). Exact table, with schema: its physical name (the table a source search returns) or, for a listed table, the listing’s display name. The physical name is matched first, then the display name, so send the physical name when the two could differ. A table the connection’s listing omits is still resolved by its exact physical name when its columns can be read; never guess casing.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • query (string; required; 1 to 200 characters). Natural field name, including compact or camel-case forms such as UnitPrice. At most 200 characters.
  • dataTypes (array of string; optional; at least 1 item). Optional concrete datatypes or broad families: numeric, date, text, or boolean.
  • limit (integer; optional; 1 to 20; default 5)
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.

astrato_semantic_layer_prepare_measure_change

Section titled “astrato_semantic_layer_prepare_measure_change”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • request (string; required; at least 1 character). The user request in their own business language. Used only to explain the returned context.
  • targetMeasure (string; optional; at least 1 character). Exact or user-supplied measure name for edit, delete, or replacement requests.
  • queries (array of object; required; 1 to 12 items). Business input concepts to resolve in one call. Do not include the target item here; targetMeasure resolves its exact current definition separately. Decompose inputs such as sales amount, customer age, region, or order date.
    • id (string; required; matches ^[A-Za-z][A-Za-z0-9_]*$)
    • text (string; required; 1 to 200 characters)
    • kinds (array of string; optional; at least 1 item; each one of field, measure)
    • dataTypes (array of string; optional; at least 1 item). Optional engine datatype or broad family: numeric, date, text, or boolean. Families match the connection-specific concrete datatypes.
  • includeSuggestions (boolean; optional). Also return create-ready semantic-engine measure suggestions for this request.
  • includeCompiledSql (boolean; optional). Also compile statement-only SQL for the prepared target, or for returned suggestions when no target exists. Implies suggestions for create requests.
  • compact (boolean; optional). Return a smaller deterministic-client response. Preserves exact references, aggregation capabilities, target definition, joins, and revision while omitting repeated locale, relative-period, authoring-rule, and candidate display metadata.

astrato_semantic_layer_plan_authoring_batch

Section titled “astrato_semantic_layer_plan_authoring_batch”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • items (array of object (3 shapes); required; 1 to 200 items). All independent measure, dimension and business-question requests to resolve together. Include a measure-kind query for a proposed create so existing exact-use-case measures can be reused instead of duplicated.
    • entity (string; required; one of measure, dimension, businessQuestion)
    • id (string; required; matches ^[A-Za-z][A-Za-z0-9_]*$)
    • operation (string; required when entity is measure or dimension; one of create, replace, patch, rename, delete, duplicate)
    • request (string; required; at least 1 character)
    • targetName (string; optional; at least 1 character)
    • queries (array of object; optional; at most 24 items; default []). Only when entity is measure or dimension.
      • id (string; required; matches ^[A-Za-z][A-Za-z0-9_]*$)
      • text (string; required; 1 to 200 characters)
      • kinds (array of string; optional; at least 1 item; each one of field, measure)
      • dataTypes (array of string; optional; at least 1 item). Optional engine datatype or broad family: numeric, date, text, or boolean. Families match the connection-specific concrete datatypes.
    • operation (string; required when entity is businessQuestion; one of create, replace, patch, rename, delete)
    • queries (array of object; optional; at most 24 items; default []). Only when entity is businessQuestion. One query per physical field the question compares: each filter or result-filter field, and an associative filter’s target and every branch field. The plan resolves them with the rest of the batch.
      • id (string; required; matches ^[A-Za-z][A-Za-z0-9_]*$)
      • text (string; required; 1 to 200 characters)
      • kinds (array of string; optional; at least 1 item; each one of field, measure)
      • dataTypes (array of string; optional; at least 1 item). Optional engine datatype or broad family: numeric, date, text, or boolean. Families match the connection-specific concrete datatypes.

astrato_semantic_layer_commit_authoring_batch

Section titled “astrato_semantic_layer_commit_authoring_batch”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • planId (UUID string; optional). Response-only plan id returned by astrato_semantic_layer_plan_authoring_batch.
  • expectedRevision (integer; required; at least 0). Revision returned by astrato_semantic_layer_plan_authoring_batch. The complete batch is rejected when it is stale.
  • items (array of object (3 shapes); required; 1 to 200 items). Independent typed intents compiled and validated together, then committed in one revision.
    • entity (string; required; one of measure, dimension, businessQuestion)
    • id (string; required; matches ^[A-Za-z][A-Za-z0-9_]*$)
    • preparedTarget (string or null; required; at least 1 character)
    • change (object (6 shapes); required when entity is measure; shape chosen by operation: create, replace, patch, delete, rename, duplicate). Same shapes as change in astrato_semantic_layer_apply_measure_change, except that patch has its own fields here; read them from the input schema.
    • change (object (6 shapes); required when entity is dimension; shape chosen by operation: create, replace, patch, delete, rename, duplicate). Same shapes as change in astrato_semantic_layer_apply_dimension_change.
    • change (object (5 shapes); required when entity is businessQuestion; shape chosen by operation: create, replace, patch, rename, delete). Fields: operation, name, definition, ifExists, patch, newName, references.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • informationSchemaUri (string; optional; at least 1 character). Resource URI returned by an earlier source-catalog call. Reuse it so searches and authoring expand one progressive information schema.
  • expectedRevision (integer; required; at least 0)
  • changes (array of object (2 shapes); required; 1 to 300 items). Ordered view and field intents. They validate and commit together in at most one revision. Send every intent for one operation in a single call; a whole-model change belongs in one revision, not several.
    • entity (string; required; one of view, field)
    • change (object (8 shapes); required when entity is view; shape chosen by operation: create-table, create-sql, update-sql, create-inline, copy, rename, update, delete)
      • operation (string; required; one of create-table, create-sql, update-sql, create-inline, copy, rename, update, delete)
      • name (string; required; at least 1 character)
      • source (object; required when operation is create-table). Only when operation is create-table or update.
        • database (string; optional; at least 1 character)
        • schema (string; required; at least 1 character)
        • table (string; required; at least 1 character)
        • objectType (string; optional; at least 1 character)
      • fields (object (3 shapes); required when operation is create-table; shape chosen by mode: all, only, all-except). Only when operation is create-table or update.
        • mode (string; required; one of all, only, all-except)
        • fields (array of string; required when mode is only or all-except; at least 1 item)
      • description (string; optional). Only when operation is create-table, create-sql or create-inline.
      • statement (string; required when operation is create-sql or update-sql; at least 1 character)
      • parameters (map of string to object; optional). Only when operation is create-sql or update-sql.
      • description (object (2 shapes); optional; shape chosen by mode: set, clear). Only when operation is update-sql or update.
        • mode (string; required; one of set, clear)
        • value (string; required when mode is set)
      • columns (array of object; required when operation is create-inline; at least 1 item)
        • name (string; required; at least 1 character)
        • dataType (string; required; at least 1 character)
        • sourceType (string; optional)
        • label (string; optional)
        • description (string; optional)
        • comment (string; optional)
        • precision (integer; optional; at least 0)
        • enabled (boolean; optional)
      • rows (array of map of string to string or number or boolean or null; required when operation is create-inline)
      • newName (string; required when operation is copy or rename; at least 1 character)
      • filter (object or null; optional). Only when operation is update. The table pre-filter (row filter), replaced whole; null clears it. Inline, or a stored filter as {"reference": {"filter": name}}. Table-backed views only. Every condition reads this view’s own fields, never a dimension, a measure or another view: {"expression": "{f1}", "f1": {"operator": "equals", "arguments": [{"reference": {"view": "<this view>", "field": "<field>"}}, {"value": "Shipped"}]}}. A security rule compares a field with {"reference": {"parameter": "userEmail"}} or "userGroupNames"; the server declares those parameters.
      • filterMode (object or null; optional). Only when operation is update. active applies the pre-filter as global data reduction: tables joined to this one return only rows that survive it, when the query’s measures read them. strict also applies it when the query reads them only through dimensions or filters. Omit for a filter on this table alone; null clears it.
        • active (boolean; required)
        • strict (boolean; required)
      • parameters (object; optional). Only when operation is update. View parameter defaults by name, for {name:type} in a field or the view SQL. Merged into the stored parameters; null removes one.
    • change (object (4 shapes); required when entity is field; shape chosen by operation: create, update, rename, delete)
      • operation (string; required; one of create, update, rename, delete)
      • view (string; required; at least 1 character)
      • name (string; required; at least 1 character)
      • definition (object; required when operation is create). For an inline calculated field, use sourceType expression and source SQL. Physical inline columns have no source and are stored with CSV values.
      • definition (object; required when operation is update)
        • source (string; optional; at least 1 character)
        • dataType (string; optional; at least 1 character)
        • nativeDataType (string; optional; at least 1 character)
        • sourceType (string; optional)
        • label (string; optional)
        • description (string; optional)
        • comment (string; optional)
        • precision (integer; optional; at least 0)
        • enabled (boolean; optional)
      • newName (string; required when operation is rename; at least 1 character)

astrato_semantic_layer_apply_measure_change

Section titled “astrato_semantic_layer_apply_measure_change”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • preparedTarget (string or null; required; at least 1 character). Exact target returned by prepare, or null for creation. Copy it unchanged.
  • expectedRevision (integer; optional; at least 0). Revision returned by astrato_semantic_layer_prepare_measure_change. Prevents edits against stale context.
  • change (object (6 shapes); required; shape chosen by operation: create, replace, patch, delete, rename, duplicate). One business-level measure change. The server resolves the V3 representation, validates, previews, and commits it atomically. Organising, grouping, tagging or filing a measure is patch.categories on a patch, or definition.categories on a create or replace – never a rename.
    • operation (string; required; one of create, replace, patch, delete, rename, duplicate)
    • name (string; required; at least 1 character)
    • definition (object; required when operation is create or replace). Fields: description, label, categories, format, expression, inputs, nestedCalculation, periodComparison.
    • patch (object; required when operation is patch). Fields: description, label, categories, format, parameters, calculation, periodComparison, aggregateOptions, filter.
    • references (string; optional; one of remove, keep). Only when operation is delete. What happens to what uses it. remove deletes the measures and dimensions built on it and drops it from questions, joins, filters, datasets and set filters, as the editor’s Delete references does. keep (the default) deletes it alone and leaves those references broken, as Keep broken does; the result’s publishBlockers then name each item that needs repairing.
    • newName (string; required when operation is rename; at least 1 character)
    • references (string; optional; one of update, keep). Only when operation is rename. update (the default) renames every reference too; keep renames only the item, as the editor’s Rename only does.
    • newName (string; optional; at least 1 character). Only when operation is duplicate. Name of the copy. Omit for “Copy of <name>”, numbered when taken, as the editor names one.

astrato_semantic_layer_prepare_dimension_change

Section titled “astrato_semantic_layer_prepare_dimension_change”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • request (string; required; at least 1 character). The dimension request in the user’s business language.
  • targetDimension (string; optional; at least 1 character)
  • queries (array of object; required; 1 to 24 items). Every field or reusable dimension concept required by the dimension, in one call.
    • id (string; required; matches ^[A-Za-z][A-Za-z0-9_]*$)
    • text (string; required; 1 to 200 characters)
    • kinds (array of string; optional; at least 1 item; each one of field, measure)
    • dataTypes (array of string; optional; at least 1 item). Optional engine datatype or broad family: numeric, date, text, or boolean. Families match the connection-specific concrete datatypes.
  • includeSuggestions (boolean; optional). Also return create-ready semantic-engine dimension suggestions for this request.

astrato_semantic_layer_apply_dimension_change

Section titled “astrato_semantic_layer_apply_dimension_change”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • preparedTarget (string or null; required; at least 1 character). Exact target returned by prepare, or null for creation. Copy it unchanged.
  • expectedRevision (integer; optional; at least 0)
  • change (object (6 shapes); required; shape chosen by operation: create, replace, patch, delete, rename, duplicate). One typed dimension change. The server derives persisted V3, resolves bucket ranges when omitted, validates, previews, and commits once.
    • operation (string; required; one of create, replace, patch, delete, rename, duplicate)
    • name (string; required; at least 1 character)
    • definition (object (6 shapes); required when operation is create or replace; shape chosen by kind: field, bucket, drillthrough, mapping, periodAxis, sets). Fields: kind, field, dateLevel, datePart, description, label, categories, format, buckets, minValue, maxValue, includeBucketNumber, includeOuterBuckets, levels, resultType, groups, default, sources, period, level, periodEnd, periodEndDate, sets.
    • patch (object; required when operation is patch)
      • description (object (2 shapes); optional; shape chosen by mode: set, clear)
        • mode (string; required; one of set, clear)
        • value (string; required when mode is set)
      • categories (object (2 shapes); optional; shape chosen by mode: set, clear). Organise, group, tag or file this dimension. set replaces the whole list; clear removes every category. Set an empty list with clear rather than set.
        • mode (string; required; one of set, clear)
        • values (array of string; required when mode is set). Free-text grouping labels for this measure, used by the editor to group and filter the measure list. A measure may carry several. Reuse an existing spelling from existingMeasureCategories instead of inventing a near-duplicate.
      • format (object (3 shapes); optional; shape chosen by mode: default, none, custom). Rejected on a drill-through, whose levels carry their own formatting.
        • mode (string; required; one of default, none, custom)
        • pattern (string; required when mode is custom; at least 1 character)
      • label (object (2 shapes); optional; shape chosen by mode: set, clear). The display label shown instead of the name. set an empty value or clear to show the name again.
        • mode (string; required; one of set, clear)
        • value (string; required when mode is set)
      • bucketing (object; optional). A bucket dimension only. Each setting given changes; the others stay as stored.
        • minValue (number; optional)
        • maxValue (number; optional)
        • buckets (integer; optional; greater than 0)
        • includeBucketNumber (boolean; optional)
        • includeOuterBuckets (boolean; optional)
      • timeAxis (object; optional). A Time Axis only. Each setting given changes; its sources and the others stay as stored.
        • period (string or object; optional; one of currentYear, previousYear, yearToDate, previousYearToDate, extractYearToDate, currentQuarter, previousQuarter, quarterToDate, previousQuarterToDate, currentMonth, previousMonth, monthToDate, previousMonthToDate, extractMonthToDate, currentWeek, previousWeek, weekToDate, previousWeekToDate, last12Months, last90Days, last30Days, last7Days, today, yesterday, beginningOfYear, beginningOfPreviousYear, beginningOfQuarter, beginningOfPreviousQuarter, beginningOfMonth, beginningOfPreviousMonth, beginningOfWeek, beginningOfPreviousWeek, endOfYear, endOfQuarter, endOfMonth, endOfWeek)
        • level (string; optional; one of year, quarter, month, week, day)
        • periodEnd (string or null; optional; one of today, yesterday, latest, fixed). null reads the window as of today again.
        • periodEndDate (string or null; optional; matches ^\d{4}-\d{2}-\d{2}$)
    • references (string; optional; one of remove, keep). Only when operation is delete. What happens to what uses it. remove deletes the measures and dimensions built on it and drops it from questions, joins, filters, datasets and set filters, as the editor’s Delete references does. keep (the default) deletes it alone and leaves those references broken, as Keep broken does; the result’s publishBlockers then name each item that needs repairing.
    • newName (string; required when operation is rename; at least 1 character)
    • references (string; optional; one of update, keep). Only when operation is rename. update (the default) renames every reference too; keep renames only the item, as the editor’s Rename only does.
    • newName (string; optional; at least 1 character). Only when operation is duplicate. Name of the copy. Omit for “Copy of <name>”, numbered when taken, as the editor names one.

astrato_semantic_layer_check_source_schema

Section titled “astrato_semantic_layer_check_source_schema”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • fresh (boolean; optional). Run a new caller-authorized check. False returns the latest stored terminal result only.

astrato_semantic_layer_apply_source_schema_fix

Section titled “astrato_semantic_layer_apply_source_schema_fix”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • runId (UUID string; required). Source-check run id that produced the suggested fix.
  • entityKey (string; required; at least 1 character). Exact finding entityKey returned by astrato_semantic_layer_check_source_schema.
  • expectedRevision (integer; required; at least 0). Current draft revision returned with the source-check diagnostics.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • label (string; optional). Human-readable edit session label.
  • name (string; optional). Alias for label.

astrato_semantic_layer_get_edit_session_status

Section titled “astrato_semantic_layer_get_edit_session_status”
  • sessionId (string; required). MCP edit session id returned by astrato_semantic_layer_begin_edit_session.
  • sessionId (string; required). MCP edit session id returned by astrato_semantic_layer_begin_edit_session.
  • operation (string; required; one of rename_view, delete_view, upsert_view, rename_field, delete_field, upsert_field, upsert_join, delete_join, upsert_function, rename_function, delete_function, update_descriptions). Structured V3 non-measure edit operation.
  • editType (string; optional). Alias for operation.
  • payload (map of string to any; optional). Operation-specific V3 object for non-measure and non-dimension edits.
  • oldName (string; optional)
  • newName (string; optional)
  • name (string; optional)
  • viewName (string; optional)
  • fieldName (string; optional)
  • viewName1 (string; optional)
  • viewName2 (string; optional)
  • type (string; optional)
  • entityType (string; optional). Non-measure entity type for update_descriptions, for example dimension or udf.
  • entityKey (string; optional). Exact V3 name-keyed map entry for update_descriptions, for example Product Category.
  • description (string; optional). New human-readable description for direct update_descriptions.

astrato_semantic_layer_preview_edit_session

Section titled “astrato_semantic_layer_preview_edit_session”
  • sessionId (string; required). MCP edit session id returned by astrato_semantic_layer_begin_edit_session.

astrato_semantic_layer_commit_edit_session

Section titled “astrato_semantic_layer_commit_edit_session”
  • sessionId (string; required). MCP edit session id returned by astrato_semantic_layer_begin_edit_session.
  • summary (string; optional). Revision summary to store in draft history.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • label (string; optional). Version label.
  • name (string; optional). Alias for label.

astrato_semantic_layer_rollback_edit_session

Section titled “astrato_semantic_layer_rollback_edit_session”
  • sessionId (string; required). MCP edit session id returned by astrato_semantic_layer_begin_edit_session.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • category (string; optional). Only return questions in this category. Category values appear on listed questions.
  • query (string; optional; 1 to 200 characters). Return only the stored questions this text names best, ranked with a 0..100 score: the user’s wording of a question, or part of it. Case, punctuation, a missing question mark, a slipped letter and word order are forgiven; a description that mentions the text counts for less than a name. bestMatch is set when one question clearly is the one named.
  • limit (integer; optional; 1 to 50). How many matches a query returns, best first; 5 when omitted.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • id (string; required). Business question id from astrato_semantic_layer_list_questions.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • limit (integer; optional; 1 to 100). Most suggestions to return, best first. Defaults to 50.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • offset (integer; optional; at least 0). Index of the first draft join to check. Pass nextOffset from a previous call to continue.

astrato_semantic_layer_prepare_question_change

Section titled “astrato_semantic_layer_prepare_question_change”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • request (string; required; at least 1 character). The requested business-question change in ordinary business language.
  • targetBusinessQuestion (string; optional; at least 1 character)

astrato_semantic_layer_apply_question_change

Section titled “astrato_semantic_layer_apply_question_change”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • preparedTarget (string or null; required; at least 1 character). Exact target returned by prepare, or null for creation.
  • expectedRevision (integer; required; at least 0)
  • change (object (5 shapes); required; shape chosen by operation: create, replace, patch, rename, delete)
    • operation (string; required; one of create, replace, patch, rename, delete)
    • name (string; required; at least 1 character)
    • definition (object; required when operation is create or replace). Same fields as query in astrato_data_execute_query.
    • ifExists (string; optional; one of fail, skip, replace). Only when operation is create. When a question of this name is already stored. fail (the default) refuses unless the stored one is identical, which is left unchanged; skip leaves the stored one as it is; replace overwrites it. Use skip to retry a save safely.
    • patch (object; required when operation is patch)
      • set (map of string to any; optional). Top-level properties to replace, each whole, written as in a create definition: a list such as orderBy or filters is replaced, not merged. Everything not named stays as stored.
      • clear (array of string; optional; each one of description, question, meaning, businessValue, finding, findingEvidence, followUps, categories, filters, associativeFilters, resultFilters, output, orderBy, preferredCharts, defaults, local). Top-level properties to remove, such as resultFilters or defaults.
      • renameMeasureSelection (object; optional). Rename a keyed measure selection and every reference to it in the question (orderBy, output, result filters, formulas, ranking), as the editor does.
        • from (string; required; at least 1 character)
        • to (string; required; at least 1 character)
    • newName (string; required when operation is rename; at least 1 character)
    • references (string; optional; one of remove, keep). Only when operation is delete. What happens to what uses it: questions that follow up with it and workflows whose parameters or fields stand for it. remove drops it from them and they stay, as the editor’s Remove dependencies does. keep (the default) leaves those references broken, as Keep dependencies does; the result’s publishBlockers then name each item that needs repairing.

astrato_semantic_layer_create_next_questions

Section titled “astrato_semantic_layer_create_next_questions”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • baseQuestion (string; required; at least 1 character). Name of the stored business question the new questions follow.
  • types (array of string; optional; at least 1 item; each one of drivers, gapToTarget, concentration, trend, comparePeriods, shareOfTotal, topN, outliers, distribution, related). kind: search only: the types to look for, default every one that applies to the question. Data checks always run. distribution shows what a typical customer, order or product amounts to against the average and the top 10%; saving one adds its median, 90th percentile and count measures to the draft, so the saved question runs after a publish.
  • kind (string; optional; one of auto, drivers, gapToTarget, concentration, trend, related, search). search reads the question’s result and looks across the whole model, within a budget of reads, for what explains it: data checks first, then one question per type with a real finding, each with a finding sentence whose numbers come from the query results; see types. drivers explain why the KPI changed between two periods; gapToTarget finds the dimensions where a few members hold most of the gap between the KPI and its target measure, for a question that compares nothing and whose KPI has a target; concentration finds the dimensions where a few members hold most of the KPI total, for a question that compares nothing; trend follows the KPI month by month, alone and with its first two dimensions; related are what the engine suggests asking next about the question (other cuts, rankings, shares of the total, running totals), with no period comparison needed. auto (the default) creates drivers when the base question compares periods or a drivers-only option is given; otherwise it creates gap-to-target questions where a target is recognised and one passes the threshold, then concentration questions where one passes. It never returns trend or related questions. Giving targetMeasure means gapToTarget alone. Every kind requires data:query.
  • count (integer; optional; 1 to 10). How many questions to create, or offer with dryRun. Defaults to 3; gapToTarget and concentration default to 2. Ignored with only.
  • dryRun (boolean; optional). Run and offer the questions without saving them.
  • only (array of string; optional; at least 1 item). Create questions by their exact names from a dry run. Send the same kind and options. If a name is no longer offered, the call is refused.
  • methods (array of string; optional; at least 1 item; each one of multiplicative, additive, priceVolumeMix, customerBridge). Only these decompositions, in this order. Defaults to all: multiplicative (KPI = count × rate × average, split with Shapley values: why it changed), additive (each segment’s contribution in points of the prior total, one question per segment dimension: where it changed), priceVolumeMix (volume, mix and price effects per product; currently always skipped with a reason, because it needs a total of a formula over a period comparison, which the engine does not compute), customerBridge (new, expansion, contraction and churn per customer).
  • segmentDimensions (array of string; optional; at least 1 item). additive: the dimensions to split by, in order. Defaults to categorical dimensions that join to the KPI.
  • componentMeasures (array of string; optional; 1 to 2 items). multiplicative: one or two count measures, e.g. customers then orders, giving KPI = customers × orders per customer × KPI per order. Defaults to the count measures that join to the KPI, distinct counts first.
  • allocation (string; optional; one of shapley, sequential). multiplicative: how the change is shared between drivers. shapley (the default) averages over every order, so no driver is favoured; sequential changes one driver at a time (count, then frequency, then average, following componentMeasures), simpler to explain but order-dependent.
  • quantityMeasure (string; optional; at least 1 character). priceVolumeMix: the units-sold measure. Unused while it is skipped.
  • productDimension (string; optional; at least 1 character). priceVolumeMix: the product dimension. Unused while it is skipped.
  • customerDimension (string; optional; at least 1 character). customerBridge: the dimension identifying a customer.
  • targetMeasure (string; optional; at least 1 character). gapToTarget: the stored measure the KPI is measured against. Defaults to the one recognised by name: a measure the base question selects beside its KPI whose name says target, budget, plan, goal, quota or forecast, else a layer measure saying so that names the KPI (Revenue Target for Revenue). Giving it means gapToTarget.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • name (string; required; at least 1 character). Dataset name from astrato_semantic_layer_list_datasets.

astrato_semantic_layer_prepare_dataset_change

Section titled “astrato_semantic_layer_prepare_dataset_change”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • request (string; required; at least 1 character). The requested dataset change in ordinary business language.
  • targetDataset (string; optional; at least 1 character). Name of the dataset to change; omit to create one.

astrato_semantic_layer_apply_dataset_change

Section titled “astrato_semantic_layer_apply_dataset_change”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • preparedTarget (string or null; required; at least 1 character). Exact target returned by prepare, or null for creation.
  • expectedRevision (integer; required; at least 0)
  • change (object (5 shapes); required; shape chosen by operation: create, replace, update, rename, delete)
    • operation (string; required; one of create, replace, update, rename, delete)
    • name (string; required; at least 1 character)
    • definition (object; required when operation is create or replace)
      • description (string; optional). What business area the dataset covers.
      • categories (array of string; optional). Free-text labels the dataset is filed under. Reuse a spelling the layer already uses.
      • filters (object; optional). Inline regular filters or reference: { filter: name }.
      • dimensions (array of object; required). Stored dimensions the dataset offers, in display order.
        • reference (object; required)
          • dimension (string; required; at least 1 character)
      • measures (array of object; required). Stored measures the dataset offers, in display order.
        • reference (object; required)
          • measure (string; required; at least 1 character)
    • patch (object; required when operation is update)
      • description (string or null; optional). New description; null or an empty string clears it. Omit to keep the current one.
      • categories (array of string; optional). Replaces the categories; an empty array clears them. Omit to keep the current ones.
      • filters (object or null; optional). Replace regular filters; null clears them, omission preserves them.
      • addDimensions (array of string; optional). Dimension names to append.
      • removeDimensions (array of string; optional). Dimension names to remove.
      • addMeasures (array of string; optional). Measure names to append.
      • removeMeasures (array of string; optional). Measure names to remove.
    • newName (string; required when operation is rename; at least 1 character)
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • name (string; required; at least 1 character). Set filter name from astrato_semantic_layer_list_set_filters.

astrato_semantic_layer_prepare_set_filter_change

Section titled “astrato_semantic_layer_prepare_set_filter_change”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • request (string; required; at least 1 character). The requested set filter change in ordinary business language.
  • targetSetFilter (string; optional; at least 1 character). Name of the set filter to change; omit to create one.

astrato_semantic_layer_apply_set_filter_change

Section titled “astrato_semantic_layer_apply_set_filter_change”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • preparedTarget (string or null; required; at least 1 character). Exact target returned by prepare, or null for creation.
  • expectedRevision (integer; required; at least 0)
  • change (object (5 shapes); required; shape chosen by operation: create, replace, update, rename, delete)
    • operation (string; required; one of create, replace, update, rename, delete)
    • name (string; required; at least 1 character)
    • definition (object; required when operation is create or replace)
    • patch (object; required when operation is update)
      • description (string or null; optional). New description; null or an empty string clears it. Omit to keep the current one.
      • categories (array of string; optional). Replaces the categories; an empty array clears them. Omit to keep the current ones.
      • associativeFilters (object; optional). Set filters only: replaces the target and branches as a whole. Omit to keep the current ones.
      • filters (object; optional). Regular filters only: replaces the conditions as a whole. Omit to keep the current ones.
    • newName (string; required when operation is rename; at least 1 character)

astrato_semantic_layer_get_security_overview

Section titled “astrato_semantic_layer_get_security_overview”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • name (string; required; at least 1 character). Exact data action name. When supplied by the user or a preceding result, read it directly; list only to discover an unknown name.

astrato_semantic_layer_prepare_data_action_change

Section titled “astrato_semantic_layer_prepare_data_action_change”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • request (string; required; at least 1 character). The requested data action change in ordinary business language.
  • targetDataAction (string; optional; at least 1 character). Name of the data action to change; omit to create one.
  • kind (string; optional; one of table, storedProcedure, virtualProcedure). What a new action registers. storedProcedure also lists the connection’s procedures under available.procedures; an existing target decides its own kind.
  • view (string; optional; at least 1 character). The view a table action writes through; its fields are listed under available.fields.
  • schema (string; optional; at least 1 character). Narrows available.procedures to one schema.
  • database (string; optional; at least 1 character). Reads available.procedures from this Snowflake database, BigQuery project or Databricks catalog instead of the connection’s own. Name the same value as database on the dialect implementation when registering one of them. PostgreSQL and Redshift cannot read another database.
  • includeProcedureCatalog (boolean; optional). Choose false for metadata updates, renames and deletes, or when the full native implementation and argument types are already verified. Choose true to discover procedures or inspect unknown signatures. External MCP defaults to true; Nash requires an explicit choice. Apply validates explicit definitions without catalog derivation.

astrato_semantic_layer_apply_data_action_change

Section titled “astrato_semantic_layer_apply_data_action_change”
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • preparedTarget (string or null; required; at least 1 character). Exact target returned by prepare, or null for creation.
  • expectedRevision (integer; required; at least 0)
  • change (object (5 shapes); required; shape chosen by operation: create, replace, update, rename, delete)
    • operation (string; required; one of create, replace, update, rename, delete)
    • name (string; required; at least 1 character; matches \S)
    • definition (object (3 shapes); required when operation is create or replace; shape chosen by kind: table, storedProcedure, virtualProcedure). Fields: kind, description, categories, parameters, fields, returns, implementation.
    • patch (object; required when operation is update)
      • description (string or null; optional)
      • categories (array of string or null; optional). Unique, nonblank labels the Workflows list groups by. An empty array or null clears them.
      • parameters (array of object or null; optional)
        • name (string; required; at least 1 character; matches \S)
        • dataType (string; required; at least 1 character; matches \S)
        • description (string; optional)
        • reference (object; optional)
        • default (string or number or boolean or null or array of string or number or boolean or null; optional)
        • nullable (boolean; optional)
        • evaluation (string; optional; one of sql, data)
      • fields (map of string to object or null; optional)
      • returns (object or null; optional)
        • fields (map of string to object; required)
      • implementation (object; optional)
        • view (string; optional; at least 1 character; matches \S)
        • operation (string; optional; one of insert, update, delete)
        • keys (map of string to object; optional)
        • values (map of string to object; optional)
        • bindings (map of string to object; optional)
        • dialects (map of string to object; optional)
        • transaction (boolean; optional)
        • batch (object; optional)
          • mode (string; required; one of perItem, set)
        • result (object; optional)
          • mode (string; required; one of rows, scalar, affectedRows, none)
          • statement (string; optional; at least 1 character; matches \S)
          • field (string; optional; at least 1 character; matches \S)
          • encoding (string; optional; one of json, string)
          • nativeDataType (string; optional; at least 1 character; matches \S)
        • expectRows (integer; optional; at least 0)
    • newName (string; required when operation is rename; at least 1 character; matches \S)
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • name (string; required; at least 1 character). Exact name of a data action in the published layer.
  • arguments (array of map of string to any; required; 1 to 1000 items). One object of named parameter values per invocation, in order; [{}] runs a parameterless action once. Omit a parameter only when it declares a default. A list value is one parameter value, not several invocations. Send decimals as text to keep their precision.
  • confirm (boolean; optional). Omit or false to get a preview and run nothing. Send true only after the user has approved this action with these arguments.
  • previewToken (string; optional; at least 1 character). Required with confirm true: the previewToken the preview returned for exactly this action and these arguments. The run is refused if the action, the arguments or the published layer differ from the preview, so the user approves what runs.
  • debug (boolean; optional). Capture authorized model and query inputs as a caller-scoped MCP replay resource. Read debugReplay.resourceUri with resources/read; result rows and request credentials are excluded.
  • responseBudgetBytes (integer; optional; 4096 to 262,144). Optional Astrato query data budget in serialized UTF-8 bytes; default 49152. Not a token count or MCP capability. Follow nextOffset with the same query, parameters and orderBy. Rows are never cut; if one cannot fit, request a larger budget or select fewer columns. Applies to executed results, not dry-run SQL.
  • parameters (object; optional). Execution-only overrides. all is keyed by parameter name and reaches every selection and filter group that declares it; measures is keyed by the BQ measure selection key, then the declared parameter name; filters and resultFilters by parameter name; associativeFilters by branch name then parameter name; drillLevels by dimension selection key. Omitted values retain declared defaults. Never copy these values into a saved definition.
    • all (map of string to string or number or boolean; optional). Values by parameter name for every measure selection, filters and resultFilters group that declares the name; groups that do not declare it are left alone. The simplest way to set a window shared by several measures, and the only way to set a view parameter, including on a view reached through a join; a value bound to the user wins over it. A value under measures, filters or resultFilters for one selection or group wins over this one.
    • measures (map of string to map of string to string or number or boolean; optional)
    • filters (map of string to string or number or boolean; optional)
    • resultFilters (map of string to string or number or boolean; optional)
    • associativeFilters (map of string to map of string to string or number or boolean; optional)
    • drillLevels (map of string to object; optional). The level a drill-through dimension selection groups by, keyed by its selection key (the string index for an array of selections). The value is one of that selection’s drillLevels references, or the field it groups by. Omitted, the first level is used. Choose the level the user asked to break the answer down by: “sales by channel” on a question grouped by a drill-through with a Channel level executes that question with Channel.
  • queryTimeout (integer; optional; 120 to 600). Engine timeout for each attempt in whole seconds, from 120 to 600. Default 120. Allow the MCP call at least twice this value plus retry delay; one transient failure may run the query again.
  • semanticLayerId (UUID string; optional). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • id (string; required). Business question id from astrato_semantic_layer_list_questions.
  • limit (integer; optional; 1 to 1000). Maximum rows for this page. Defaults to every row the question’s own topN keeps, Others row included, otherwise the standard page size. A question that stores a topN is never read beyond it, so a larger value is clamped rather than honoured.
  • offset (integer; optional; at least 0). Row to start from. Use it with the response’s totalRecords to read the rest of a capped result.
  • dryRun (boolean; optional). When true, compile the SQL this exact call would run and return it as statement, with the result columns, without running anything. Use it when the SQL is wanted before or instead of running the query; an execution already returns the SQL it ran.
  • draft (object; optional). Listed only where Deployment Region authoring is enabled. Opt in to an exact saved draft using revision and headToken from the layer read/save. Omit for published behavior. Prepare returns draft only when supported by this connection; draftUnavailable means the returned catalogue is published, so omit draft when executing it. Repeat the returned draft unchanged for preparation, dryRun, execution and pagination. A changed draft or lost execution capability requires preparing again; draft execution never falls back silently.
    • revision (integer; required; at least 0)
    • headToken (string; required; 1 to 1024 characters)

These tools are described in Manage Data Apps. They are listed only where app publishing is enabled. astrato_dashboard_freeform_update takes audience, expireAt, embedding and grantPublicDataAccess only where publication access settings are enabled; otherwise its schema leaves them out.

astrato_semantic_layer_benchmark_questions

Section titled “astrato_semantic_layer_benchmark_questions”
  • semanticLayerId (string; optional; at least 1 character). Required: this server has no default layer. Semantic layer id from astrato_semantic_layer_list; pass name there to find a layer.
  • questionIds (array of string; optional; at most 25 items). Stored question ids to run, from astrato_semantic_layer_list_questions. Omit to run every question in the layer, up to the cap. Send the previous run’s notIncludedQuestionIds here to cover the questions it did not reach.
  • maxQuestions (integer; optional; 1 to 25). Most questions to run in this call.
  • profile (boolean; optional). Profile the slow questions after the timed runs, to explain them. Defaults to true; false times the questions and reads no query profiles.
  • filterValues (integer; optional; 0 to 5). Run each question that answered a second time, filtered to each of this many of the most common values of the dimension the layer’s questions use most, as a dashboard filter would. Defaults to 3; 0 runs no filtered runs. Those runs appear under results[].filtered and are not scored.

Scope: publication:write.

  • name (string; required; 1 to 200 characters)
  • labels (array of string; optional; at most 20 items; each at most 50 characters)
  • semanticLayerId (UUID string; required)
  • idempotencyKey (string; required; 1 to 200 characters)

Scope: publication:write.

  • dashboardId (UUID string; required). Opaque dashboard ID returned by a Data App tool.
  • name (string; optional; 1 to 200 characters)
  • labels (array of string; optional; at most 20 items; each at most 50 characters)
  • audience (string; optional; one of authenticated, public). Listed only where publication access settings are enabled.
  • expireAt (date-time string or null; optional). Listed only where publication access settings are enabled.
  • embedding (object; optional). Listed only where publication access settings are enabled.
    • enabled (boolean; required)
    • allowedDomains (array of string; required; at most 100 items; each at most 253 characters)
  • grantPublicDataAccess (boolean; optional). Listed only where publication access settings are enabled. true grants anybody read on this app’s semantic layer and data connection, so public viewers’ data requests are not refused. Send it with audience public, or alone for an app already public.
  • hosting (object (2 shapes); optional; shape chosen by mode: data-node, custom)
    • mode (string; required; one of data-node, custom)
    • deploymentBindingId (string; required when mode is custom; 1 to 256 characters)
  • expectedVersion (integer; required; greater than 0). Data App version most recently read by the caller.

Scope: publication:read.

  • cursor (string; optional; at most 4096 characters)
  • limit (integer; optional; 1 to 100)

Scope: publication:read.

  • dashboardId (UUID string; required). Opaque dashboard ID returned by a Data App tool.
  • includeHosting (boolean; optional)

Scope: publication:write.

  • dashboardId (UUID string; required). Opaque dashboard ID returned by a Data App tool.
  • expectedVersion (integer; required; greater than 0). Data App version most recently read by the caller.

Scope: publication:publish.

  • dashboardId (UUID string; required). Opaque dashboard ID returned by a Data App tool.
  • expectedVersion (integer; required; greater than 0). Data App version most recently read by the caller.

Scope: publication:manage-access.

  • resourceType (string; required; always dashboard-freeform). Supported securable Astrato resource type. Rediscover the tool schema for new types.

Scope: publication:manage-access.

  • resourceType (string; required; always dashboard-freeform). Supported securable Astrato resource type. Rediscover the tool schema for new types.
  • resourceId (UUID string; required). Opaque resource ID returned by that resource capability.

Scope: publication:manage-access.

  • resourceType (string; required; always dashboard-freeform). Supported securable Astrato resource type. Rediscover the tool schema for new types.
  • resourceId (UUID string; required). Opaque resource ID returned by that resource capability.
  • subjectKind (string; required; one of user, group, tenant)
  • subjectId (UUID string; optional)
  • permission (string; required; one of view, manage, publish, manage_access, delete)

Scope: publication:manage-access.

  • resourceType (string; required; always dashboard-freeform). Supported securable Astrato resource type. Rediscover the tool schema for new types.
  • resourceId (UUID string; required). Opaque resource ID returned by that resource capability.
  • aclEntryId (UUID string; required)

These tools are described in External agents using App Builder. They are listed only where App Builder is enabled.

Scope: workspace:read.

  • search (string; optional; at most 200 characters)
  • offset (integer; optional; at least 0; default 0)
  • limit (integer; optional; 1 to 50; default 20)

Scope: workspace:write.

  • appId (UUID string; optional)
  • semanticLayerId (UUID string; optional). The semantic layer a new app reads; required to create one, and ignored when appId opens an existing app. Nash passes the layer in its context when this is omitted.
  • name (string; optional; 1 to 200 characters)
  • idempotencyKey (string; optional; 1 to 200 characters)
  • request (string; optional; 1 to 8000 characters). For a Nash-to-Builder handoff, preserve the self-contained user request and agreed choices. No secrets or query rows. The user reviews it and explicitly continues after opening Builder; never start source reads before that.

Scope: workspace:read.

  • appId (UUID string; required)
  • paths (array of string; optional; at most 8 items)
  • offset (integer; optional; at least 0). A nextOffset above 0 continues one file: send only that path. 0 reads every path from its start.

Scope: workspace:write.

  • appId (UUID string; required)
  • generation (integer; required; greater than 0). Use the generation from the latest completed edit, restore or execute result, or read.lease.generation from a completed source read; never guess or silently adopt a replacement lease.
  • expectedRevision (integer; required; greater than 0). Use the revision from the latest completed edit, restore or execute result, or read.revision from a completed source read. Required for every browser execute action.
  • edits (array of object (4 shapes); required; 1 to 128 items)
    • type (string; required; one of write, delete, rename, patch)
    • path (string; required)
    • content (string; required when type is write)
    • to (string; required when type is rename)
    • oldText (string; required when type is patch)
    • newText (string; required when type is patch)

Scope: workspace:read.

  • appId (UUID string; required)
  • revision (integer; optional; greater than 0)
  • before (integer; optional; greater than 0)

Scope: workspace:write.

  • appId (UUID string; required)
  • generation (integer; required; greater than 0). Use the generation from the latest completed edit, restore or execute result, or read.lease.generation from a completed source read; never guess or silently adopt a replacement lease.
  • expectedRevision (integer; required; greater than 0). Use the revision from the latest completed edit, restore or execute result, or read.revision from a completed source read. Required for every browser execute action.
  • revision (integer; required; greater than 0)

Scope: workspace:write.

  • appId (UUID string; required)
  • generation (integer; required; greater than 0). Use the generation from the latest completed edit, restore or execute result, or read.lease.generation from a completed source read; never guess or silently adopt a replacement lease.
  • expectedRevision (integer; required; greater than 0). Use the revision from the latest completed edit, restore or execute result, or read.revision from a completed source read. Required for every browser execute action.
  • action (object (5 shapes); required; shape chosen by type: build, inspect, command, interact, sequence)
    • type (string; required; one of build, inspect, command, interact, sequence)
    • command (string; required when type is command; one of npm, node)
    • args (array of string; required when type is command; at most 40 items; each at most 2000 characters)
    • action (object (6 shapes); required when type is interact; shape chosen by type: click, clickAt, fill, scroll, navigate, viewport)
      • type (string; required; one of click, clickAt, fill, scroll, navigate, viewport)
      • ref (string; required when type is click or fill; matches ^e[1-9][0-9]*-[1-9][0-9]*$)
      • screenshot (string; required when type is clickAt; matches ^s[0-9a-f]{8}-[1-9][0-9]*$). screenshotId from the inspection whose image you measured. It covers one action: after any other interaction or change to the preview, inspect again.
      • x (integer; required when type is clickAt; 0 to 1000). Position across that image: 0 at its left edge, 1000 at its right edge, at any image size.
      • y (integer; required when type is clickAt; 0 to 1000). Position down that image: 0 at its top edge, 1000 at its bottom edge, at any image size.
      • value (string; required when type is fill; at most 1024 characters)
      • x (integer; required when type is scroll; -2000 to 2000). Horizontal scroll delta in pixels; use 0 for vertical scrolling.
      • y (integer; required when type is scroll; -2000 to 2000). Vertical scroll delta in pixels.
      • ref (string; optional; matches ^e[1-9][0-9]*-[1-9][0-9]*$). Only when type is scroll. Current inspected element to scroll; omit to scroll the preview window.
      • hash (string; required when type is navigate; at most 512 characters; matches ^#[^\u0000-\u0020]*(?![\s\S]))
      • width (integer; required when type is viewport; 320 to 1920)
      • height (integer; required when type is viewport; 240 to 1440)
    • steps (array of object (5 shapes); required when type is sequence; 1 to 6 items)
      • type (string; required; one of click, fill, scroll, navigate, viewport)
      • ref (string; optional; matches ^e[1-9][0-9]*-[1-9][0-9]*$). Only when type is click or fill. Control from the latest inspection. Send ref or label.
      • label (string; optional; 1 to 160 characters). Only when type is click or fill. The control’s exact label, ignoring case. Send ref or label. Replaces every earlier ref.
      • role (string; optional; 1 to 40 characters). Only when type is click or fill. With label: the control’s role, when several share the label.
      • value (string; required when type is fill; at most 1024 characters)
      • x (integer; required when type is scroll; -2000 to 2000). Horizontal scroll delta in pixels; use 0 for vertical scrolling.
      • y (integer; required when type is scroll; -2000 to 2000). Vertical scroll delta in pixels.
      • ref (string; optional; matches ^e[1-9][0-9]*-[1-9][0-9]*$). Only when type is scroll. Current inspected element to scroll; omit to scroll the preview window.
      • hash (string; required when type is navigate; at most 512 characters; matches ^#[^\u0000-\u0020]*(?![\s\S]))
      • width (integer; required when type is viewport; 320 to 1920)
      • height (integer; required when type is viewport; 240 to 1440)