Run a SQL analysis

← Analyze

Use SQL when you need to inspect source data or answer a question that does not yet have a metric. You need the Explorer role or higher, a Connector, and a warehouse identity that can read the referenced sources. Catalog helps you discover names for a query; its selection does not limit the sources that the Connector identity can read.

SQL runs with the Connector account’s permissions, including when an Agent submits it. Use a dedicated read-only warehouse account. If it has write permissions, Explorers and their Agents can modify data; Monomer does not guarantee read-only access. Ask the warehouse administrator to deny procedure, pass-through, and remote/external function privileges as described in Prepare the source.

Run a small query

Open Explore → SQL and select the intended connector.
Check the schema and table names in Catalog.
Enter SQL in the source’s dialect. For a PostgreSQL table named analytics.orders, this example reads a bounded sample:

SELECT order_id, ordered_at, amount
FROM analytics.orders
ORDER BY ordered_at DESC
LIMIT 20

Replace the table and column names with ones that exist in your connector, then select Run.
Wait for the run to complete and inspect the returned columns and rows. Check the connector and query recorded with the run.

Use a small scope when exploring unfamiliar data. A connector credential may have different source-side permissions from your personal warehouse login.

Discover the Workspace and connector IDs, read workspace, and follow its availableOperations to list workspace/explore/runs. Send the advertised SQL_EXPLORE_RUN entry to monomer_describe before constructing the call, then call monomer_invoke. The SQL text is input.sql; the SQL_EXPLORE_RUN input does not use a query object.

monomer_invoke input

{
  "workspaceId": "0198ef28-2000-7000-8000-000000000001",
  "path": "workspace/explore/runs",
  "action": "run",
  "input": {
    "kind": "SQL_EXPLORE_RUN",
    "connectorId": "0198ef28-2000-7000-8000-000000000002",
    "sql": "SELECT order_id, ordered_at, amount FROM analytics.orders ORDER BY ordered_at DESC LIMIT 20"
  }
}

Replace the illustrative IDs and source names. Read the returned run path until it finishes, then follow its result path. An accepted run is not yet a successful query.

If execution fails

If a query is denied, verify that you have the Explorer role or higher and that the Connector’s warehouse identity has the required grants. For missing relations, verify exact source names and refresh Catalog after a schema change. Monomer does not add per-table or per-metric grants; the warehouse still enforces its own restrictions.

Before a run is accepted, warehouse permission denial returns PERMISSION_DENIED with HTTP 409 (Agent CONFLICT) and retryable=false. Check the Connector account’s grants before submitting again. SQL validation rejection (RAW_SQL_VALIDATION_REJECTED) and a read-only transaction violation (READ_ONLY_VIOLATION) also return 409 without automatic retry; use the returned safe explanation to correct the SQL or warehouse configuration. When Monomer cannot finish validating the SQL, the Problem code names the cause. These failures return 503:

Code	`retryable`	Next step
`CONNECTION_FAILED`	`true`	Check the Connector connection settings and warehouse availability before trying again.
`CREDENTIAL_UNAVAILABLE`	`true`	Check the Connector credentials before trying again.
`AUTHENTICATION_FAILED`	`false`	Update the Connector credentials before trying again.
`RAW_SQL_VALIDATION_DEADLINE_EXCEEDED`	`true`	Validation timed out; try again. This code does not identify whether the delay was in Monomer or the warehouse.
`RESOURCE_EXHAUSTED`, `RAW_SQL_VALIDATION_FAILED`	`true`	Validation is temporarily unavailable; try again.

When Monomer’s own query service is temporarily unavailable, agents receive OWNER_UNAVAILABLE with 503 and retryable=true, and the app says you can try the request again. This is a Monomer service failure; changing the Connector is not the suggested repair. A rejection before acceptance creates no run to poll. MCP returns the same Problem code, status, explanation, and retry policy as Agent REST in its error tool result; see Errors.

If the warehouse denies permission after the run has been accepted, the run finishes as FAILED with failureCode=PERMISSION_DENIED and a safe warehouse explanation in failureDetail. Correct the warehouse grants before starting another run.

If Monomer can’t reach the warehouse after the run has been accepted, the run finishes as FAILED with failureCode=CONNECTION_FAILED. If the warehouse rejects the Connector’s sign-in, it finishes with failureCode=AUTHENTICATION_FAILED. Both carry the safe warehouse explanation in failureDetail; check the Connector’s connection settings or credentials before starting another run. Other warehouse failures finish with failureCode=EXECUTION_FAILED.

For cancellation, previous runs, and downloads, continue with Work with results. If you repeat the same business calculation, define a metric so others can reuse its meaning.