ax insight
Manage org-scoped saved SQL insights.
Insights are saved SQL queries with a heading and an immutable slug. Create
them here, or from a query with --save on
experiment query /
run query. Listing never re-executes SQL; view and
export re-execute live against your org's uploaded results data.
| Command | Use |
|---|---|
insight list | List insights (metadata only). |
insight view | Re-execute one insight and show its rows. |
insight create | Create an insight from a heading and SQL. |
insight share | Publish a public capability URL for one insight. |
insight edit | Update heading, description, labels, or SQL. |
insight delete | Delete one insight. |
insight export | Write an insight's live result to a file. |
All commands accept --org <org-id>; list and view also accept --json.
Arguments marked required must be supplied; everything else is optional.
insight list
List insights: slug, heading, owner, labels, updated. No SQL runs.
ax insight list| Argument / flag | What it does |
|---|---|
--search <text> | Case-insensitive search over slug, heading, description, owner. |
--owner <user-id> | Filter by the original owner. |
--experiment <id> / --run <id> | Filter by provenance (where the insight was saved from). |
--label <label> | Require this label. |
--limit <n> | Max insights (default 50). |
insight view
Fetch one insight and re-execute its SQL live.
ax insight view <SLUG | ID>| Argument / flag | What it does |
|---|---|
<SLUG | ID> | Required. Insight slug or ins_... id. |
--sql | Print the stored SQL instead of executing. |
--limit <n> | Max rows (default 100, max 1000). |
insight create
Create an insight from a heading and SQL. The slug is minted from the heading and is immutable afterwards.
ax insight create "<HEADING>" --sql '<SQL>'| Argument / flag | What it does |
|---|---|
<HEADING> | Required. Human heading; also mints the slug unless --slug is given. |
--sql <SQL|@file|-> | Required. Inline SQL, @file.sql, or - for stdin. |
--slug <slug> | Explicit slug (kebab-case). A collision errors unless --force. |
--description <text> | Optional description. |
--label <label> | Labels to attach (repeatable). |
--force | Overwrite mutable content when the slug already exists. |
Example:
ax insight create "Cross-experiment cost" --sql @cost.sql --label finance
ax insight view cross-experiment-costinsight share
Print a stable public capability URL for one insight. The first share freezes the heading, description, query, analytical data family, and execution scope; later edits to the source insight do not change that snapshot. The public page still reruns the frozen query against live data, so rows can change. Repeated shares return the same URL. Deleting the source insight revokes the share.
ax insight share <SLUG | ID>| Argument / flag | What it does |
|---|---|
<SLUG | ID> | Required. Insight slug or ins_... id. |
insight edit
Update an insight's mutable fields. The slug never changes.
ax insight edit <SLUG | ID>| Argument / flag | What it does |
|---|---|
<SLUG | ID> | Required. Insight slug or ins_... id. |
--heading <text> | New heading. |
--description <text> | New description; pass an empty string to clear. |
--label <label> | Replace the label set (repeatable); --clear-labels clears it. |
--sql <SQL|@file|-> | New SQL. |
insight delete
Delete one insight by slug or id. No confirmation prompt.
ax insight delete <SLUG | ID>insight export
Re-execute an insight once and write the result to a file.
ax insight export <SLUG | ID> <PATH>| Argument / flag | What it does |
|---|---|
<SLUG | ID> | Required. Insight slug or ins_... id. |
<PATH> | Required. Destination file; overwritten if it exists. |
--format <fmt> | csv, json, tsv, or md. Inferred from the extension when omitted. |
--limit <n> | Max rows (default 100, max 1000). |