Analytics Building Guide

This guide is the short path to a working Analytics page. Analytics explains the parts, and every endpoint name below links to its reference page.

The recommended path

1. Check where you are acting. Who Am I? answers the organization your requests act on and the permissions your key has there.
2. Find the data. List Analytics Data Sources first: reuse a source that already fetches what you need. Otherwise find the app with List Universal Apps, its read action with List Universal Actions, and a connection with List Connections.
3. Create the source with Create Analytics Data Source. Its first fetch starts at once; Get Analytics Data Source Result answers its status and rows.
4. Look at the rows with Query Analytics Data Source: run the SQL a panel will run before you build the panel.
5. Create the page with Create Analytics Page.
6. Build it in one call with Set Analytics Page Definition: its variables, tabs and every panel, with their SQL, display and clicks. Give each new panel a ref and name it by that ref anywhere in the same body. It is all or nothing, and a refusal lists every problem with its JSON Pointer into your body. Check a body first, without saving it, with Validate Analytics Page Definition.
7. Check each panel with Get Analytics Panel Output: its status, rows and any failure.
8. Publish with Publish Analytics Page, then share it with Create Analytics Page Share or send it on a schedule with Create Analytics Publication.

What to know

Revisions

Every change to a page's draft needs the revision you last read in the If-Match header, sent as "r_...", as workflow drafts do: page settings, variables, tabs, layout, panels, undo and redo, publish, discard and restore. Get Analytics Page with version=draft and Get Analytics Page Definition answer it as revision, and in the ETag header. A change answers the new one in meta.revision, so you can send it straight back with the next change. A 412 means the draft changed since you read it, in the app, through Cirra or through the API: read it again and retry; error.details.revision is the current one.

A definition you read can be sent back as it is, and it changes nothing; within a panel, only what differs from the draft is written, and null on a field that holds a value clears it. A panel you leave out is deleted.

Panel SQL

A panel's dataSources entry runs DuckDB SQL over the source's rows, with its alias as the table name: SELECT region, sum(total) AS total FROM orders GROUP BY 1. Filter, group and sort in SQL; use transformCode only for what SQL cannot do. Then map the columns in the display type's settings: Analytics Display Types lists every type and what it takes. A bar chart, for example, is { "displayType": "bar", "settings": { "chart": { "xKey": "month", "series": [{ "key": "orders" }] } } }. A page variable is $name in the SQL, and a date variable filters each source's date column unless the entry sets followPageDate: false.

Drill-downs and subpages

A click opens a drill-down panel on the same page: give the target placement: "drill" and wire the click with on, such as { "rowClick": { "action": "drillDown", "panelId": "<id or ref>" } }. Every $name the target's SQL reads takes the clicked row's field of the same name; rename a field in the clicking panel's SQL (SELECT owner_id AS userId) when the names differ. To open a whole page instead, use Create Analytics Subpage, which makes the page and wires the click together.

Incremental refreshes

A sync source made through the API refreshes in full on its schedule. Fetching only changed records stays off unless you turn it on with Update Analytics Data Source: send incrementalDetails (the fields that identify a record and the arguments that ask the app for changes since the last check) with isIncrementalEnabled: true.

Real side effects

Send Analytics Publication sends for real. Sharing with a guest, and publication recipients outside your organization, email people outside it. Fetching a source calls the app with its connection.

Published embeds

A change that deletes a panel or tab that a published embed shows needs confirming, as in the app. The first request answers 409 with the affected embeds and a confirmationReceipt in error.details; send the same request again with that receipt to confirm.