Written for: For developers
MCP tool reference
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.
Get the exact input schema
Section titled “Get the exact input schema”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,annotationsandinputSchema, a JSON Schema whoserequiredarray 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$refto read them. tools/listlists every tool the environment registers, whatever your scopes, so a data-only client holdingdata:querycan read it although it cannot callastrato_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.
Endpoint
Section titled “Endpoint”- 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.
Capabilities
Section titled “Capabilities”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_*andastrato_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_contextreports 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.
Capability identifiers
Section titled “Capability identifiers”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.
The usual path
Section titled “The usual path”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_createcreates an empty, unpublished semantic layer on a datasource.astrato_semantic_layer_apply_measure_changeadds or changes a measure in the layer’s draft.astrato_semantic_layer_preview_publishshows everything publishing would send, including other people’s changes. Show it to the user and publish only once they approve it.astrato_semantic_layer_publishpublishes the layer, so queries and Data Apps can use it. Pass theexpectedRevisionof the preview the user approved.astrato_dashboard_freeform_createreserves 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_ |
admin: |
List the tenant’s users for an administrator, each row carrying why it cannot be changed where that applies. |
astrato_ |
admin: |
List the tenant’s licence teams, whose ids a status or team change has to be aimed at. |
astrato_ |
admin: |
Change one user’s role, sign-in status or licence team, reporting which of those writes landed. |
astrato_ |
workspace: |
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 visible Canvas dashboards in bounded upstream pages, optionally through one collection lens. |
astrato_ |
workspace: |
Update one collection’s name and description. |
astrato_ |
workspace: |
Delete one collection after explicit user confirmation. |
astrato_ |
workspace: |
Update one Canvas dashboard’s name and description. |
astrato_ |
workspace: |
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_ |
workspace: |
Consume the matching preparation token, recheck the affected users, and move the Canvas dashboard to Removed when the impact is unchanged. |
astrato_ |
workspace: |
Add or remove one Canvas dashboard from the current user’s Starred view. |
astrato_ |
workspace: |
Add or remove one Canvas dashboard from one collection. |
astrato_ |
workspace: |
List the pinboards the caller can open. |
astrato_ |
workspace: |
Read a board document and its revision. |
astrato_ |
workspace: |
Create an empty personal or collection board. |
astrato_ |
workspace: |
Pin a stored business question to the end of a board. |
astrato_ |
workspace: |
Remove a pin from a board and its layouts after explicit user confirmation. |
astrato_ |
workspace: |
Replace a whole board document. Use it to rename a board, reorder or resize pins, or change display settings. |
astrato_ |
workspace: |
Delete a board after explicit user confirmation. |
astrato_ |
workspace: |
Create from non-secret metadata, returning a short-lived browser action when credentials are required. |
astrato_ |
workspace: |
Read pending, completed or failed state and a credential-free receipt for the initiating user. |
astrato_ |
workspace: |
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_ |
workspace:; sl: 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_ |
sl: |
List the tenant data connections a semantic layer can bind to, with validity and the revision later calls require. |
astrato_ |
sl: |
Return the driver descriptors that define the flow: authentication methods, settings fields, catalog levels and their vendor labels. |
astrato_ |
workspace: |
Prepare non-secret metadata and return a preparation ID and revision. |
astrato_ |
sl: |
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_ |
workspace: |
Open a bound secure form for create/update, or commit rename, source selection and deletion; retest reports stored validity. |
astrato_ |
workspace: |
Read safe per-user settings, validity and the mapping revision of a dynamic connection. |
astrato_ |
workspace: |
Open a bound secure form to add or update per-user settings, or delete selected mappings directly. |
astrato_ |
sl: |
Server, permission, and default-layer context. Call this first for structural workflows. |
astrato_ |
sl: |
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_ |
sl: |
List the datasources a new semantic layer can bind to, without returning connection settings. |
astrato_ |
sl: |
Create an empty, unpublished semantic layer on one datasource and return its actual name and semanticLayerId. |
astrato_ |
sl: |
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_ |
sl: |
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_ |
sl: |
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_ |
sl: |
One page of views, fields, joins, or items (cursor + limit, max 50). |
astrato_ |
sl: |
Search views, fields, joins, items, and functions. |
astrato_ |
sl: |
Search the authorized physical-source catalog and return exact schema, table, and column identifiers. |
astrato_ |
sl: |
Refresh loaded source metadata or one schema/table branch without discovering unrelated branches. |
astrato_ |
sl: |
Run shared semantic validation, including datasource aggregation support when live capability discovery succeeds. |
astrato_ |
sl: |
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_ |
sl: |
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_ |
sl: |
Resolve several measure, dimension and business-question intents together, reuse exact existing use cases, and return one consolidated ambiguity list. |
astrato_ |
sl: |
Resolve one measure change; optionally compact repeated metadata or return current-draft engine suggestions and statement-only compiled SQL. |
astrato_ |
sl: |
Resolve one dimension change; optionally return current-draft engine suggestions. |
astrato_ |
sl: |
Resolve existing views and physical-source concepts for typed view and field authoring. |
astrato_ |
sl: |
Export the exact current validated draft as Apache Ossie YAML without publishing. Returns portability diagnostics and a resource link. |
astrato_ |
sl: |
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_ |
sl: |
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_ |
sl: |
Discover Snowflake semantic views on a datasource. |
astrato_ |
sl: |
Convert a Snowflake view without touching the draft. |
astrato_ |
sl: |
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_ |
sl: |
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_ |
sl: |
Report whether a session is still based on the current draft revision. |
astrato_ |
sl: |
Preview pending changes and validation before committing. |
astrato_ |
sl: |
Check the database for schema drift; never publishes. fresh: false reads the stored result and lastCheck without checking. |
astrato_ |
sl: |
Apply one revision-bound typed fix returned by the latest source check; never publishes. |
astrato_ |
sl: |
Open an edit session pinned to the current draft revision. |
astrato_ |
sl: |
Apply one structured edit. Changes remain in the session until commit. |
astrato_ |
sl: |
Create, replace, patch, rename, or delete one measure atomically: validate and commit in one call. |
astrato_ |
sl: |
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_ |
sl: |
Atomically add, copy, edit, rename, or delete views and their fields without publishing. |
astrato_ |
sl: |
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_ |
sl: |
Discard the session and its pending changes. |
astrato_ |
sl: |
Commit the session as a new draft revision. Auto-rebases non-overlapping changes. |
astrato_ |
sl: |
Create a named version of the current draft head. It has no expected-revision guard. |
astrato_ |
sl:, sl: |
Apply a previewed Snowflake import atomically. |
astrato_ |
sl:, sl: |
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_ |
sl: |
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_ |
sl: |
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_ |
sl: |
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_ |
sl: |
List stored business questions. See the Business questions guide. |
astrato_ |
sl: |
Read one complete canonical stored question. |
astrato_ |
sl: |
List the join suggestions the editor shows, best first, each with its confidence and the exact join to create. |
astrato_ |
sl: and data: |
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_ |
sl: |
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_ |
sl: |
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_ |
sl: |
Read one current target and the reusable dimensions and measures available for a revision-bound change. |
astrato_ |
sl: |
Atomically create, replace, rename, or delete one stored question without publishing. |
astrato_ |
sl: |
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_ |
sl: |
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_ |
sl: |
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_ |
sl: |
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_ |
sl: |
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_ |
sl: |
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_ |
data: |
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_ |
sl: |
Private Preview, feature-gated. Store the draft workflow policy explicitly; optionally reject a stale draft revision. Publishes nothing. |
astrato_ |
data: |
Compile and execute a stored question against the published semantic layer, a page at a time via limit and offset. |
astrato_ |
data: |
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_ |
sl: |
List datasets: named collections of existing dimensions and measures, with categories and member counts. |
astrato_ |
sl: |
Read one dataset, its members in display order, and any that are no longer in the layer. |
astrato_ |
sl: |
Read one current dataset and the dimensions and measures available to it. Writes nothing. |
astrato_ |
sl: |
Atomically create, replace, update members of, rename, or delete one dataset. Filters set in the editor are kept; this tool cannot author them. |
astrato_ |
sl: |
List stored set and regular filters with their type, a set filter’s target, and the questions that use them. |
astrato_ |
sl: |
Read one stored filter: a set filter’s target and branches or a regular filter’s conditions, and the questions that use it. |
astrato_ |
sl: |
Read one current stored filter and what is available to it. Writes nothing. |
astrato_ |
sl: |
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: |
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: |
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_ |
sl: |
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_ |
sl: |
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.
-
Call
astrato_data_prepare_querywithsemanticLayerId,query: {}andanalyzeCandidates: true. Review the starting context and the candidate analysis forSales. -
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. -
Add
Tagand callastrato_data_prepare_querywith the complete query:{"measures": [{ "key": "sales", "reference": { "measure": "Sales" } }],"dimensions": [{ "key": "tag", "reference": { "dimension": "Tag" } }]} -
Review the updated diagnostics, then pass that same query and
semanticLayerIdtoastrato_data_execute_query. Keep any filters, parameter overrides and local definitions identical between preparation and execution. AqueryAnalysisRejectedrefusal 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
COUNTwithdistinct: trueof 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_qualitychecks 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.
Custom-group dimensions
Section titled “Custom-group dimensions”When you author a custom-group (mapping) dimension, each rule is checked for missing references,
invalid filter values, formula conditions and parameter defaults. Diagnostics identify the dimension
and the affected rule, such as groups[0].filter.f1.arguments[1]. Fix the reported reference or value
before retrying the change. Rules that cannot currently be converted for publication are also
reported as errors.
Set each rule’s output and the optional default as a value with a compatible dataType.
In the dimension’s property panel, Returns updates all output types. Incompatible values stay
visible for repair. 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.
Arguments by tool
Section titled “Arguments by tool”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”astrato_workspace_list_collections
Section titled “astrato_workspace_list_collections”Takes no arguments.
astrato_workspace_list_canvas_dashboards
Section titled “astrato_workspace_list_canvas_dashboards”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 ofname,-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 ofall,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 ofdraft,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.
astrato_workspace_update_collection
Section titled “astrato_workspace_update_collection”id(UUID string; required). Exact collection id returned byastrato_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.
astrato_workspace_delete_collection
Section titled “astrato_workspace_delete_collection”id(UUID string; required). Exact collection id returned byastrato_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 byastrato_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 byastrato_workspace_list_canvas_dashboards.collectionId(UUID string; required). Exact collection id returned byastrato_workspace_list_collections.included(boolean; required). True to add the dashboard; false to remove it from the collection.
astrato_pinboard_list
Section titled “astrato_pinboard_list”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.
astrato_pinboard_get
Section titled “astrato_pinboard_get”pinboardId(string; optional). Board id fromastrato_pinboard_list. Omit for the caller’s default board.
astrato_pinboard_create
Section titled “astrato_pinboard_create”name(string; required). Board name.collectionId(UUID string; optional). Collection to create the board in, which needs edit access. Omit for a personal board.
astrato_pinboard_add_pin
Section titled “astrato_pinboard_add_pin”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.
astrato_pinboard_remove_pin
Section titled “astrato_pinboard_remove_pin”slug(string; required). Pin slug, a key of the documentpins.pinboardId(string; optional). Omit for the caller’s default board.
astrato_pinboard_replace_document
Section titled “astrato_pinboard_replace_document”document(object; required). The complete document fromastrato_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 revisionastrato_pinboard_getreturned. 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.
astrato_pinboard_delete
Section titled “astrato_pinboard_delete”pinboardId(string; required). Board id fromastrato_pinboard_list.
astrato_management_directory_list_users
Section titled “astrato_management_directory_list_users”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.
astrato_management_license_list_teams
Section titled “astrato_management_license_list_teams”Takes no arguments.
astrato_management_directory_update_user
Section titled “astrato_management_directory_update_user”userId(UUID string; required). Exact Astrato user id fromastrato_management_directory_list_users. Not an email address.role(string; optional; one ofadministrator,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, fromastrato_management_license_list_teams.
astrato_dashboard_canvas_update
Section titled “astrato_dashboard_canvas_update”canvasDashboardId(UUID string; required). Exact workbook id returned byastrato_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.
astrato_dashboard_canvas_prepare_deletion
Section titled “astrato_dashboard_canvas_prepare_deletion”canvasDashboardId(UUID string; required). Exact workbook id returned byastrato_workspace_list_canvas_dashboards.
astrato_dashboard_canvas_delete
Section titled “astrato_dashboard_canvas_delete”canvasDashboardId(UUID string; required). Exact workbook id returned byastrato_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 precedingastrato_dashboard_canvas_prepare_deletioncall. Confirm that impact with the user before deleting.
Data connections, import and queries
Section titled “Data connections, import and queries”astrato_data_create_connection
Section titled “astrato_data_create_connection”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 ofnone,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 ofpassword,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.
astrato_data_get_secure_action_status
Section titled “astrato_data_get_secure_action_status”actionId(UUID string; required). Secure action id returned byastrato_data_create_connection.
astrato_data_list_connections
Section titled “astrato_data_list_connections”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 byoperation:upsert,delete)operation(string; required; one ofupsert,delete)users(array of object; required whenoperationisupsert; 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 whenoperationisdelete; 1 to 100 items)
astrato_data_describe_connection_drivers
Section titled “astrato_data_describe_connection_drivers”driverId(string; optional; at least 1 character). Limit the result to one driver.
astrato_data_prepare_connection
Section titled “astrato_data_prepare_connection”driverId(string; required; at least 1 character). Driver id fromastrato_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 fromastrato_data_list_connectionsor 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.
astrato_data_browse_connection_catalog
Section titled “astrato_data_browse_connection_catalog”connectionId(UUID string; optional). A saved connection to browse.preparationId(UUID string; optional). A preparation fromastrato_data_prepare_connection.level(string; required; one ofdatabase,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.
astrato_data_apply_connection
Section titled “astrato_data_apply_connection”expectedRevision(integer; required; at least 0)change(object (7 shapes); required; shape chosen byoperation:create,update,configure,rename,select-source,retest,delete)operation(string; required; one ofcreate,update,configure,rename,select-source,retest,delete)preparationId(UUID string; required whenoperationiscreateorupdate)name(string; optional; 1 to 200 characters). Only whenoperationiscreateorconfigure.source(object; required whenoperationisselect-source). Only whenoperationiscreateorselect-source.database(string; optional; at least 1 character)schema(string; optional; at least 1 character)
context(map of string to string; optional). Only whenoperationiscreateorupdate.connectionId(UUID string; required whenoperationisupdate,configure,rename,select-source,retestordelete)context(object; optional). Only whenoperationisconfigure.role(string; optional; at most 1000 characters)warehouse(string; optional; at most 1000 characters)
source(object; optional). Only whenoperationisconfigure.database(string; optional; 1 to 1000 characters)schema(string; optional; at most 1000 characters)
exitNode(object; optional). Only whenoperationisconfigure.enabled(boolean; required)profile(string; optional; 1 to 1000 characters)
newName(string; required whenoperationisrename; 1 to 200 characters)
astrato_data_prepare_import
Section titled “astrato_data_prepare_import”datasourceId(UUID string; optional). The data connection to import into, fromastrato_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.
astrato_data_import_csv
Section titled “astrato_data_import_csv”datasourceId(UUID string; optional). The data connection to import into, fromastrato_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 fromastrato_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 throughastrato_data_prepare_import.fileName(string; optional; 1 to 255 characters). The original file name, used for the default table name. An upload throughastrato_data_prepare_importdoes 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.
astrato_get_context
Section titled “astrato_get_context”detail(fulloridentity; optional). Omit it or usefullfor the complete Nash context. Useidentityfor 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 isnulland named inidentity.omittedFields; usefullwhen that display value is needed.
astrato_data_list_sources
Section titled “astrato_data_list_sources”Takes no arguments.
astrato_data_prepare_query
Section titled “astrato_data_prepare_query”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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 matcherastrato_semantic_layer_search_fieldsuses; 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 ofsemantic,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 whenastrato_semantic_layer_create_next_questionscreated 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 ofmultiplicative,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 asastrato_semantic_layer_prepare_question_changereturned 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 ofascending,descending)
preferredCharts(array of object; optional). Advisory renderer suggestions only. They never change query validity.type(string; required; one ofline,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 ofascending,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; alwaysindependent). 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 withtopN: send one or the other.showOthers(boolean; optional)othersPosition(string; optional; one ofdefault,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)
astrato_data_execute_query
Section titled “astrato_data_execute_query”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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 whenastrato_semantic_layer_create_next_questionscreated 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 ofmultiplicative,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 asastrato_semantic_layer_prepare_question_changereturned 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 ofascending,descending)
preferredCharts(array of object; optional). Advisory renderer suggestions only. They never change query validity.type(string; required; one ofline,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 ofascending,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; alwaysindependent). 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 withtopN: send one or the other.showOthers(boolean; optional)othersPosition(string; optional; one ofdefault,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)
Semantic layers
Section titled “Semantic layers”astrato_support_search_public_knowledge
Section titled “astrato_support_search_public_knowledge”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.
astrato_support_create_case
Section titled “astrato_support_create_case”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 fromastrato_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;escalateonly)issueType(string; required; one ofbug,feature)issueOrigin(string; required; one ofastrato_bug,unknown,feature_request)evidence(object; required). One field,error(string; required; one ofprovided,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 ofrequested_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.
astrato_semantic_layer_list
Section titled “astrato_semantic_layer_list”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, fromastrato_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.
astrato_semantic_layer_create
Section titled “astrato_semantic_layer_create”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 fromastrato_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.
astrato_semantic_layer_update
Section titled “astrato_semantic_layer_update”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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.
astrato_semantic_layer_set_visibility
Section titled “astrato_semantic_layer_set_visibility”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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.
astrato_semantic_layer_set_writeback_mode
Section titled “astrato_semantic_layer_set_writeback_mode”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_semantic_layer_list; pass name there to find a layer.mode(string; required; one ofdataSource,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.
astrato_semantic_layer_unlink_import_source
Section titled “astrato_semantic_layer_unlink_import_source”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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.
astrato_semantic_layer_export_ossie
Section titled “astrato_semantic_layer_export_ossie”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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 fromastrato_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 fromastrato_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_viewsuffix.
astrato_semantic_layer_preview_publish
Section titled “astrato_semantic_layer_preview_publish”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_semantic_layer_list; pass name there to find a layer.
astrato_semantic_layer_publish
Section titled “astrato_semantic_layer_publish”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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 fromastrato_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 fromastrato_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 fromastrato_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 fromastrato_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.
astrato_semantic_layer_get_summary
Section titled “astrato_semantic_layer_get_summary”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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 readfileVersionbefore parsing; the file name still readsv2whatever 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), asastrato_data_prepare_queryreports 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 ofdraft,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.
astrato_semantic_layer_get_details
Section titled “astrato_semantic_layer_get_details”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_semantic_layer_list; pass name there to find a layer.section(string; required; one ofviews,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.
astrato_semantic_layer_search
Section titled “astrato_semantic_layer_search”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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 fromastrato_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 fromastrato_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 fromastrato_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.
astrato_semantic_layer_validate
Section titled “astrato_semantic_layer_validate”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_semantic_layer_list; pass name there to find a layer.
astrato_semantic_layer_search_fields
Section titled “astrato_semantic_layer_search_fields”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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; default5)
astrato_semantic_layer_find_unused
Section titled “astrato_semantic_layer_find_unused”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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 fromastrato_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 offield,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 fromastrato_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 ofmeasure,dimension,businessQuestion)id(string; required; matches^[A-Za-z][A-Za-z0-9_]*$)operation(string; required whenentityismeasureordimension; one ofcreate,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 whenentityismeasureordimension.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 offield,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 whenentityisbusinessQuestion; one ofcreate,replace,patch,rename,delete)queries(array of object; optional; at most 24 items; default[]). Only whenentityisbusinessQuestion. 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 offield,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 fromastrato_semantic_layer_list; pass name there to find a layer.planId(UUID string; optional). Response-only plan id returned byastrato_semantic_layer_plan_authoring_batch.expectedRevision(integer; required; at least 0). Revision returned byastrato_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 ofmeasure,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 whenentityismeasure; shape chosen byoperation:create,replace,patch,delete,rename,duplicate). Same shapes aschangeinastrato_semantic_layer_apply_measure_change, except thatpatchhas its own fields here; read them from the input schema.change(object (6 shapes); required whenentityisdimension; shape chosen byoperation:create,replace,patch,delete,rename,duplicate). Same shapes aschangeinastrato_semantic_layer_apply_dimension_change.change(object (5 shapes); required whenentityisbusinessQuestion; shape chosen byoperation:create,replace,patch,rename,delete). Fields:operation,name,definition,ifExists,patch,newName,references.
astrato_semantic_layer_apply_view_change
Section titled “astrato_semantic_layer_apply_view_change”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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 ofview,field)change(object (8 shapes); required whenentityisview; shape chosen byoperation:create-table,create-sql,update-sql,create-inline,copy,rename,update,delete)operation(string; required; one ofcreate-table,create-sql,update-sql,create-inline,copy,rename,update,delete)name(string; required; at least 1 character)source(object; required whenoperationiscreate-table). Only whenoperationiscreate-tableorupdate.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 whenoperationiscreate-table; shape chosen bymode:all,only,all-except). Only whenoperationiscreate-tableorupdate.mode(string; required; one ofall,only,all-except)fields(array of string; required whenmodeisonlyorall-except; at least 1 item)
description(string; optional). Only whenoperationiscreate-table,create-sqlorcreate-inline.statement(string; required whenoperationiscreate-sqlorupdate-sql; at least 1 character)parameters(map of string to object; optional). Only whenoperationiscreate-sqlorupdate-sql.description(object (2 shapes); optional; shape chosen bymode:set,clear). Only whenoperationisupdate-sqlorupdate.mode(string; required; one ofset,clear)value(string; required whenmodeisset)
columns(array of object; required whenoperationiscreate-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 whenoperationiscreate-inline)newName(string; required whenoperationiscopyorrename; at least 1 character)filter(object or null; optional). Only whenoperationisupdate. 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 whenoperationisupdate.activeapplies 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.strictalso 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 whenoperationisupdate. 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 whenentityisfield; shape chosen byoperation:create,update,rename,delete)operation(string; required; one ofcreate,update,rename,delete)view(string; required; at least 1 character)name(string; required; at least 1 character)definition(object; required whenoperationiscreate). 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 whenoperationisupdate)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 whenoperationisrename; 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 fromastrato_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 byastrato_semantic_layer_prepare_measure_change. Prevents edits against stale context.change(object (6 shapes); required; shape chosen byoperation: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 ofcreate,replace,patch,delete,rename,duplicate)name(string; required; at least 1 character)definition(object; required whenoperationiscreateorreplace). Fields:description,label,categories,format,expression,inputs,nestedCalculation,periodComparison.patch(object; required whenoperationispatch). Fields:description,label,categories,format,parameters,calculation,periodComparison,aggregateOptions,filter.references(string; optional; one ofremove,keep). Only whenoperationisdelete. 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 whenoperationisrename; at least 1 character)references(string; optional; one ofupdate,keep). Only whenoperationisrename. 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 whenoperationisduplicate. 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 fromastrato_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 offield,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 fromastrato_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 byoperation: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 ofcreate,replace,patch,delete,rename,duplicate)name(string; required; at least 1 character)definition(object (6 shapes); required whenoperationiscreateorreplace; shape chosen bykind: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 whenoperationispatch)description(object (2 shapes); optional; shape chosen bymode:set,clear)mode(string; required; one ofset,clear)value(string; required whenmodeisset)
categories(object (2 shapes); optional; shape chosen bymode: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 ofset,clear)values(array of string; required whenmodeisset). 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 bymode:default,none,custom). Rejected on a drill-through, whose levels carry their own formatting.mode(string; required; one ofdefault,none,custom)pattern(string; required whenmodeiscustom; at least 1 character)
label(object (2 shapes); optional; shape chosen bymode: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 ofset,clear)value(string; required whenmodeisset)
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 ofcurrentYear,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 ofyear,quarter,month,week,day)periodEnd(string or null; optional; one oftoday,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 ofremove,keep). Only whenoperationisdelete. 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 whenoperationisrename; at least 1 character)references(string; optional; one ofupdate,keep). Only whenoperationisrename. 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 whenoperationisduplicate. 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 fromastrato_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 fromastrato_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 byastrato_semantic_layer_check_source_schema.expectedRevision(integer; required; at least 0). Current draft revision returned with the source-check diagnostics.
astrato_semantic_layer_begin_edit_session
Section titled “astrato_semantic_layer_begin_edit_session”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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 byastrato_semantic_layer_begin_edit_session.
astrato_semantic_layer_apply_edit
Section titled “astrato_semantic_layer_apply_edit”sessionId(string; required). MCP edit session id returned byastrato_semantic_layer_begin_edit_session.operation(string; required; one ofrename_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 byastrato_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 byastrato_semantic_layer_begin_edit_session.summary(string; optional). Revision summary to store in draft history.
astrato_semantic_layer_create_version
Section titled “astrato_semantic_layer_create_version”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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 byastrato_semantic_layer_begin_edit_session.
astrato_semantic_layer_list_questions
Section titled “astrato_semantic_layer_list_questions”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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.
astrato_semantic_layer_get_question
Section titled “astrato_semantic_layer_get_question”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_semantic_layer_list; pass name there to find a layer.id(string; required). Business question id fromastrato_semantic_layer_list_questions.
astrato_semantic_layer_suggest_questions
Section titled “astrato_semantic_layer_suggest_questions”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_semantic_layer_list; pass name there to find a layer.
astrato_semantic_layer_suggest_joins
Section titled “astrato_semantic_layer_suggest_joins”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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.
astrato_semantic_layer_suggest_dimensions
Section titled “astrato_semantic_layer_suggest_dimensions”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_semantic_layer_list; pass name there to find a layer.
astrato_semantic_layer_check_join_quality
Section titled “astrato_semantic_layer_check_join_quality”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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 fromastrato_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 fromastrato_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 byoperation:create,replace,patch,rename,delete)operation(string; required; one ofcreate,replace,patch,rename,delete)name(string; required; at least 1 character)definition(object; required whenoperationiscreateorreplace). Same fields asqueryinastrato_data_execute_query.ifExists(string; optional; one offail,skip,replace). Only whenoperationiscreate. 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 whenoperationispatch)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 ofdescription,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 whenoperationisrename; at least 1 character)references(string; optional; one ofremove,keep). Only whenoperationisdelete. 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 fromastrato_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 ofdrivers,gapToTarget,concentration,trend,comparePeriods,shareOfTotal,topN,outliers,distribution,related).kind: searchonly: the types to look for, default every one that applies to the question. Data checks always run.distributionshows 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 ofauto,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 requiresdata: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 ofmultiplicative,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 ofshapley,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.
astrato_semantic_layer_list_datasets
Section titled “astrato_semantic_layer_list_datasets”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_semantic_layer_list; pass name there to find a layer.
astrato_semantic_layer_get_dataset
Section titled “astrato_semantic_layer_get_dataset”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_semantic_layer_list; pass name there to find a layer.name(string; required; at least 1 character). Dataset name fromastrato_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 fromastrato_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 fromastrato_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 byoperation:create,replace,update,rename,delete)operation(string; required; one ofcreate,replace,update,rename,delete)name(string; required; at least 1 character)definition(object; required whenoperationiscreateorreplace)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 whenoperationisupdate)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 whenoperationisrename; at least 1 character)
astrato_semantic_layer_list_set_filters
Section titled “astrato_semantic_layer_list_set_filters”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_semantic_layer_list; pass name there to find a layer.
astrato_semantic_layer_get_set_filter
Section titled “astrato_semantic_layer_get_set_filter”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_semantic_layer_list; pass name there to find a layer.name(string; required; at least 1 character). Set filter name fromastrato_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 fromastrato_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 fromastrato_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 byoperation:create,replace,update,rename,delete)operation(string; required; one ofcreate,replace,update,rename,delete)name(string; required; at least 1 character)definition(object; required whenoperationiscreateorreplace)patch(object; required whenoperationisupdate)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 whenoperationisrename; 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 fromastrato_semantic_layer_list; pass name there to find a layer.
astrato_semantic_layer_list_data_actions
Section titled “astrato_semantic_layer_list_data_actions”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_semantic_layer_list; pass name there to find a layer.
astrato_semantic_layer_get_data_action
Section titled “astrato_semantic_layer_get_data_action”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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 fromastrato_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 oftable,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 fromastrato_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 byoperation:create,replace,update,rename,delete)operation(string; required; one ofcreate,replace,update,rename,delete)name(string; required; at least 1 character; matches\S)definition(object (3 shapes); required whenoperationiscreateorreplace; shape chosen bykind:table,storedProcedure,virtualProcedure). Fields:kind,description,categories,parameters,fields,returns,implementation.patch(object; required whenoperationisupdate)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 ofsql,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 ofinsert,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 ofperItem,set)
result(object; optional)mode(string; required; one ofrows,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 ofjson,string)nativeDataType(string; optional; at least 1 character; matches\S)
expectRows(integer; optional; at least 0)
newName(string; required whenoperationisrename; at least 1 character; matches\S)
astrato_semantic_layer_run_data_action
Section titled “astrato_semantic_layer_run_data_action”semanticLayerId(UUID string; optional). Required: this server has no default layer. Semantic layer id fromastrato_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.
astrato_semantic_layer_execute_question
Section titled “astrato_semantic_layer_execute_question”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 fromastrato_semantic_layer_list; pass name there to find a layer.id(string; required). Business question id fromastrato_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)
Data Apps and access
Section titled “Data Apps and access”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 fromastrato_semantic_layer_list; pass name there to find a layer.questionIds(array of string; optional; at most 25 items). Stored question ids to run, fromastrato_semantic_layer_list_questions. Omit to run every question in the layer, up to the cap. Send the previous run’snotIncludedQuestionIdshere 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 underresults[].filteredand are not scored.
astrato_dashboard_freeform_create
Section titled “astrato_dashboard_freeform_create”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)
astrato_dashboard_freeform_update
Section titled “astrato_dashboard_freeform_update”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 ofauthenticated,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 bymode:data-node,custom)mode(string; required; one ofdata-node,custom)deploymentBindingId(string; required whenmodeiscustom; 1 to 256 characters)
expectedVersion(integer; required; greater than 0). Data App version most recently read by the caller.
astrato_dashboard_freeform_list
Section titled “astrato_dashboard_freeform_list”Scope: publication:read.
cursor(string; optional; at most 4096 characters)limit(integer; optional; 1 to 100)
astrato_dashboard_freeform_get
Section titled “astrato_dashboard_freeform_get”Scope: publication:read.
dashboardId(UUID string; required). Opaque dashboard ID returned by a Data App tool.includeHosting(boolean; optional)
astrato_dashboard_freeform_delete
Section titled “astrato_dashboard_freeform_delete”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.
astrato_dashboard_freeform_unpublish
Section titled “astrato_dashboard_freeform_unpublish”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.
astrato_management_access_describe
Section titled “astrato_management_access_describe”Scope: publication:manage-access.
resourceType(string; required; alwaysdashboard-freeform). Supported securable Astrato resource type. Rediscover the tool schema for new types.
astrato_management_access_list
Section titled “astrato_management_access_list”Scope: publication:manage-access.
resourceType(string; required; alwaysdashboard-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.
astrato_management_access_grant
Section titled “astrato_management_access_grant”Scope: publication:manage-access.
resourceType(string; required; alwaysdashboard-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 ofuser,group,tenant)subjectId(UUID string; optional)permission(string; required; one ofview,manage,publish,manage_access,delete)
astrato_management_access_revoke
Section titled “astrato_management_access_revoke”Scope: publication:manage-access.
resourceType(string; required; alwaysdashboard-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)
App Builder
Section titled “App Builder”These tools are described in External agents using App Builder. They are listed only where App Builder is enabled.
astrato_app_builder_list
Section titled “astrato_app_builder_list”Scope: workspace:read.
search(string; optional; at most 200 characters)offset(integer; optional; at least 0; default0)limit(integer; optional; 1 to 50; default20)
astrato_app_builder_open
Section titled “astrato_app_builder_open”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.
astrato_app_builder_read
Section titled “astrato_app_builder_read”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.
astrato_app_builder_edit
Section titled “astrato_app_builder_edit”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 ofwrite,delete,rename,patch)path(string; required)content(string; required whentypeiswrite)to(string; required whentypeisrename)oldText(string; required whentypeispatch)newText(string; required whentypeispatch)
astrato_app_builder_versions
Section titled “astrato_app_builder_versions”Scope: workspace:read.
appId(UUID string; required)revision(integer; optional; greater than 0)before(integer; optional; greater than 0)
astrato_app_builder_restore
Section titled “astrato_app_builder_restore”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)
astrato_app_builder_execute
Section titled “astrato_app_builder_execute”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 bytype:build,inspect,command,interact,sequence)type(string; required; one ofbuild,inspect,command,interact,sequence)command(string; required whentypeiscommand; one ofnpm,node)args(array of string; required whentypeiscommand; at most 40 items; each at most 2000 characters)action(object (6 shapes); required whentypeisinteract; shape chosen bytype:click,clickAt,fill,scroll,navigate,viewport)type(string; required; one ofclick,clickAt,fill,scroll,navigate,viewport)ref(string; required whentypeisclickorfill; matches^e[1-9][0-9]*-[1-9][0-9]*$)screenshot(string; required whentypeisclickAt; 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 whentypeisclickAt; 0 to 1000). Position across that image: 0 at its left edge, 1000 at its right edge, at any image size.y(integer; required whentypeisclickAt; 0 to 1000). Position down that image: 0 at its top edge, 1000 at its bottom edge, at any image size.value(string; required whentypeisfill; at most 1024 characters)x(integer; required whentypeisscroll; -2000 to 2000). Horizontal scroll delta in pixels; use 0 for vertical scrolling.y(integer; required whentypeisscroll; -2000 to 2000). Vertical scroll delta in pixels.ref(string; optional; matches^e[1-9][0-9]*-[1-9][0-9]*$). Only whentypeisscroll. Current inspected element to scroll; omit to scroll the preview window.hash(string; required whentypeisnavigate; at most 512 characters; matches^#[^\u0000-\u0020]*(?![\s\S]))width(integer; required whentypeisviewport; 320 to 1920)height(integer; required whentypeisviewport; 240 to 1440)
steps(array of object (5 shapes); required whentypeissequence; 1 to 6 items)type(string; required; one ofclick,fill,scroll,navigate,viewport)ref(string; optional; matches^e[1-9][0-9]*-[1-9][0-9]*$). Only whentypeisclickorfill. Control from the latest inspection. Send ref or label.label(string; optional; 1 to 160 characters). Only whentypeisclickorfill. The control’s exact label, ignoring case. Send ref or label. Replaces every earlier ref.role(string; optional; 1 to 40 characters). Only whentypeisclickorfill. With label: the control’s role, when several share the label.value(string; required whentypeisfill; at most 1024 characters)x(integer; required whentypeisscroll; -2000 to 2000). Horizontal scroll delta in pixels; use 0 for vertical scrolling.y(integer; required whentypeisscroll; -2000 to 2000). Vertical scroll delta in pixels.ref(string; optional; matches^e[1-9][0-9]*-[1-9][0-9]*$). Only whentypeisscroll. Current inspected element to scroll; omit to scroll the preview window.hash(string; required whentypeisnavigate; at most 512 characters; matches^#[^\u0000-\u0020]*(?![\s\S]))width(integer; required whentypeisviewport; 320 to 1920)height(integer; required whentypeisviewport; 240 to 1440)
What next
Section titled “What next”- MCP scopes and permissions — what each scope grants, and how a refusal for a missing scope looks.
- MCP results and errors — the shape of a tool result and of a refused call.
- Query governed data with MCP — the order to call the query tools in.