Analytics APIs

An Analytics API is a saved query contract over one data model. It can be previewed in the console and executed by approved query identities after publication.

The model may be owned by the current project or supplied through an active read-only Shared Dataset connection. For a shared model, ReportPlane fixes execution to the Dataset source warehouse while the consumer project owns the Analytics definition, allowed filters, visualization, clients, and API keys.

Create an Analytics API#

Open Analytics → APIs → New Analytics API.

1. Choose the data model.
2. Enter a clear name, stable key, and description.
3. Select the chart type.
4. Add dimensions and metrics.
5. Add required filters that must apply to every execution, when needed.
6. Choose request-time filter fields and allowed operators.
7. Optionally enable Latest row per entity for append-only state or revision streams.
8. Configure output order and limit.
9. Review visualization settings.
10. Select the destination binding and cache behavior.
11. Preview, then publish when the output is ready for consumers.

latest_by is part of the saved Analytics contract, not an ingest update operation. See Latest row per entity for partition, ordering, tie-breaker, and filter semantics.

Stable keys and aliases#

The public /query request refers to an Analytics API by its key or supported internal reference. Use a stable key in application code.

Dimension and metric aliases become output keys. Choose aliases that will remain meaningful to consumers, such as request_count rather than a temporary UI label.

Load example#

The create and edit builders can load a deterministic example for the selected chart type. The helper chooses compatible model fields and fills dimensions, metrics, filters, order, limit, and visualization metadata.

It changes the current draft only. It does not save or publish automatically. If the model lacks a required field shape—such as two numeric metrics for a scatter chart—the builder explains the incompatibility without replacing the draft.

For a map example, the model must expose clearly named numeric latitude and longitude fields. The builder selects them as result dimensions and creates portable visualization.map metadata; it does not generate warehouse-specific spatial SQL.

Preview and publication#

Preview uses the analytics runtime through the authenticated playground endpoint. A newly saved definition may require a short retry while runtime snapshots refresh.

Publication is the explicit signal that a definition is ready for normal query clients. Continue to restrict access through query clients or API keys.

Share one Analytics view#

An enabled, published Analytics API can also be exposed through an unlisted, read-only share link. Open the Analytics API and select Share, then optionally add password protection. The share preserves the saved filters, limits, binding, cache policy, visualization, and runtime execution contract; it does not expose the warehouse or grant project access.

See Analytics sharing for recipient capabilities, password grants, revocation, privacy behavior, and the distinction from Shared Datasets.

Edit and archive#

Editing a published definition can change output columns, filter behavior, or visualization metadata. Treat those changes like an API release. Existing required filters are loaded into the edit builder and remain part of the definition unless you explicitly change or remove them.

Delete from the console archives the definition through the management service. Check query-client access and application dependencies first.