Datasets and charts

A view declared in your App's analytics.json is registered as a dataset for the tenant at deploy, and shows up in the tenant's Analytics Studio: in the dataset picker, in the chart builder, and in cohorts.

This page is what your declaration looks like from the other side.

In the catalog

The operator sees your title and description. That is the whole of the first impression, and two things follow:

• A missing title means the view name is humanised. stock_levels becomes "Stock levels", which is acceptable, and "Stock levels per location, current" is better.
• The description is where the grain goes. "One row per location" or "One row per movement" is the sentence that stops somebody averaging the wrong thing. Nothing else in the interface tells them.

Your datasets sit alongside whatever the platform's own apps register, under a name namespaced by your vendor and app — so there is no collision, and no ambiguity about whose data an operator is looking at.

In the chart builder

An operator picks a dataset, then picks what to plot. What they are offered comes from your roles:

Which is why declaring roles matters more than any other line in the file. Concretely:

• No time role — no date scoping and no trend. The dataset becomes a table to stare at.
• No measures — nothing to plot. The studio's type heuristic may find a numeric column, and it may find the wrong one.
• UUIDs as dimensions — a group-by over values nobody recognises. Resolve the label with a relation or reference locator and declare that instead.
• A free-text column as a dimension — as many buckets as there are rows.

Columns that are not roles

A column can be in the view without being a measure or a dimension, and often should be: a code, a label, a name that lets somebody recognise a row when they look at the underlying data. Declare those; just do not declare them as dimensions.

The reverse also holds — nothing forces you to expose a column at all. Every operator with Analytics Studio access for the tenant can see every column of every registered dataset, so the decision about what to include is a disclosure decision. See Tenant isolation.

What an operator cannot do

Worth knowing, because it is what they will ask you for:

• They cannot define a metric with a formula and save it for reuse. There is no metric-definition surface and no API for one.
• They cannot build a funnel.
• They cannot schedule a chart to be delivered anywhere.
• They cannot embed a chart in another product, yours included. No embed, no guest token.

If the customer needs any of that, it is something you build on your own store. See What does not exist yet.

The test for a good dataset

Before you ship a view, read its roles back as a sentence — sum of MEASURES by DIMENSIONS over TIME, per ENTITY — and ask whether that is a question the customer's staff actually asks. If it is not, the view is the wrong shape, and no amount of chart building will fix it.

Where to go next

• Semantic roles — the four roles in detail.
• Cohorts — the one feature with a hard requirement.
• Example — a view whose roles read as a sensible question.