What is KPI Studio?
KPI Studio is where you define metrics of your own. A KPI collection groups metrics and dimensions that belong together. Each metric holds one definition and the dimensions it can be split and filtered by. The studio is the editor for one metric. It shows the definition in the middle and the tables of your warehouse on the right, and a dry run tests the definition.
The page KPI collections lists every collection of your space. Each one shows its status (Active, Deprecated or Draft) and whether it is Managed or Custom. It also shows how many metrics and dimensions the collection holds, and its version.
Collections that come with an integration are built and maintained by Indicate and cannot be changed. A collection you create is custom, and you are responsible for its definitions and dimensions. See Metrics.
When do I need this?
The managed integration does not deliver the number you need, for example a metric that combines fields in your own way.
You want a definition of your own, for example what counts as a qualified request in your business.
You need a metric on data that only exists in your warehouse, for example an imported file.
You uploaded your own data and want AI assistants to read it. AI assistants see Insights, never raw tables, so a metric is the way in.
Before you start
You need the role User or higher, and a plan that includes custom metrics.
The data has to be in your warehouse. Check it in
Data Studio, see Data Studio.A metric is not written in SQL but as declarative JSON in the DSL of the semantic layer, which compiles into a query. Every metric filters on _connection_id, so it returns data for one source connection only. The language reference is at docs.indicate-data.io/reference/semantic-layer.
Let an AI assistant write the definition
The plugin data-max holds three skills that take an AI assistant from a raw export to a finished definition:
data-review: Checks a raw export (CSV, TSV, JSON, XML or Excel) and reports how to clean it for a warehouse. It never changes your data.
data-transform: Carries out that review and turns the file into clean tables, ready for the warehouse.
metric-creator: Builds metric and dimension definitions in the DSL on top of clean data. It writes versioned JSON files for the metrics and a file dimensions.md with the matching dimensions.
To install it in Claude Code, run /plugin marketplace add insanetic/data-max, then /plugin install data-max@data-max. For other AI assistants, copy the folders from skills/ into the skills folder of your assistant.
metric-creator needs the DDL of your tables. In
Data Studio, open the table, click More actions, then Show DDL, and copy the CREATE TABLE statement.
How do I create a KPI collection?
Open
Data sourcesāKPI declarationāKPI Studio.Click New KPI collection at the top right.
Enter a Display name, for example Commerce core, and optionally a Description.
Click Create.
The new collection appears in the list. Click it to open it. A collection has the tabs Metrics, Dimensions, Sharing and Settings.
How do I create a metric?
Open the collection. The tab Metrics opens.
Click New metric.
Enter a Display name, for example Booking rate, and optionally a Description.
Click Create.
The studio opens with the new metric as Draft. On the left are Metadata, DSL editor, Grouping dimensions and Perspective dimensions. The editor is in the middle, and the panel Data warehouse on the right shows the schemas and tables of your space.
To open an existing metric later, hover over it on the tab Metrics and click Edit in studio. The three-dot menu ā® of a metric also offers Duplicate to copy it into this or another collection.
How do I write and test the definition?
Click DSL editor and write the definition in the editor. To start from another metric, click Import at the top and pick its collection and metric.
Expand the schemas in the panel Data warehouse on the right to check the exact names of tables and columns. Schema at the top shows or hides the panel.
Click Dry run. If the studio says Save the metric first to preview it, click Save and then Dry run again.
Check the result at the bottom. The tabs Preview, Chart, Table and Emulated show the result in different ways. Change Time range, Group by time, Insights and Group by to see how the metric behaves. These settings are only for testing.
If the definition fails, the error appears with the statement that caused it.
What are grouping and perspective dimensions?
Both are dimensions, but they do different jobs:
Grouping dimensions: Decide how the data is split. They go into the GROUP BY of the query, for example the channel on the x axis.
Perspective dimensions: Decide which data is included. They go into the filters, for example whether a time range filters by booking date or by arrival date.
Every metric needs at least one of each. If the definition returns a column that no dimension maps to, the metric fails to run. See Grouping and perspective for how they show up in a widget.
How do I add a dimension to a metric?
In the studio, click Add dimension under Grouping dimensions or Perspective dimensions.
Option 1: Link a dimension the collection already has
Click Link existing dimension. The dialog Link existing dimensions opens.
Tick one or more dimensions, or click Select all.
Click Link dimension. With several dimensions ticked, the button names their number.
Option 2: Create a new dimension
Click Create dimension. The dialog New dimension opens.
Enter a Display name, for example Channel. Users see this name.
Under Scope, click Grouping or Perspective. The section you started in is preselected.
Under Semantic type, click Categorical for values such as channel or country, or Temporal for dates and times. Time ranges and time grouping work on temporal dimensions.
Under Physical mapping, enter the Identifier, the exact name of the column, and the Alias, the name the column has in your definition. To pick the column instead of typing it, click Browse schema.
Optionally, under Qualifier, enter the Table and Schema, so the column is fully qualified. Use the same table as in the $from of your definition.
Click Create.
A typo in Identifier or Alias is the most common reason a metric does not run. If metric-creator built the definition, take both from the file dimensions.md it wrote.
The tab Dimensions of the collection lists every dimension with its scope, type, column and the metrics that use it. Click Edit on a row to change a dimension. The three-dot menu ā® of a row offers Add to metrics, Duplicate and Delete. The filters In use, Unused and Unavailable find dimensions that no metric uses.
How do I save and publish a metric?
Click Save at the top, or press ā + S on macOS or Ctrl + S on Windows. A saved metric stays a Draft until you publish it. Only a published metric can be used in dashboards and Insights.
Publishing cannot be undone. A published metric never goes back to draft, and the only way back is to delete it. Its dimensions also become visible to other spaces that have access to the collection.
Click Publish at the top of the studio. The dialog Publish metric opens.
Turn on I understand publishing cannot be undone.
Click Publish permanently.
The status of the metric changes from Draft to Active. To use it in widgets, in the chat with Resi and in AI assistants, publish the collection as an Insight. See Publish a KPI collection as an Insight.
How do I share a KPI collection with another space?
A shared collection is read-only for the other space. It can browse the collection and publish its own Insights on it, but cannot change or share it further. Sharing a collection shares the definitions, not the data. To give another space your numbers, share the Insight instead, see Share Insights.
Open the collection and click the tab Sharing.
Click Share with a space. The dialog Share KPI collection opens.
Under Space, pick the space. Only spaces you have access to are listed.
Click Share. The space gets access right away.
To take the access away again, click Remove next to the space and confirm with Remove access. Publish to every space at the top of the tab makes the collection visible to every space on the platform. It is separate from the list of spaces, so turning one off leaves the other as it is.
Troubleshooting
Why does the dry run fail with Failed to execute KPI collection query?
In most cases an alias or a table in the definition does not exist. The error under the editor shows the query that was generated.
Compare Alias and Identifier of every dimension with the names in your definition. Correct them with Edit on the tab Dimensions and click Dry run again.
Why is a table in my definition not found?
- Open the dimension, and under Qualifier, set Table and Schema so the column is fully qualified. The table has to match the $from of your definition. Look the table up in the panel Data warehouse.
Which column name do I have to use?
- Expand the schema in the panel Data warehouse, or open the table in
Data Studioand click Schema. InData Studio, More actions and then Show DDL shows the whole CREATE TABLE statement.
Why does my metric return no data?
- Check that the definition filters on _connection_id, and that the Insight built on the collection has a source connection.
Why doesn't my metric appear in a widget?
The metric is still a Draft. Publish it in the studio.
The collection is not published as an Insight yet. See Publish a KPI collection as an Insight.
Why can't I create or edit metrics?
Creating and editing needs the role User or higher and a plan that includes custom metrics.
Managed collections and collections another space shared with you are read-only.